MariaDB SkySQL customers should assess the availability requirements of their application and choose an appropriate service tier to meet their objectives. MariaDB SkySQL customers are on the Foundation Tier unless they have specifically purchased and paid for Power Tier service.
+| Tier | +Performance Standard | +
|---|---|
| SkySQL Foundation Tier | +ā¢ Multi-node configurations will deliver a 99.95% service availability on a per-billing-month basis. | +
| ā¢ For example, with this availability target in a 30 day calendar month the maximum service downtime is 21 minutes and 54 seconds. | ++ |
| SkySQL Power Tier | +ā¢ Multi-node configurations will deliver a 99.995% service availability on a per-billing-month basis. | +
| ā¢ For example, with this availability target in a 30 day calendar month the maximum service downtime is 2 minutes and 11 seconds. | ++ |
Service DowntimeĀ is measured at each SkySQL database endpoint as the total number of full minutes, outside of scheduled downtime for maintenance and upgrades, where continuous attempts to establish a connection within the minute fail as reflected in minute-by-minute logs.
+Monthly Uptime PercentageĀ is calculated on a per-billing-month basis as the total number of minutes in a month, minus the number of minutes of measuredĀ Service DowntimeĀ within the month, divided by the number of minutes in that month. When a service is deployed for only part of a month, it is assumed to be 100% available for the portion of the month that it is not deployed.
+Service CreditĀ is the percentage of the total fees paid by you for a given SkySQL service during the month in which the downtime occurred to be credited if MariaDB approves your claim. The percentage used in calculating Service Credit is dependent on whether the customer is on Foundation Tier or Power Tier, and is dependent on the calculatedĀ Monthly Uptime Percentage.
+| Tier | +Monthly Uptime Percentage | +Percentage Applied | +
|---|---|---|
| Foundation Tier | +Less than 99.95%, but greater than or equal to 99.0% | +10% | +
| Foundation Tier | +Less than 99.0% | +25% | +
| Power Tier | +Less than 99.995%, but greater than or equal to 99.0% | +10% | +
| Power Tier | +Less than 99.0% | +25% | +
MariaDB will grant and process claims, provided the customer has satisfied itsĀ Customer ObligationsĀ and that none of theĀ ExclusionsĀ listed apply to the claim.Ā Service CreditsĀ will be issued only upon request within 60 days of the end of the billing period of the month of impact to service availability, and upon confirmation of outage.Ā Service CreditsĀ will be issued in the form of a monetary credit applied to future use of the service that experienced theĀ Service Downtime.Ā Service CreditsĀ will not be applied to fees for any other SkySQL instance.
+The aggregate maximum number ofĀ Service CreditsĀ to be issued by MariaDB to customers for any and allĀ Service DowntimeĀ that occurs in a single billing month will not exceed 50% of the amount due from the customer for the covered service for the applicable month.
+A customer will forfeit their right to receive aĀ Service CreditĀ unless they:
+Out-of-scope configurations
+TheĀ Performance StandardĀ does not apply to single instance SkySQL service configuration or services in Technical Preview. Customers requiring High Availability should deploy instead in production-ready multi-node service configuration.
+See "Choose a SkySQL Release" for information on SkySQL services in Technical Preview.
+Underlying infrastructure
+Impact to service availability caused by availability or performance of cloud services used to operate MariaDB SkySQL is excluded. This includes any such outages in Amazon Web Services (AWS) and Amazon Elastic Kubernetes Service (EKS), and Google Cloud Platform (GCP) and Google Kubernetes Engine (GKE).
+Network interruption
+Impact to service availability caused by blocking of network traffic by ISPs, network providers, governments, or third parties is excluded.
+External factors
+Impact to your use of service based on factors outside MariaDB SkySQL are excluded. This includes periods of downtime for your applications.
+Uncorroborated impacts
+Only impacts to service availability detected atĀ point of measurementĀ are subject when determining the uptime percentage. Service availability impacts measured through any other means, such as application instrumentation, are excluded except as also measured asĀ Service DowntimeĀ by MariaDB.
+Portal access
+Impact to your ability to access or use the MariaDB SkySQL portal, an interface provided to manage services, is excluded. This includes any component and content linked from the MariaDB SkySQL portal, including Documentation, the Customer Support portal, Monitoring, and Workload Analysis. These components operate independently from database services and do not impact database availability.
+Resource usage
+Impact to service availability caused by usage of system resources, such as problems caused by excessive workload consumption of CPU, disk I/O, disk capacity, memory, and other system resources, are excluded.
+Clients and connectors
+Impact to service availability caused by the use of unsupported third-party clients and connectors is excluded.
+Non-paying customers
+TheĀ Performance StandardĀ applies only to paying MariaDB SkySQL customers who are paid-in-full. All other MariaDB SkySQL customers, including those not paid-in-full and those customers participating in a free or credited service trial, are excluded.
+Customer-directed maintenance
+When a customer directs that MariaDB conduct a maintenance operation on a service, any resulting impact to service availability is excluded.
+Customer-approved maintenance
+When a customer approves MariaDB-recommended maintenance on a service, any resulting impact to service availability is excluded.
+Customer-initiated changes
+When a customer initiates changes to their SkySQL services, e.g., via access to the database or via the SkySQL portal, any resulting impact to service availability is excluded.
+Initial provisioning
+Availability of services during initial provisioning, e.g., before a service becomes online, healthy, and available, is excluded.
+Autonomous features enable automatic scaling in response to changes in workload.
+Auto-scale of nodes enables scaling based on load:
+Auto-scale of storage enables expansion of capacity based on usage.
+Autonomous features can be enabled at time ofĀ service launch. Autonomous features can be enabled or disabled after launch.
+
Auto-scaling of nodes can be enabled either at time of service launch or after service launch.
+DuringĀ service launch:
+After service launch,Ā manage Autonomous settings, and enable the desired auto-scaling features.
+Auto-scaling of storage can be enabled either at time of service launch or after service launch.
+DuringĀ Service Launch:
+After service launch,Ā manage Autonomous settings, and enable the desired auto-scaling features.
+For ColumnStore Data Warehouse, object storage adjusts automatically. Autonomous scaling features for storage are not used by this topology.
+To manage Autonomous settings:
+Automatic scaling occurs based on rules.
+| Policy | +Condition | +Action | +
|---|---|---|
| Auto-Scale Disk | +Disk utilization > 90% sustained for 5 minutes. The disk is expected to run out of capacity in the next 24 hours (predicted based on the last 6 hours of service usage). |
+Upgrade storage to the next available size in 100GB increments. Note: you cannot downgrade storage, the upgrade is irreversible |
+
| Auto-Scale Nodes Out | +CPU utilization > 75% over all replicas sustained for 30 minutes. Number of concurrent sessions > 90% over all replicas sustained for 1 hour. Number of concurrent sessions is expected to hit the maximum within 4 hours (predicted based on the last 2 hours of service usage) |
+Add new replica or node Additional nodes will be of the same size and configuration as existing nodes | +
| Auto-Scale Nodes In | +CPU utilization < 50% over all replicas sustained for 1 hour. Number of concurrent sessions < 50% over all replicas sustained for 1 hour |
+Remove replica or node Node count will not decrease below the initial count set at launch | +
| Auto-Scale Nodes Up | +Number of concurrent sessions is expected to hit the maximum within 4 hours (predicted based on the last 2 hours of service usage) | +Upgrade all nodes to the next available size | +
| Auto-Scale Nodes Down | +CPU utilization < 50% over all replicas sustained for 1 hour. Number of concurrent sessions < 50% over all replicas sustained for 1 hour |
+Downgrade nodes Node size will not decrease below the initial node size set at launch | +
Autonomous actions are not instantaneous.
+Cooldown periods may apply. A cooldown period is the time period after a scaling operation is completed before another scaling operation can occur. The cooldown period for storage scaling is 6 hours.
+ + + + + + + + + + + + + + +Regular and reliable backups are essential to successful recovery of mission critical applications.Ā MariaDB Enterprise ServerĀ backup and restore operations are performed usingĀ MariaDB Enterprise Backup, anĀ enterprise-buildĀ ofĀ MariaDB Backup.
+MariaDB Enterprise BackupĀ is compatible with MariaDB Enterprise Server 10.2, 10.3, 10.4, 10.5, and 10.6.
+MariaDB Enterprise Backup creates a file-level backup of data from the MariaDB Enterprise Server data directory. This backup includesĀ temporal data, and the encrypted and unencrypted tablespaces of supported storage engines (e.g.,Ā InnoDB,Ā MyRocks,Ā Aria).
+MariaDB Enterprise Server implements:
+Backup support is specific to storage engines. All supported storage engines enable full backup. The InnoDB storage engine additionally supports incremental backup.
+A feature of MariaDB Enterprise Backup and MariaDB Enterprise Server, non-blocking backups minimize workload impact during backups. When MariaDB Enterprise Backup connects to MariaDB Enterprise Server, staging operations are initiated to protect data during read.
+Non-blocking backup functionality differs from historical backup functionality in the following ways:
+FLUSHĀ TABLESĀ WITHĀ READĀ LOCK, which closed open tables and only allowed tables to be reopened with a read lock during the duration of backups.MariaDB Enterprise Backup creates complete or incremental backups of MariaDB Enterprise Server data, and is also used to restore data from backups produced using MariaDB Enterprise Backup.
+Full backups produced using MariaDB Enterprise Server are not initially point-in-time consistent, and an attempt to restore from a raw full backup will cause InnoDB to crash to protect the data.
+Incremental backups produced using MariaDB Enterprise Backup contain only the changes since the last backup and cannot be used standalone to perform a restore.
+To restore from a backup, you first need to prepare the backup for point-in-time consistency using theĀ --prepareĀ command:
-prepareĀ command on aĀ full backupĀ synchronizes the tablespaces, ensuring that they are point-in-time consistent and ready for use in recovery.-prepareĀ command on anĀ incremental backupĀ synchronizes the tablespaces and also applies the updated data into the previous full backup, making it a complete backup ready for use in recovery.-prepareĀ command on data that is to be used for aĀ partial restoreĀ (when restoring only one or more selected tables) requires that you also use theĀ -exportĀ option to create the necessaryĀ .cfgĀ files to use in recovery.When MariaDB Enterprise Backup restores from a backup, it copies or moves the backup files into the MariaDB Enterprise Server data directory, as defined by theĀ datadirĀ system variable.
For MariaDB Enterprise Backup to safely restore data from full and incremental backups, the data directory must be empty. One way to achieve this is to move the data directory aside to a unique directory name:
+/var/lib/mysql-2020-01-01)Ā ORĀ remove the old data directory (depending on how much space you have available).mkdirĀ /var/lib/mysql).chownĀ -RĀ mysql:mysqlĀ /var/lib/mysql).When MariaDB Enterprise Backup performs a backup operation, it not only copies files from the data directory but also connects to the running MariaDB Enterprise Server.
+This connection to MariaDB Enterprise Server is used to manage locks and backup staging that prevent the Server from writing to a file while being read for a backup.
+MariaDB Enterprise Backup establishes this connection based on the user credentials specified with theĀ --userĀ andĀ --passwordĀ options when performing a backup.
It is recommended that a dedicated user be created and authorized to perform backups.
+MariaDB Enterprise Backup 10.5 and later requires this user to have theĀ RELOAD,Ā PROCESS,Ā LOCKĀ TABLES, andĀ BINLOGĀ MONITORĀ privileges. (TheĀ BINLOG MONITORĀ privilege replaced theĀ REPLICATIONĀ CLIENTĀ privilege in MariaDB Enterprise Server 10.5.):
**CREATE** **USER** 'mariabackup'@'localhost'IDENTIFIED **BY** 'mbu_passwd'**;GRANT** RELOAD**,** PROCESS**,** **LOCK** TABLES**,** BINLOG MONITOR**ON** ***.*****TO** 'mariabackup'@'localhost'**;**
In the above example, MariaDB Enterprise Backup would run on the local system that runs MariaDB Enterprise Server. Where backups may be run against a remote server, the user authentication and authorization should be adjusted.
+While MariaDB Enterprise Backup requires a user for backup operations, no user is required for restore operations since restores occur while MariaDB Enterprise Server is not running.
+MariaDB Enterprise Backup 10.4 and earlier requires this user to have theĀ RELOAD,Ā PROCESS,Ā LOCKĀ TABLES, andĀ REPLICATIONĀ CLIENTĀ privileges. (TheĀ BINLOG MONITORĀ privilege replaced theĀ REPLICATIONĀ CLIENTĀ privilege in MariaDB Enterprise Server 10.5.):
**CREATE** **USER** 'mariabackup'@'localhost'IDENTIFIED **BY** 'mbu_passwd'**;GRANT** RELOAD**,** PROCESS**,** **LOCK** TABLES**,** REPLICATION CLIENT**ON** ***.*****TO** 'mariabackup'@'localhost'**;**
In the above example, MariaDB Enterprise Backup would run on the local system that runs MariaDB Enterprise Server. Where backups may be run against a remote server, the user authentication and authorization should be adjusted.
+While MariaDB Enterprise Backup requires a user for backup operations, no user is required for restore operations since restores occur while MariaDB Enterprise Server is not running.
+Full backups performed with MariaDB Enterprise Backup contain all table data present in the database.
+When performing a full backup, MariaDB Enterprise Backup makes a file-level copy of the MariaDB Enterprise Server data directory. This backup omits log data such as the binary logs (binlog), error logs, general query logs, and slow query logs.
+When you perform a full backup, MariaDB Enterprise Backup writes the backup to theĀ --target-dirĀ path. The directory must be empty or non-existent and the operating system user account must have permission to write to that directory. A database user account is required to perform the backup.
The version ofĀ mariabackupĀ orĀ mariadb-backupĀ should be the same version as the MariaDB Enterprise Server version. When the version does not match the server version, errors can sometimes occur, or the backup can sometimes be unusable.
To create a backup, executeĀ mariabackupĀ orĀ mariadb-backupĀ with theĀ [--backup](https://mariadb.com/docs/server/ref/mdb/cli/mariadb-backup/backup/)Ā option, and provide the database user account credentials using theĀ [--user](https://mariadb.com/docs/server/ref/mdb/cli/mariadb-backup/user/)Ā andĀ [--password](https://mariadb.com/docs/server/ref/mdb/cli/mariadb-backup/password/)Ā options:
$ sudo mariabackup --backup \ --target-dir=/data/backups/full \ --user=mariabackup \ --password=mbu_passwd
Subsequent to the above example, the backup is now available in the designatedĀ --target-dirĀ path.
A raw full backup is notĀ point-in-time consistentĀ and must be prepared before it can be used for a restore. The backup can be prepared any time after the backup is created and before the backup is restored. However, MariaDB recommends preparing a backup immediately after taking the backup to ensure that the backup is consistent.
+The backup should be prepared with the same version of MariaDB Enterprise Backup that was used to create the backup.
+To prepare the backup, executeĀ mariabackupĀ orĀ mariadb-backupĀ with theĀ [--prepare](https://mariadb.com/docs/server/ref/mdb/cli/mariadb-backup/prepare/)Ā option:
$ sudo mariabackup --prepare \ --use-memory=34359738368 \ --target-dir=/data/backups/full
For best performance, theĀ [--use-memory](https://mariadb.com/docs/server/ref/mdb/cli/mariadb-backup/use-memory/)Ā option should be set to the server'sĀ [innodb_buffer_pool_size](https://mariadb.com/docs/server/ref/mdb/system-variables/innodb_buffer_pool_size/)Ā value.
Once a full backup has beenĀ preparedĀ to be point-in-time consistent, MariaDB Enterprise Backup is used to copy backup data to the MariaDB Enterprise Server data directory.
+To restore from a full backup:
+Restore from the "full" directory using theĀ -copy-backĀ option:
$ sudo mariabackup --copy-back --target-dir=/data/backups/full
MariaDB Enterprise Backup writes to the data directory as the current user, which can be changed usingĀ sudo. To confirm that restored files are properly owned by the user that runs MariaDB Enterprise Server, run a command like this (adapted for the correct user/group):
$ sudo chown -R mysql:mysql /var/lib/mysql
Once this is done, start MariaDB Enterprise Server:
+$ sudo systemctl start mariadb
When the Server starts, it works from the restored data directory.
+Full backups of large data-sets can be time-consuming and resource-intensive. MariaDB Enterprise Backup supports the use of incremental backups to minimize this impact.
+While full backups are resource-intensive at time of backup, the resource burden around incremental backups occurs when preparing for restore. First, the full backup is prepared for restore, then each incremental backup is applied.
+When you perform an incremental backup, MariaDB Enterprise Backup compares a previous full or incremental backup to what it finds on MariaDB Enterprise Server. It then creates a new backup containing the incremental changes.
+Incremental backup is supported for InnoDB tables. Tables using other storage engines receive full backups even during incremental backup operations.
+To increment a full backup, use theĀ --incremental-basedirĀ option to indicate the path to the full backup and theĀ --target-dirĀ option to indicate where you want to write the incremental backup:
$ sudo mariabackup --backup \ --incremental-basedir=/data/backups/full \ --target-dir=/data/backups/inc1 \ --user=mariabackup \ --password=mbu_passwd
In this example, MariaDB Enterprise Backup reads theĀ /data/backups/fullĀ directory, and MariaDB Enterprise Server then creates an incremental backup in theĀ /data/backups/inc1Ā directory.
An incremental backup must be applied to a prepared full backup before it can be used in a restore operation. If you have multiple full backups to choose from, pick the nearest full backup prior to the incremental backup that you want to restore. You may also want to back up your full-backup directory, as it will be modified by the updates in the incremental data.
+If your full backup directory is not yet prepared, run this to make it consistent:
+$ sudo mariabackup --prepare --target-dir=/data/backups/full
Then, using the prepared full backup, apply the first incremental backup's data to the full backup in an incremental preparation step:
+$ sudo mariabackup --prepare \ --target-dir=/data/backups/full \ --incremental-dir=/data/backups/inc1
Once the incremental backup has been applied to the full backup, the full backup directory contains the changes from the incremental backup (that is, theĀ inc1/Ā directory). Feel free to removeĀ inc1/Ā to save disk space.
Once you have prepared the full backup directory with all the incremental changes you need (as described above), stop the MariaDB Enterprise Server,Ā emptyĀ its data directory, and restore from the original full backup directory using theĀ --copy-backĀ option:
$ sudo mariabackup --copy-back --target-dir=/data/backups/full
MariaDB Enterprise Backup writes files into the data directory using either the current user or root (in the case of a sudo operation), which may be different from the system user that runs the database. Run the following to recursively update the ownership of the restored files and directories:
+$ sudo chown -R mysql:mysql /var/lib/mysql
Then, start MariaDB Enterprise Server. When the Server starts, it works from the restored data directory.
+In a partial backup, MariaDB Enterprise Backup copies a specified subset of tablespaces from the MariaDB Enterprise Server data directory. Partial backups are useful in establishing a higher frequency of backups on specific data, at the expense of increased recovery complexity. In selecting tablespaces for a partial backup, please consider referential integrity.
+Command-line options can be used to narrow the set of databases or tables to be included within a backup:
+| Option | +Description | +
|---|---|
| --databases | +List of databases to include | +
| --databases-exclude | +List of databases to omit from the backup | +
| --databases-file | +Path to file listing the databases to include | +
| --tables | +List of tables to include | +
| --tables-exclude | +List of tables to exclude | +
| --tables-file | +Path to file listing the tables to include | +
For example, you may wish to produce a partial backup, which excludes a specific database:
+$ sudo mariabackup --backup \ --target-dir=/data/backups/part \ --user=mariabackup \ --password=mbu_passwd \ --database-exclude=test
Partial backups can also be incremental:
+$ sudo mariabackup --backup \ --incremental-basedir=/data/backups/part \ --target-dir=/data/backups/part_inc1 \ --user=mariabackup \ --password=mbu_passwd \ --database-exclude=test
As with full and incremental backups, partial backups are not point-in-time consistent. A partial backup must be prepared before it can be used for recovery.
+A partial restore can be performed from a full backup or partial backup.
+The preparation step for either partial or full backup restoration requires the use of transportable tablespaces for InnoDB. As such, each prepare operation requires theĀ --exportĀ option:
$ sudo mariabackup --prepare --export --target-dir=/data/backups/part
When using a partial incremental backup for restore, the incremental data must be applied to its prior partial backup data before its data is complete. If performing partial incremental backups, run the prepare statement again to apply the incremental changes onto the partial backup that served as the base.
+$ sudo mariabackup --prepare --export \ --target-dir=/data/backups/part \ --incremental-dir=/data/backups/part_inc1
Unlike full and incremental backups, you cannot restore partial backups directly using MariaDB Enterprise Backup. Further, as a partial backup does not contain a complete data directory, you cannot restore MariaDB Enterprise Server to a startable state solely with a partial backup.
+To restore from a partial backup, you need to prepare a table on the MariaDB Enterprise Server, then manually copy the files into the data directory.
+The details of the restore procedure depend on the characteristics of the table:
+As partial restores are performed while the server is running, not stopped, care should be taken to prevent production workloads during restore activity.
+Note
+You can also use data from a full backup in a partial restore operation if you have prepared the data using theĀ --exportĀ option as described above.
To restore a non-partitioned table from a backup, first create a new table on MariaDB Enterprise Server to receive the restored data. It should match the specifications of the table you're restoring.
+Be extra careful if the backup data is from a server with a different version than the restore server, as some differences (such as a differingĀ ROW_FORMAT) can cause an unexpected result.
Create an empty table for the data being restored:
+**CREATE** **TABLE** test**.**address_book **(** id INT **PRIMARY** **KEY** AUTO_INCREMENT**,** name VARCHAR**(**255**),** email VARCHAR**(**255**));**
Modify the table to discard the tablespace:
+**ALTER** **TABLE** test**.**address_book DISCARD TABLESPACE**;**
You can copy (or move) the files for the table from the backup to the data directory:
+$ sudo cp /data/backups/part_inc1/test/address_book.* /var/lib/mysql/test
Use a wildcard to include both theĀ .ibdĀ andĀ .cfgĀ files. Then, change the owner to the system user running MariaDB Enterprise Server:
$ sudo chown mysql:mysql /var/lib/mysql/test/address_book.*
Lastly, import the new tablespace:
+**ALTER** **TABLE** test**.**address_book IMPORT TABLESPACE**;**
MariaDB Enterprise Server looks in the data directory for the tablespace you copied in, then imports it for use. If the table is encrypted, it also looks for the encryption key with the relevant key ID that the table data specifies.
+Repeat this step for every table you wish to restore.
+Restoring a partitioned table from a backup requires a few extra steps compared to restoring a non-partitioned table.
+To restore a partitioned table from a backup, first create a new table on MariaDB Enterprise Server to receive the restored data. It should match the specifications of the table you're restoring, including the partition specification.
+Be extra careful if the backup data is from a server with a different version than the restore server, as some differences (such as a differingĀ ROW_FORMAT) can cause an unexpected result.
Create an empty table for the data being restored:
+**CREATE** **TABLE** test**.**students **(** id INT **NOT** **NULL** AUTO_INCREMENT**,** name VARCHAR**(**255**),** email VARCHAR**(**255**),** graduating_year **YEAR,** **PRIMARY** **KEY** **(**id**,** graduating_year**))** ENGINE = InnoDBPARTITION **BY** RANGE **(**graduating_year**)** **(** PARTITION p0 **VALUES** **LESS** **THAN** **(**2019**),** PARTITION p1 **VALUES** **LESS** **THAN** **MAXVALUE);**
Then create a second empty table matching the column specification, but without partitions. This will be your working table:
+**CREATE** **TABLE** test**.**students_work **ASSELECT** * **FROM** test**.**students **WHERE** **NULL;**
For each partition you want to restore, discard the working table's tablespace:
+**ALTER** **TABLE** test**.**students_work DISCARD TABLESPACE**;**
Then, copy the table files from the backup, using the new name:
+$ sudo cp /data/backups/part_inc1/test/students.ibd /var/lib/mysql/test/students_work.ibd
+$ sudo cp /data/backups/part_inc1/test/students.cfg /var/lib/mysql/test/students_work.cfg
Change the owner to that of the user running MariaDB Enterprise Server:
+$ sudo chown mysql:mysql /var/lib/mysql/test/students_work.*
Import the copied tablespace:
+**ALTER** **TABLE** test**.**students_work IMPORT TABLESPACE**;**
Lastly, exchange the partition, copying the tablespace from the working table into the partition file for the target table:
+**ALTER** **TABLE** test**.**students EXCHANGE PARTITION p0 **WITH** **TABLE** test**.**students_work**;**
Repeat the above process for each partition until you have them all exchanged into the target table. Then delete the working table, as it's no longer necessary:
+**DROP** **TABLE** test**.**students_work**;**
This restores a partitioned table.
+When restoring a table with a full-text search (FTS) index, InnoDB may throw a schema mismatch error.
+In this case, to restore the table, it is recommended to:
+.cfgĀ file.For example, to restore tableĀ t1Ā with FTS index from databaseĀ db1:
In the MariaDB shell, drop the table you are going to restore:
+**DROP** **TABLE** **IF** **EXISTS** db1**.**t1**;**
Create an empty table for the data being restored:
+**CREATE** **TABLE** db1**.**t1**(**f1 CHAR**(**10**))** ENGINE=INNODB**;**
Modify the table to discard the tablespace:
+**ALTER** **TABLE** db1**.**t1 DISCARD TABLESPACE**;**
In the operating system shell, copy the table files from the backup to the data directory of the corresponding database:
+$ sudo cp /data/backups/part/db1/t1.* /var/lib/mysql/db1
Remove theĀ .cfgĀ file from the data directory:
$ sudo rm /var/lib/mysql/db1/t1.cfg
Change the owner of the newly copied files to the system user running MariaDB Enterprise Server:
+$ sudo chown mysql:mysql /var/lib/mysql/db1/t1.*
In the MariaDB shell, import the copied tablespace:
+**ALTER** **TABLE** db1**.**t1 IMPORT TABLESPACE**;**
Verify that the data has been successfully restored:
+**SELECT** * **FROM** db1**.**t1**;**
+--------+
+| f1 |
++--------+
+| ABC123 |
++--------+
Add the necessary secondary indexes:
+**ALTER** **TABLE** db1**.**t1 **FORCE,** **ADD** FULLTEXT **INDEX** f_idx**(**f1**);**
The table is now fully restored:
+**SHOW** **CREATE** **TABLE** db1**.**t1**\G**
*************************** 1. row ***************************
+ Table: t1
+Create Table: CREATE TABLE `t1` (
+ `f1` char(10) DEFAULT NULL,
+ FULLTEXT KEY `f_idx` (`f1`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci
+Recovering from a backup restores the data directory at a specific point-in-time, but it does not restore the binary log. In a point-in-time recovery, you begin by restoring the data directory from a full or incremental backup, then use theĀ mysqlbinlogĀ utility to recover the binary log data to a specific point in time.
First, prepare the backup as you normally would for aĀ fullĀ orĀ incrementalĀ backup:
+$ sudo mariabackup --prepare --target-dir=/data/backups/full
When MariaDB Enterprise Backup runs on a MariaDB Enterprise Server where binary logs is enabled, it stores binary log information in theĀ xtrabackup_binlog_infoĀ file. Consult this file to find the name of the binary log position to use. In the following example, the log position isĀ 321.
`$ sudo cat /data/backups/full/xtraback_binlog_info
+mariadb-node4.00001 321`
+Update the configuration file to use a new data directory.
+**[mysqld]**datadir=/var/lib/mysql_new
Using MariaDB Enterprise Backup, restore from the backup to the new data directory:
+$ sudo mariabackup --copy-back --target-dir=/data/backups/full
Then change the owner to the MariaDB Enterprise Server system user:
+$ sudo chown -R mysql:mysql /var/lib/mysql_new
Start MariaDB Enterprise Server:
+$ sudo systemctl start mariadb
Using the binary log file in the old data directory, the start position in theĀ xtrabackup_binlog_infoĀ file, the date and time you want to restore to, and theĀ mysqlbinlogĀ utility to create an SQL file with the binary log changes:
$ mysqlbinlog --start-position=321 \ --stop-datetime="2019-06-28 12:00:00" \ /var/lib/mysql/mariadb-node4.00001 \ > mariadb-binlog.sql
Lastly, run the binary log SQL to restore the databases:
+$ mysql -u root -p < mariadb-binlog.sql
The SkySQL Backup service provides comprehensive Backup and Restore features through a secure API. We extend the automated nightly backups with a number of self service features. You can automatically create and store backups of your databases to ensure additional data safety or provide a robust disaster recovery solution. The backups are stored on reliable and secure cloud storage, ensuring they are readily available when needed. The backup process is seamless and does not affect the performance of your databases. SkySQL also offers the flexibility to customize your backup schedule according to your specific needs.
+Here is the list of features offered:
+Automatic nightly backups : Automated nightly backups include a full backup of every database in the service.
+Secure On-demand or scheduled backups
+Full (physical) backups : Full backups create a complete backup of the database server into a new backup folder. It uses mariabackup under the hood. Physical backups are performed by copying the individual data files or directories and the fastest way to do a backup.
+Incremental backups : Incremental backups update a previous backup with whatever changes to the data have occurred since the backup.
+Logical backups : Logical backups consist of the SQL statements necessary to restore the data, such as CREATE DATABASE, CREATE TABLE and INSERT. This is done using mariadb-dump(https://mariadb.com/kb/en/mariadb-dump/) and is the most flexible way to perform a backup and restore, and a good choice when the data size is relatively small.
+Bring your own Bucket (BYOB) : you can backup or restore data to/from your own bucket in either GCP or AWS.
+Backup your binlogs : Binlogs record database changes (data modifications, table structure changes) in a sequential, binary format. You can preserve binlogs for setting up replication or to recover to a certain point-in-time.
+Point-in-time recovery : you can restore from a full or a logical backup and then use a binlog backup to restore to a point-in-time.
+Secure backup/restores : Control backup/restore privileges by granting roles to users in SkySQL.
+while the daily automated backups are included the use of this API will incur nominal additional charges. Please contact info@skysql.com for details.
+The following documentation describes the API for the SkySQL Backup Service. This can be used directly with any HTTP client.
+Note
+Please refer to the API docs (swagger) for the latest API. +The information below might be slightly outdated.
+To authenticate with the API, do the following:
+Go to SkySQL API Key management page: https://app.skysql.com/user-profile/api-keys and generate an API key
+Export the value from the token field to an environment variable $API_KEY
+Use it on subsequent request, e.g:
+ curl --request GET 'https://api.skysql.com/skybackup/v1/backups/schedules' \\
+ --header "X-API-Key: ${API_KEY}"
+Backups on large data sets can take time. You instruct the creation of a backup using a "schedule". You can either schedule a one-time backup (schedule now) or set up automatic backups using a cron schedule. A backup schedule results in a backup job which can be tracked using the status API. We support the following types of backups : full(physical), incremental(physical), binary log, and dump(logical).
+To create a backup schedule, you need to have the "administrator" role. You can add members and configure roles using the SkySQL portal.
+To create a full backup you need to make the following API call:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "full",
+ "schedule": "once",
+ "service_id": "dbtgf28044362"
+}'
+++note that each launched database is tracked with a service ID in SkySQL. You can fetch the service ID from the Fully qualified domain name(FQDN) of your service. For instance in dbpgf17106534.sysp0000.db2.skysql.com, 'dbpgf17106534' is the service ID. +You will find the FQDN in the Connect window
+
Typical API server response should look like:
+{
+ "id": 253,
+ "service_id": "dbtgf28044362",
+ "schedule": "once",
+ "type": "full",
+ "status": "Scheduled",
+ "message": "Backup is scheduled."
+}
+++you can fetch the Status of the backup using 'https://api.skysql.com/skybackup/v1/backups'. See the 'Backup Status' section for an example. The 'status' field will report Success or failure.
+
To set up an automatic periodic full backup at 3 am UTC, you need to make the following API call:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "full",
+ "schedule": "0 3 * * *",
+ "service_id": "dbtgf28044362"
+}'
+For more information about cron schedules take a look at this document.
+Incremental backups can be taken once you have full backup. Read here for more details.
+To set up an one-time incremental backup, you need to make the following API call:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "incremental",
+ "schedule": "once",
+ "service_id": "dbtgf28044362"
+}'
+To set up an cron incremental backup, you need to make the following API call:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "incremental",
+ "schedule": "0 3 * * *",
+ "service_id": "dbtgf28044362"
+}'
+To set up an one-time binarylog backup:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "binarylog",
+ "schedule": "once",
+ "service_id": "dbtgf28044362"
+}'
+To set up an cron incremental backup:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "binarylog",
+ "schedule": "0 3 * * *",
+ "service_id": "dbtgf28044362"
+}'
+To set up an one-time dump backup:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "dump",
+ "schedule": "once",
+ "service_id": "dbtgf28044362"
+}'
+To set up an cron dump backup:
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "dump",
+ "schedule": "0 3 * * *",
+ "service_id": "dbtgf28044362"
+}'
+To set up an external storage backup, you need to make the following API call:
+For GCP you need to create an service account key. Please follow the steps from this documentation. Once you have created the service account key you will need to base64 encode it. You can encode it directly from a command line itself. For example the execution of command echo -n 'service-account-key' | base64 will produce something like c2VydmljZS1hY2NvdW50LWtleQ==
curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "full",
+ "schedule": "0 2 * * *",
+ "service_id": "dbtgf28044362",
+ "external_storage": {
+ "bucket": {
+ "path": "s3://my_backup_bucket",
+ "credentials": "c2VydmljZS1hY2NvdW50LWtleQ=="
+ }
+ }
+}'
+The service account key will be in the following format:
+{
+ "type": "service_account",
+ "project_id": "XXXXXXX",
+ "private_key_id": "XXXXXXX",
+ "private_key": "-----BEGIN PRIVATE KEY-----XXXXX-----END PRIVATE KEY-----",
+ "client_email": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX.iam.gserviceaccount.com",
+ "client_id": "XXXXXXX",
+ "auth_uri": "<https://accounts.google.com/o/oauth2/auth>",
+ "token_uri": "<https://oauth2.googleapis.com/token>",
+ "auth_provider_x509_cert_url": "<https://www.googleapis.com/oauth2/v1/certs>",
+ "client_x509_cert_url": "<https://www.googleapis.com/robot/v1/metadata/x509/XXXXXXXXXXXXXX.iam.gserviceaccount.com>",
+ "universe_domain": "googleapis.com"
+}
+For AWS, you must provide your own credentials. These include the AWS access key associated with an IAM account and the bucket region. For more information about AWS credentials, please refer to the documentation. The required credentials are aws_access_key_id , aws_secret_access_key and region. For example your credentials should look like:
+[default]
+aws_access_key_id = AKIAIOSFODNN7EXAMPLE
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+region = us-west-2
+You should encode your credentials base64 before passing it to the API. You can encode it directly from a command line itself. For example the execution of command echo '[default]\naws_access_key_id = AKIAIOSFODNN7EXAMPLE\naws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\nregion = us-west-2' | base64 will produce the following W2RlZmF1bHRdCmF3c19hY2Nlc3Nfa2V5X2lkID0gQUtJQUlPU0ZPRE5ON0VYQU1QTEUKYXdzX3NlY3JldF9hY2Nlc3Nfa2V5ID0gd0phbHJYVXRuRkVNSS9LN01ERU5HL2JQeFJmaUNZRVhBTVBMRUtFWQpyZWdpb24gPSB1cy13ZXN0LTIK.
+Using encoded credentials you will be able to pass it to the API server. To initiate a new backup to your external storage you need to execute an API call to the backup service:
```bash
+curl --location '<https://api.skysql.com/skybackup/v1/backups/schedules>' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "full",
+ "schedule": "0 2 ** *",
+ "service_id": "dbtgf28044362",
+ "external_storage": {
+ "bucket": {
+ "path": "s3://my_backup_bucket",
+ "credentials": "W2RlZmF1bHRdCmF3c19hY2Nlc3Nfa2V5X2lkID0gQUtJQUlPU0ZPRE5ON0VYQU1QTEUKYXdzX3NlY3JldF9hY2Nlc3Nfa2V5ID0gd0phbHJYVXRuRkVNSS9LN01ERU5HL2JQeFJmaUNZRVhBTVBMRUtFWQpyZWdpb24gPSB1cy13ZXN0LTIK"
+ }
+ }
+}'
To get backup schedules inside the Organization :
+curl --location '<https://api.skysql.com/skybackup/v1/backups/schedules>' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+To get backup schedules for specific service :
+curl --location '<https://api.skysql.com/skybackup/v1/backups/schedules?service_id=dbtgf28044362>' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+To get specific backup schedule by id :
+curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules/200' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+In the following example, we update the backup schedule to 9 AM UTC. Remember, you cannot change the schedules for one-time backups. +To update specific backup schedule you need to make the following API call:
+curl --location --request PATCH '<https://api.skysql.com/skybackup/v1/backups/schedules/215>' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "schedule": "0 9 ** *"
+}'
+To delete a backup schedule you need to provide the backup schedule id. Example of the api call below:
+curl --location --request DELETE 'https://api.skysql.com/skybackup/v1/backups/schedules/215' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+The following API illustrates how to get the available backups and status of backup jobs .
+Here is an example to fetch all the available Backups in your org:
+curl --location 'https://api.skysql.com/skybackup/v1/backups' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+To list all backups available for your service :
+curl --location 'https://api.skysql.com/skybackup/v1/backups?service_id=dbtgf28216706' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+The typical response of either of two calls should look like:
+{
+ "backups": [
+ {
+ "id": "eda3b72460c8c0d9d61a7f01b6a22e32:dbtgf28216706:tx-filip-mdb-ms-0",
+ "service_id": "dbtgf28216706",
+ "type": "full",
+ "method": "skybucket",
+ "server_pod": "tx-filip-mdb-ms-0",
+ "backup_size": 5327326,
+ "reference_full_backup": "",
+ "point_in_time": "2024-03-26 17:18:21",
+ "start_time": "2024-03-26T17:18:57Z",
+ "end_time": "2024-03-26T17:19:01Z",
+ "status": "Succeeded"
+ }
+ ],
+ "backups_count": 1,
+ "pages_count": 1
+}
+++The ** Backup id is the most important part of this data as you need to provide it in the restore api call** to schedule restore execution.
+
WARNING
+++restoring from a Backup will likely wipe out all data in your target DB service. If you aren't sure, first take a backup of the Db service where a restore is being performed. The DB being restored will also be stopped during a Restore. You will need restart it.
+
You can restore your database from the backup located in the default SkySQL managed backup storage. In this case, you need to provide the backup ID when making the restore API call. Here is an example:
+curl --location 'https://api.skysql.com/skybackup/v1/restores' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "key": "eda3b72460c8c0d9d61a7f01b6a22e32:dbtgf28216706:tx-filip-mdb-ms-0",
+ "service_id": "dbtgf28044362"
+}'
+Inside the service_id parameter of your restore API request, you need to provide the id of the service, where you want to restore your data.
+You can restore your data from external storage. Your external storage bucket data should be created via one of the following tools: mariabackup, mysqldump. Credentials to external storage access could be fetched from:
For GCP you need to create an service account key. Please follow the steps from this documentation. Once you have created the service account key you will need to base64 encode it. You can encode it directly from a command line itself. For example the execution of command echo -n 'service-account-key' | base64 will produce the following c2VydmljZS1hY2NvdW50LWtleQ==
curl --location 'https://api.skysql.com/skybackup/v1/backups/schedules' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}' \
+--data '{
+ "backup_type": "full",
+ "schedule": "0 2 * * *",
+ "service_id": "dbtgf28044362",
+ "external_storage": {
+ "bucket": {
+ "path": "s3://my_backup_bucket",
+ "credentials": "c2VydmljZS1hY2NvdW50LWtleQ=="
+ }
+ }
+}'
+The service account key will be in the following format:
+{
+ "type": "service_account",
+ "project_id": "XXXXXXX",
+ "private_key_id": "XXXXXXX",
+ "private_key": "-----BEGIN PRIVATE KEY-----XXXXX-----END PRIVATE KEY-----",
+ "client_email": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX.iam.gserviceaccount.com",
+ "client_id": "XXXXXXX",
+ "auth_uri": "<https://accounts.google.com/o/oauth2/auth>",
+ "token_uri": "<https://oauth2.googleapis.com/token>",
+ "auth_provider_x509_cert_url": "<https://www.googleapis.com/oauth2/v1/certs>",
+ "client_x509_cert_url": "<https://www.googleapis.com/robot/v1/metadata/x509/XXXXXXXXXXXXXX.iam.gserviceaccount.com>",
+ "universe_domain": "googleapis.com"
+}
+For AWS, you must provide your own credentials. These include the AWS access key associated with an IAM account and the bucket region. For more information about AWS credentials, please refer to the documentation. The required credentials are aws_access_key_id , aws_secret_access_key and region. For example your credentials should look like:
+[default]
+aws_access_key_id = AKIAIOSFODNN7EXAMPLE
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+region = us-west-2
+You should encode your credentials base64 before passing it to the API. You can encode it directly from a command line itself. For example the execution of command echo '[default]\naws_access_key_id = AKIAIOSFODNN7EXAMPLE\naws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\nregion = us-west-2' | base64 will produce the following W2RlZmF1bHRdCmF3c19hY2Nlc3Nfa2V5X2lkID0gQUtJQUlPU0ZPRE5ON0VYQU1QTEUKYXdzX3NlY3JldF9hY2Nlc3Nfa2V5ID0gd0phbHJYVXRuRkVNSS9LN01ERU5HL2JQeFJmaUNZRVhBTVBMRUtFWQpyZWdpb24gPSB1cy13ZXN0LTIK.
The following request demonstrates how to restore your data from an external storage:
+{
+ "service_id": "dbtgf28044362",
+ "key": "/backup.tar.gz",
+ "external_source": {
+ "bucket": "gs://my_backup_bucket",
+ "method": "mariabackup",
+ "credentials" "W2RlZmF1bHRdCmF3c19hY2Nlc3Nfa2V5X2lkID0gQUtJQUlPU0ZPRE5ON0VYQU1QTEUKYXdzX3NlY3JldF9hY2Nlc3Nfa2V5ID0gd0phbHJYVXRuRkVNSS9LN01ERU5HL2JQeFJmaUNZRVhBTVBMRUtFWQpyZWdpb24gPSB1cy13ZXN0LTIK"
+ }
+}
+In case your backup data is encrypted you need to pass encryption key as well:
+{
+ "service_id": "dbtgf28044362",
+ "key": "/backup.tar.gz",
+ "external_source": {
+ "bucket": "gs://my_backup_bucket",
+ "method": "mariabackup",
+ "credentials": "W2RlZmF1bHRdCmF3c19hY2Nlc3Nfa2V5X2lkID0gQUtJQUlPU0ZPRE5ON0VYQU1QTEUKYXdzX3NlY3JldF9hY2Nlc3Nfa2V5ID0gd0phbHJYVXRuRkVNSS9LN01ERU5HL2JQeFJmaUNZRVhBTVBMRUtFWQpyZWdpb24gPSB1cy13ZXN0LTIK",
+ "encryption_key": "my_encryption_key"
+ }
+}
+In order to get all Restores scheduled in the past you need to make api call:
+curl --location 'https://api.skysql.com/skybackup/v1/restores' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+curl --location 'https://api.skysql.com/skybackup/v1/restores/12' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+Typical response of those two apis should look like:
+In case restore is in progress:
+[
+ {
+ "id": 12,
+ "service_id": "dbtgf28216706",
+ "bucket": "gs://sky-syst0000-backup-us-84e9d84ecf265a/orgpxw1x",
+ "key": "eda3b72460c8c0d9d61a7f01b6a22e32:dbtgf28216706:tx-filip-mdb-ms-0",
+ "type": "physical",
+ "status": "Running",
+ "message": "server is not-ready"
+ }
+]
+In case restore completed:
+[
+ {
+ "id": 13,
+ "service_id": "dbtgf28216706",
+ "bucket": "gs://sky-syst0000-backup-us-84e9d84ecf265a/orgpxw1x",
+ "key": "dda9b72460c9c0d9d61a7f01b6a33e39:dbtgf28216706:tx-filip-mdb-ms-0",
+ "type": "physical",
+ "status": "Succeeded",
+ "message": "Restore has succeeded!"
+ }
+]
+You can delete older completed restore schedules. To clean up your auditing history you need to execute the following api call:
+curl --location --request DELETE 'https://api.skysql.com/skybackup/v1/restores/12' \
+--header 'Accept: application/json' \
+--header 'X-API-Key: ${API_KEY}'
+Billing is associated with aĀ MariaDB ID.
+For pricing information see "Pricing" .
+From theĀ Portal, you can access a current billing and usage summary:
+Current charges, prior billing date, and next invoice date are shown.
+Usage information can be shown by service or by resource.
+Click the resource name or service name to expand the view.
+
Billing - Usage
+https://skysql.mariadb.com/billings/usage
+From theĀ Portal, you can access prior invoices:
+
Billing - Billing History
+https://skysql.mariadb.com/billings/history
+ + + + + + + + + + + + + +Note
+COMING SOON ā¦ a complete feature checklist of both the tiers ... +A full description of billing and invoicing (FAQ covers a bit)
+Power Tier is a premium service offering who have the most critical requirements for uptime, availability, performance, and support.
+By default, any new signed up users are in the āFoundation Tierā. To upgrade to Power Tier,Ā simply click the āUpgradeā button - SkySQL support will contact you and start the upgrade process. You can also directly reach out to SkySQL Support.
+Features available to SkySQL Power Tier customers include:
+Database server configuration, including system variables, is managed through the Configuration Manager.
+
Configuration Manager
+https://app.skysql.com/settings/configuration-manager
+To access the Configuration Manager interface:
+Available configuration parameters differ by cloud database topology.
+For cloud databases with the Enterprise Server Single Node topology, the following Configuration Manager parameters are used to configure MariaDB Enterprise Server behavior:
+Parameter
+disconnect_on_expired_password
+explicit_defaults_for_timestamp
+idle_readonly_transaction_timeout
+idle_write_transaction_timeout
+innodb_flush_log_at_trx_commit
+performance_schema_accounts_size
+performance_schema_digests_size
+performance_schema_events_stages_history_long_size
+performance_schema_events_stages_history_size
+performance_schema_events_statements_history_long_size
+performance_schema_events_statements_history_size
+performance_schema_events_waits_history_long_size
+performance_schema_events_waits_history_size
+performance_schema_max_cond_classes
+performance_schema_max_cond_instances
+performance_schema_max_digest_length
+performance_schema_max_file_classes
+performance_schema_max_file_handles
+performance_schema_max_file_instances
+performance_schema_max_mutex_classes
+performance_schema_max_mutex_instances
+performance_schema_max_rwlock_classes
+performance_schema_max_rwlock_instances
+performance_schema_max_socket_classes
+performance_schema_max_socket_instances
+performance_schema_max_stage_classes
+performance_schema_max_table_handles
+performance_schema_max_table_instances
+performance_schema_max_thread_classes
+performance_schema_max_thread_instances
+performance_schema_session_connect_attrs_size
+session_track_system_variables
+simple_password_check_letters_same_case
+simple_password_check_minimal_length
+simple_password_check_other_characters
+system_versioning_alter_history
+For cloud databases with the Enterprise Server With Replica(s) topology, Configuration Manager can be used to configure MariaDB Enterprise Server behavior and MariaDB MaxScale behavior.
+The following Configuration Manager parameters are used to configure MariaDB Enterprise Server behavior:
+Parameter
+disconnect_on_expired_password
+explicit_defaults_for_timestamp
+idle_readonly_transaction_timeout
+idle_write_transaction_timeout
+innodb_flush_log_at_trx_commit
+performance_schema_accounts_size
+performance_schema_digests_size
+performance_schema_events_stages_history_long_size
+performance_schema_events_stages_history_size
+performance_schema_events_statements_history_long_size
+performance_schema_events_statements_history_size
+performance_schema_events_waits_history_long_size
+performance_schema_events_waits_history_size
+performance_schema_max_cond_classes
+performance_schema_max_cond_instances
+performance_schema_max_digest_length
+performance_schema_max_file_classes
+performance_schema_max_file_handles
+performance_schema_max_file_instances
+performance_schema_max_mutex_classes
+performance_schema_max_mutex_instances
+performance_schema_max_rwlock_classes
+performance_schema_max_rwlock_instances
+performance_schema_max_socket_classes
+performance_schema_max_socket_instances
+performance_schema_max_stage_classes
+performance_schema_max_table_handles
+performance_schema_max_table_instances
+performance_schema_max_thread_classes
+performance_schema_max_thread_instances
+performance_schema_session_connect_attrs_size
+rpl_semi_sync_master_wait_no_slave
+rpl_semi_sync_master_wait_point
+rpl_semi_sync_slave_delay_master
+rpl_semi_sync_slave_kill_conn_timeout
+session_track_system_variables
+simple_password_check_letters_same_case
+simple_password_check_minimal_length
+simple_password_check_other_characters
+system_versioning_alter_history
+The following Configuration Manager parameters are used to configure MariaDB MaxScale behavior:
+Parameter
+transaction_replay_retry_on_deadlock
+MariaDB Connector/J enables Java applications to connect to SkySQL and MariaDB database products using a native MariaDB connector.
+| Version | +Latest Release | +Latest Release Date | +Maturity | +
|---|---|---|---|
| MariaDB Connector/J 3.1 | +https://mariadb.com/docs/server/release-notes/mariadb-connector-j-3-1/3-1-4/ | +2023-05-01 | +General Availability | +
| MariaDB Connector/J 3.0 | +https://mariadb.com/docs/server/release-notes/mariadb-connector-j-3-0/3-0-10/ | +2023-01-11 | +General Availability | +
| MariaDB Connector/J 2.7 | +https://mariadb.com/docs/server/release-notes/mariadb-connector-j-2-7/2-7-9/ | +2023-03-22 | +General Availability | +
| MariaDB Connector/J 1.8 | +MariaDB Connector/J 1.8.0 | +2019-02-11 | +GA | +
To download the JAR file manually:
+Maven can install MariaDB Connector/J as a dependency of your application during build. Set theĀ <version>Ā element to correspond to the version of MariaDB Connector/J that you would like to install.
To use Maven to install MariaDB Connector/J, add the dependency to yourĀ pom.xmlĀ file:
<dependency>
+ <groupId>org.mariadb.jdbc</groupId>
+ <artifactId>mariadb-java-client</artifactId>
+ <version>3.0.10</version>
+</dependency>
+For additional information on available releases, see the "Release Notes for MariaDB Connector/J".
+Depending on the features you plan to use, you may need to add some additional dependencies toĀ pom.xml.
If you downloaded the connector JAR, place it on your CLASSPATH
+export CLASSPATH="/path/to/application:/path/to/mariadb-java-client-3.0.10.jar"
+In MariaDB Connector/J 3.0, TLS is enabled for connections to SkySQL using theĀ sslModeĀ parameter.
import java.sql.*;
+import java.util.Properties;
+
+public class App {
+ public static void main(String[] argv) {
+ Properties connConfig = new Properties();
+ connConfig.setProperty("user", "db_user");
+ connConfig.setProperty("password", "db_user_password");
+ **connConfig.setProperty("sslMode", "verify-full");**
+
+ try (Connection conn = DriverManager.getConnection("jdbc:mariadb://HOST:PORT", connConfig)) {
+ try (Statement stmt = conn.createStatement()) {
+ try (ResultSet contact_list = stmt.executeQuery("SELECT first_name, last_name, email FROM test.contacts")) {
+ while (contact_list.next()) {
+ System.out.println(String.format("%s %s <%s>",
+ contact_list.getString("first_name"),
+ contact_list.getString("last_name"),
+ contact_list.getString("email")));
+ }
+ }
+ }
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+In MariaDB Connector/J 2.7 and before, TLS is enabled for connections to SkySQL using theĀ useSslĀ parameter.
import java.sql.*;
+import java.util.Properties;
+
+public class App {
+ public static void main(String[] argv) {
+ Properties connConfig = new Properties();
+ connConfig.setProperty("user", "db_user");
+ connConfig.setProperty("password", "db_user_password");
+ **connConfig.setProperty("useSsl", "true");**
+
+ try (Connection conn = DriverManager.getConnection("jdbc:mariadb://HOST:PORT", connConfig)) {
+ try (Statement stmt = conn.createStatement()) {
+ try (ResultSet contact_list = stmt.executeQuery("SELECT first_name, last_name, email FROM test.contacts")) {
+ while (contact_list.next()) {
+ System.out.println(String.format("%s %s <%s>",
+ contact_list.getString("first_name"),
+ contact_list.getString("last_name"),
+ contact_list.getString("email")));
+ }
+ }
+ }
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+| Connector | +MariaDB Connector/J | +
|---|---|
| Supported Versions | +https://mariadb.com/docs/server/release-notes/mariadb-connector-j-3-1/https://mariadb.com/docs/server/release-notes/mariadb-connector-j-3-0/https://mariadb.com/docs/server/release-notes/mariadb-connector-j-2-7/MariaDB Connector/J 1.8 | +
| Programming Language | +Java | +
| Programming Language Version | +Java 17, Java 11, Java 8 (Connector/J 3.1)Java 17, Java 11, Java 8 (Connector/J 3.0)Java 17, Java 11, Java 8 (Connector/J 2.7)Java 7 (Connector/J 1.8) | +
| API | +JDBC 4.2 (Connector/J 3.1)JDBC 4.2 (Connector/J 3.0)JDBC 4.2 (Connector/J 2.7)JDBC 4.1 (Connector/J 1.8) | +
| Supports TLS | +Yes | +
| License | +GNU Lesser General Public License v2.1 | +
The NoSQL protocol module allows a MariaDB server or cluster to execute transactions for applications using MongoDB client libraries, transparently converting MongoDB API calls into the equivalent SQL. The MariaDB responses are then converted into the format expected by the MongoDBĀ® client library and application.
+For detailed information on supported commands, see "NoSQL Protocol Module" in MariaDB MaxScale documentation.
+ + +Connect to the NoSQL interface using a MongoDB client library or compatible application.Ā Documentation on official MongoDB librariesĀ is available from MongoDB.
+Documentation on installingĀ mongoshĀ (the MongoDB Shell)Ā is available from MongoDB.
From the Dashboard, the details needed to connect to your SkySQL service can be seen by clicking on the "CONNECT" button for the desired service.
+The "NoSQL port" is the TCP port used to connect to the NoSQL interface.
+TheĀ firewallĀ must be configured to allowlist the client's IP address or netblock before connections can occur.
+See the "Connecting using Mongosh" section of the Connect page for an exampleĀ mongoshĀ command-line, authentication instructions, and instructions to change the default password.
Node.js developers can connect to MariaDB database products through a native MariaDB Connector. Using MariaDB Connector/Node.js you can connect to MariaDB database products to use and administer databases from within your Node.js application.
+MariaDB Connector/Node.js is usually installed either from the Node.js repository or manually from the source code package.
+To install MariaDB Connector/Node.js from the Node.js repository, use NPM:
+$ npm install mariadb
NPM connects to the Node.js repository and downloads MariaDB Connector/Node.js and all relevant dependencies into theĀ node_modules/Ā directory.
To download and install the MariaDB Connector/Node.js manually from source code:
+When the source code package finishes downloading, install it with NPM:
+$ npm install mariadb-connector-nodejs-*.tar.gz
NPM untars the download and installs MariaDB Connector/Node.js in theĀ node_modules/Ā directory.
Node.js developers can use MariaDB Connector/Node.js to establish client connections with MariaDB database products.
+MariaDB Connector/Node.js provides two different connection implementations: one built on theĀ Promise APIĀ and the other built on the Callback API.
+To use the Callback API, use the following module:
+**const** mariadb = require**(**'mariadb/callback'**);**
createConnection(options)Ā ->Ā ConnectionĀ is the base function used to create aĀ ConnectionĀ object.
TheĀ createConnection(options)Ā function returns aĀ ConnectionĀ object.
Determine theĀ connection informationĀ for your MariaDB SkySQL database service:
+| Option | +Description | +
|---|---|
| host | +The fully Qualified Domain Name in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| port | +The Read-Write Port or Read-Only Port in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| user | +The desired username, which might be the default username in the Service Credentials view | +
| password | +The user's password, which might be the default password in the Service Credentials view if it was not yet customized | +
| database | +Database name to establish a connection to. No default is configured. | +
| connectTimeout | +Connection timeout in milliseconds. In Connector/Node.js 2.5.6, the default value changed to 1000. The default value for earlier versions is 10000. | +
| rowsAsArray | +A boolean value to indicate whether to return result sets as array instead of the default JSON. Arrays are comparatively faster. | +
The following code example connects using the database and user account created in theĀ example setup:
+const mariadb = require('mariadb/callback');
+
+// Certificate Authority (CA)",
+var serverCert = [fs.readFileSync(process.env.SKYSQL_CA_PEM, "utf8")];
+
+// Declare async function
+function main() {
+ let conn;
+
+ try {
+ conn = mariadb.createConnection({
+ host: "example.skysql.com",
+ port: 5009,
+ ssl: { ca: serverCert },
+ user: "db_user",
+ password: "db_user_password",
+ database: "test",
+ });
+
+ // Use Connection
+ // ...
+ } catch (err) {
+ // Manage Errors
+ console.log("SQL error in establishing a connection: ", err);
+ } finally {
+ // Close Connection
+ if (conn) conn.end(err => {if(err){
+ console.log("SQL error in closing a connection: ", err);}
+ });
+ }
+}
+
+main();
+try...catch...finallyĀ statement is used for exception handling.connection.end([callback])Ā function.connection.end([callback])Ā function to close/end the connection in theĀ finallyĀ block after the queries that are running have completed.end()Ā function takes a callback function that defines one implicit argument for theĀ ErrorĀ object if thrown in closing the connection as argument. If no error is generated in closing a connection theĀ ErrorĀ object isĀ null.Node.js developers can use MariaDB Connector/Node.js to establish client connections with MariaDB database products.
+MariaDB Connector/Node.js provides two different connection implementations: one built on the Promise API and the other built on theĀ Callback API. Promise is the default.
+To use the Promise API, use theĀ mariadbĀ module:
**const** mariadb = require**(**'mariadb'**);**
createConnection(options)Ā ->Ā PromiseĀ is the base function used to create aĀ ConnectionĀ object.
TheĀ createConnection(options)Ā returns aĀ PromiseĀ that resolves to aĀ ConnectionĀ object if no error occurs, and rejects with anĀ ErrorĀ object if an error occurs.
Determine theĀ connection informationĀ for your MariaDB SkySQL database service:
+| Option | +Description | +
|---|---|
| host | +The fully Qualified Domain Name in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| port | +The Read-Write Port or Read-Only Port in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| user | +The desired username, which might be the default username in the Service Credentials view | +
| password | +The user's password, which might be the default password in the Service Credentials view if it was not yet customized | +
| ssl.ca | +The contents of theĀ skysql_chain.pemĀ file containing theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/#Certificate_Authority_Chain | +
| ā¢ https://supplychain.mariadb.com/skysql_chain.pem | ++ |
| ā¢ https://supplychain.mariadb.com/aws_skysql_chain.pem | ++ |
| database | +Database name to establish a connection to. No default is configured. | +
| connectTimeout | +Connection timeout in milliseconds. In Connector/Node.js 2.5.6, the default value changed to 1000. The default value for earlier versions is 10000. | +
| rowsAsArray | +A boolean value to indicate whether to return result sets as array instead of the default JSON. Arrays are comparatively faster. | +
Create a file namedĀ .envĀ to store your database credentials:
MDB_HOST = 192.0.2.50
+MDB_PORT = 3306
+MDB_USER = db_user
+MDB_PASS = db_user_password
+MDB_HOST = example.skysql.com
+MDB_PORT = 5001
+MDB_CA_PEM = /path/to/skysql_chain.pem
+MDB_USER = db_user
+MDB_PASS = db_user_password
+The following code example connectsĀ using the database and user account created inĀ Setup for Examples:
+// Required Modules
+const fs = require("fs");
+const mariadb = require("mariadb");
+require("dotenv").config()
+
+// Certificate Authority (CA)
+const serverCert = [fs.readFileSync(process.env.MDB_CA_PEM, "utf8")];
+
+// Declare async function
+async function main() {
+ let conn;
+
+ try {
+ conn = await mariadb.createConnection({
+ host: process.env.MDB_HOST,
+ port: process.env.MDB_PORT,
+ user: process.env.MDB_USER,
+ password: process.env.MDB_PASS,
+ ssl: { ca: serverCert },
+ database: "test",
+ });
+
+ // Use Connection
+ // ...
+ } catch (err) {
+ // Manage Errors
+ console.log("SQL error in establishing a connection: ", err);
+ } finally {
+ // Close Connection
+ if (conn) conn.close();
+ }
+}
+
+main();
+mariadbĀ module using theĀ require()Ā function.main()Ā using theĀ asyncĀ keyword.awaitĀ expressions using theĀ awaitĀ keyword.awaitĀ expression is the resolved value of theĀ Promise.mainĀ is arbitrary and does not have special meaning as in some other programming languages.connĀ for the connection to be created using aĀ letĀ statement with the async functionĀ main.try...catch...finallyĀ statement is used for exception handling.tryĀ block, create a new connection using theĀ mariadb#createConnection(options)Ā function in the Promise API.catchĀ block.close()Ā function.| Connector | +MariaDB Connector/Node.js | +
|---|---|
| Supported Versions | +https://mariadb.com/docs/server/release-notes/mariadb-connector-nodejs-2-5/https://mariadb.com/docs/server/release-notes/mariadb-connector-nodejs-3-2/ | +
| Programming Language | +JavaScript | +
| Programming Language Version | +ā¢ Connector/Node.js 2.5: Node.js 16 | +
| ā¢ Connector/Node.js 3.2: Node.js 16, 18, 20 | ++ |
| API | +Promise APICallback API | +
| Supports TLS | +Yes | +
| Supports Connection Pools | +Yes | +
| License | +GNU Lesser General Public License v2.1 | +
Python developers can use MariaDB Connector/Python to establish client connections with SkySQL database products.
+Connections are managed using the following Python class:
+| Class | +Description | +
|---|---|
| Connection | +Represents a connection to a MariaDB database product. | +
Connections are created, used, and managed using the following Connection class functions:
| Function | +Description | +
|---|---|
| connect() | +Establishes a connection to a database server and returns a connection object. | +
| cursor() | +Returns a new cursor object for the current connection. | +
| change_user() | +Changes the user and default database of the current connection. | +
| reconnect() | +Tries to make a connection object active again by reconnecting to the server using the same credentials which were specified in connect() method. | +
| close() | +Closes the connection. | +
Determine the connection information for your SkySQL database service:
+| connect() parameter | +Where to find it | +
|---|---|
| user | +Default username in the Service Credentials view, or the username you created | +
| passwd | +Default password in the Service Credentials view, the password you set on the default user, or the password for the user you created | +
| host | +Fully Qualified Domain Name in the Connection Parameters Portal | +
| ssl_verify_cert | +Set to True to support SSL | +
| port | +Read-Write Port or Read-Only Port in the Connection Parameters Portal | +
The following code example connects to an example server.
+Examples:
+# Module Import
+import mariadb
+import sys
+
+# Instantiate Connection
+try:
+ conn = mariadb.connect(
+ host="192.0.2.1",
+ port=3306,
+ user="db_user",
+ password="USER_PASSWORD")
+except mariadb.Error as e:
+ print(f"Error connecting to the database: {e}")
+ sys.exit(1)
+
+# Use Connection
+# ...
+
+# Close Connection
+conn.close()
+# Module Import
+import mariadb
+import sys
+
+# Instantiate Connection
+try:
+ conn = mariadb.connect(
+ host="SKYSQL_SERVICE.mdb0000001.db.skysql.com",
+ port=5009,
+ ssl_verify_cert=True,
+ user="DB00000001",
+ password="USER_PASSWORD")
+except mariadb.Error as e:
+ print(f"Error connecting to the database: {e}")
+ sys.exit(1)
+
+# Use Connection
+# ...
+
+# Close Connection
+conn.close()
+connect() function returns an instance of the Connection class, which is assigned to the conn variable.connect()function.close()method.Instantiating the Connection class creates a single connection to MariaDB database products. Applications that require multiple connections may benefit from pooling connections.
MariaDB Connector/Python closes the connection as part of the class's destructor, which is executed when an instance of the class goes out of scope. This can happen in many cases, such as:
+Connection class is defined in the local scope of a function, and the function returnsConnection class is defined as an attribute of a custom class's instance, and the custom class's instance goes out of scope.Connections can also be explicitly closed using the close() method, which is helpful when the connection is no longer needed, but the variable is still in scope.
Starting with MariaDB Connector/Python 1.1 when MariaDB Connector/Python is built with MariaDB Connector/C 3.3, the connector supports connection failover when auto_reconnect is
+enabled and the connection string contains a comma-separated list of multiple server addresses.
To enable connection failover:
+mariadb.connect function with the host argument specified as a comma-separated list containing multiple server addresses. The connector attempts to connect to the addresses in the order specified in the list.auto_reconnect to True. If the connection fails, the connector will attempt to reconnect to the addresses in the order specified in the list.The following code example connects with connection failover enabled:
+# Module Import
+import mariadb
+import sys
+
+# Instantiate Connection
+try:
+ conn = mariadb.connect(
+ host="192.0.2.1,192.0.2.0,198.51.100.0",
+ port=3306,
+ user="db_user",
+ password="USER_PASSWORD")
+ conn.auto_reconnect = True
+except mariadb.Error as e:
+ print(f"Error connecting to the database: {e}")
+ sys.exit(1)
+
+# Use Connection
+# ...
+
+# Close Connection
+conn.close()
+# Module Import
+import mariadb
+import sys
+
+# Instantiate Connection
+try:
+ conn = mariadb.connect(
+ host="SKYSQL_SERVICE.mdb0000001.db.skysql.com,SKYSQL_SERVICE.mdb0000002.db.skysql.com",
+ port=5009,
+ ssl_verify_cert=True,
+ user="DB00000001",
+ password="USER_PASSWORD")
+ conn.auto_reconnect = True
+except mariadb.Error as e:
+ print(f"Error connecting to the database: {e}")
+ sys.exit(1)
+
+# Use Connection
+# ...
+
+# Close Connection
+conn.close()
+MariaDB Connector/C++ enables C++ applications to establish client connections to SkySQL over TLS.
+MariaDB Connector/C++ has dependencies. You must install MariaDB Connector/C to use it.
+| MariaDB Connector/C++ | +MariaDB Connector/C | +
|---|---|
| 1.1 | +3.2.3 or later | +
| 1.0 | +3.1.1 or later | +
For additional information, see "MariaDB Connector/C++ Release Notes".
+To install MariaDB Connector/C++ on Linux:
+Extract the tarball:
+$ tar -xvzf mariadb-connector-cpp-*.tar.gz
Change into the relevant directory:
+$ cd mariadb-connector-cpp-*/
Install the directories for the header files:
+$ sudo install -d /usr/include/mariadb/conncpp
+$ sudo install -d /usr/include/mariadb/conncpp/compat
Install the header files:
+$ sudo install include/mariadb/* /usr/include/mariadb/
+$ sudo install include/mariadb/conncpp/* /usr/include/mariadb/conncpp
+$ sudo install include/mariadb/conncpp/compat/* /usr/include/mariadb/conncpp/compat
Install the directories for the shared libraries:
+On CentOS, RHEL, Rocky Linux:
+$ sudo install -d /usr/lib64/mariadb
+$ sudo install -d /usr/lib64/mariadb/plugin
On Debian, Ubuntu:
+$ sudo install -d /usr/lib/mariadb
+$ sudo install -d /usr/lib/mariadb/plugin
Install the shared libraries:
+On CentOS, RHEL, Rocky Linux:
+$ sudo install lib64/mariadb/libmariadbcpp.so /usr/lib64
+$ sudo install lib64/mariadb/plugin/* /usr/lib64/mariadb/plugin
On Debian, Ubuntu:
+$ sudo install lib/mariadb/libmariadbcpp.so /usr/lib
+$ sudo install lib/mariadb/plugin/* /usr/lib/mariadb/plugin
To install MariaDB Connector/C++ on Windows:
+mariadbcppĀ LIBĀ file (exampleĀ "C:\ProgramĀ Files\MariaDB\MariaDBĀ C++Ā ConnectorĀ 64-bit") toĀ PATHĀ environment variable.| Version | +Latest Release | +Latest Release Date | +Maturity | +
|---|---|---|---|
| MariaDB Connector/C++ 1.1 | +https://mariadb.com/docs/server/release-notes/mariadb-connector-cpp-1-1/1-1-2/ | +2022-11-30 | +Release Candidate | +
| MariaDB Connector/C++ 1.0 | +https://mariadb.com/docs/server/release-notes/mariadb-connector-cpp-1-0/1-0-2/ | +2022-10-11 | +General Availability | +
The connection is configured via the information that is initially acquired from the SkySQL Portal pages:
+| What to set | +Where to find it | +
|---|---|
| Hostname in the URL | +The fully Qualified Domain Name in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| Port number in the URL | +The Read-Write Port or Read-Only Port in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| userĀ parameter | +The desired username, which might be the default username in the Service Credentials view | +
| passwordĀ parameter | +The user's password, which might be the default password in the Service Credentials view if it was not yet customized | +
| tlsCertĀ parameter | +The path to theĀ skysql_chain.pemĀ file containing theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/#Certificate_Authority_Chain | +
| ā¢ https://supplychain.mariadb.com/skysql_chain.pem | ++ |
| ā¢ https://supplychain.mariadb.com/aws_skysql_chain.pem | ++ |
While MariaDB Connector/C++ supports several connection styles, we are going to detail just the JDBC syntax since all connections to SkySQL use a single idiom of hostname, port, user, password, and SSL parameters.
+The base URL is specified as follows:
+jdbc:mariadb://example.skysql.com:5001/dbname
If the trailing database name is left off of the URL, the connection will start without selecting a database.
+MariaDB Connector/C++ supports several optional connection parameters. These parameters can be specified using aĀ PropertiesĀ object, as we do in our examples, or appended to the URL in standardĀ name=valueĀ query-string encoding.
In the following list, we've left out any parameters that aren't pertinent to accessing SkySQL:
+| Parameter Name | +Description | +Type | +Default | +Aliases | +
|---|---|---|---|---|
| autoReconnect | +Defines whether the connector automatically reconnects after a connection failure. | +bool | +false | +ā¢ OPT_RECONNECT | +
| connectTimeout | +Defines the connect timeout value in milliseconds. When set toĀ 0, there is no connect timeout. | +int | +30000 | ++ |
| enabledTlsCipherSuites | +A list of permitted ciphers or cipher suites to use for TLS. | +string | ++ | ā¢ enabledSslCipherSuites | +
| ā¢ enabledSSLCipherSuites | ++ | + | + | + |
| jdbcCompliantTruncation | +This mode is enabled by default. This mode configures the connector to addĀ STRICT_TRANS_TABLESĀ toĀ https://mariadb.com/docs/server/ref/mdb/system-variables/sql_mode/https://mariadb.com/docs/server/ref/mdb/system-variables/sql_mode/, which causes ES to handle truncation issues as errors instead of warnings. | +bool | +true | ++ |
| password | +Defines the password of the user account to connect with. | ++ | + | + |
| socketTimeout | +Defines the network socket timeout (SO_TIMEOUT) in milliseconds. When set toĀ 0, there is no socket timeout. This connection parameter is not intended to set a maximum time for statements. To set a maximum time for statements, please see theĀ https://mariadb.com/docs/server/ref/mdb/system-variables/max_statement_time/https://mariadb.com/docs/server/ref/mdb/system-variables/max_statement_time/https://mariadb.com/docs/server/ref/mdb/system-variables/max_statement_time/Ā system variable. | +int | +0 | +ā¢ OPT_READ_TIMEOUT | +
| tcpRcvBuf | +The buffer size for TCP/IP and socket communication.Ā tcpSndBufĀ changes the same buffer value, and the biggest value of the two is selected. | +int | +0x4000 | +ā¢ tcpSndBuf | +
| tcpSndBuf | +The buffer size for TCP/IP and socket communication.Ā tcpRcvBufĀ changes the same buffer value, and the biggest value of the two is selected. | +int | +0x4000 | +ā¢ tcpRcvBuf | +
| tlsCert | +Path to the X509 certificate file. | +string | ++ | ā¢ sslCert | +
| tlsCRL | +Path to a PEM file that should contain one or more revoked X509 certificates. | +string | ++ | ā¢ tlsCrl | +
| ā¢ sslCRL | ++ | + | + | + |
| useCompression | +Compresses network traffic between the client and server. | +bool | +false | +ā¢ CLIENT_COMPRESS | +
| user | +Defines the user name of the user account to connect with. | ++ | + | ā¢ userName | +
| useServerPrepStmts | +Defines whether the connector uses server-side prepared statements using theĀ https://mariadb.com/docs/skysql-previous-release/ref/mdb/sql-statements/PREPARE/,Ā https://mariadb.com/docs/skysql-previous-release/ref/mdb/sql-statements/EXECUTE/, andĀ https://mariadb.com/docs/skysql-previous-release/ref/mdb/sql-statements/DROP_PREPARE/Ā statements. By default, the connector uses client-side prepared statements. | +bool | +false | ++ |
| useTls | +Whether to force TLS. This enables TLS with the default system settings. | +bool | ++ | ā¢ useSsl | +
| ā¢ useSSL | ++ | + | + | + |
Two categories of methods are available to to establish a connection.
+MariaDB Connector/C++ can connect using the non-staticĀ connect()Ā methods in theĀ sql::DriverĀ class.
The non-staticĀ connect()Ā methods in theĀ sql::DriverĀ class have the following prototypes:
Connection*Ā connect(constĀ SQLString&Ā url,Ā Properties&Ā props);Connection*Ā connect(constĀ SQLString&Ā host,Ā constĀ SQLString&Ā user,Ā constĀ SQLString&Ā pwd);Connection*Ā connect(constĀ Properties&Ā props);The non-staticĀ connect()Ā methods in theĀ sql::DriverĀ class:
sql::DriverĀ class to establish a connection.nullptrĀ as theĀ Connection*Ā value when an error occurs, so applications should check the return value before use.For example:
+// Instantiate Driver
+sql::Driver* driver = sql::mariadb::get_driver_instance();
+
+// Configure Connection, including an optional initial database name "places":
+sql::SQLString url("jdbc:mariadb://example.skysql.com:5009/places");
+
+// Use a properties map for the other connection options
+sql::Properties properties({
+ {"user", "db_user"},
+ {"password", "db_user_password"},
+ {"autocommit", false},
+ {"useTls", true},
+ {"tlsCert", "classpath:static/skysql_chain.pem"},
+ });
+
+// Establish Connection
+// Use a smart pointer for extra safety
+std::unique_ptr<sql::Connection> conn(driver->connect(url, properties));
+
+if (!conn) {
+ cerr << "Invalid database connection" << endl;
+ exit (EXIT_FAILURE);
+}
+MariaDB Connector/C++ can connect using the staticĀ getConnection()Ā methods in theĀ sql::DriverManagerĀ class.
The staticĀ getConnection()Ā methods in theĀ sql::DriverManagerĀ class have the following prototypes:
staticĀ Connection*Ā getConnection(constĀ SQLString&Ā url);staticĀ Connection*Ā getConnection(constĀ SQLString&Ā url,Ā Properties&Ā props);staticĀ Connection*Ā getConnection(constĀ SQLString&Ā url,Ā constĀ SQLString&Ā user,Ā constĀ SQLString&Ā pwd);The staticĀ getConnection()Ā methods in theĀ sql::DriverManagerĀ class:
sql::DriverManagerĀ class to establish a connection, because they are static.tryĀ {Ā ..Ā }Ā catchĀ (Ā ..Ā )Ā {Ā ..Ā }Ā to catch the exception.For example:
+try {
+ // Configure Connection, including an optional initial database name "places":
+ sql::SQLString url("jdbc:mariadb://example.skysql.com:5009/places");
+
+ // Use a properties map for the other connection options
+ sql::Properties properties({
+ {"user", "db_user"},
+ {"password", "db_user_password"},
+ {"autocommit", false},
+ {"useTls", true},
+ {"tlsCert", "classpath:static/skysql_chain.pem"},
+ });
+
+ // Establish Connection
+ // Use a smart pointer for extra safety
+ std::unique_ptr<sql::Connection> conn(DriverManager::getConnection(url, properties));
+ } catch (...) {
+ cerr << "Invalid database connection" << endl;
+ exit (EXIT_FAILURE);
+}
+The following code demonstrates how to connect using theĀ example database and user account:
+// Includes
+#include <iostream>
+#include <mariadb/conncpp.hpp>
+
+// Main Process
+int main(int argc, char **argv)
+{
+ try {
+ // Instantiate Driver
+ sql::Driver* driver = sql::mariadb::get_driver_instance();
+
+ // Configure Connection, including initial database name "test":
+ sql::SQLString url("jdbc:mariadb://example.skysql.com:5009/test");
+
+ // Use a properties map for the other connection options
+ sql::Properties properties({
+ {"user", "db_user"},
+ {"password", "db_user_password"},
+ {"autocommit", false},
+ {"useTls", true},
+ {"tlsCert", "classpath:static/skysql_chain.pem"},
+ });
+
+ // Establish Connection
+ // Use a smart pointer for extra safety
+ std::unique_ptr<sql::Connection> conn(driver->connect(url, properties));
+
+ // Use Connection
+ // ...
+
+ // Close Connection
+ conn->close();
+ }
+
+ // Catch Exceptions
+ catch (sql::SQLException& e) {
+ std::cerr << "Error Connecting to the database: "
+ << e.what() << std::endl;
+
+ // Exit (Failed)
+ return 1;
+ }
+
+ // Exit (Success)
+ return 0;
+}
+MariaDB Connector/C enables C and C++ applications to establish client connections to SkySQL over TLS. MariaDB Connector/C is a native connector that is written in C.
+MariaDB Connector/C enables C and C++ applications to establish client connections to SkySQL and MariaDB database products over TLS.
+Additional information on MariaDB Connector/C is available in theĀ MariaDB Knowledge Base.
+The connection is configured via the information that is initially acquired from the SkySQL Portal pages:
+| Function | +Option/Argument | +Where to find it | +
|---|---|---|
| mysql_optionsv() | +MYSQL_OPT_SSL_CAĀ option | +The path to theĀ skysql_chain.pemĀ file containing theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/#Certificate_Authority_Chain | +
| ā¢ https://supplychain.mariadb.com/skysql_chain.pem | ++ | + |
| ā¢ https://supplychain.mariadb.com/aws_skysql_chain.pem | ++ | + |
| mysql_real_connect() | +hostĀ argument | +The fully Qualified Domain Name in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
| mysql_real_connect() | +userĀ argument | +The desired username, which might be the default username in the Service Credentials view | +
| mysql_real_connect() | +passwdĀ argument | +The user's password, which might be the default password in the Service Credentials view if it was not yet customized | +
| mysql_real_connect() | +portĀ argument | +The Read-Write Port or Read-Only Port in theĀ https://mariadb.com/docs/skysql-previous-release/connect/connection-parameters-portal/ | +
The following code demonstrates how to use MariaDB Connector/C to connect to SkySQL. This example uses theĀ example database and user account:
+#include <stdio.h>
+#include <stdlib.h>
+#include <mysql.h>
+
+int main (int argc, char* argv[])
+{
+
+ // Initialize Connection
+ MYSQL *conn;
+ if (!(conn = mysql_init(0)))
+ {
+ fprintf(stderr, "unable to initialize connection struct\n");
+ exit(1);
+ }
+
+ // Connect to the database
+ if (!mysql_real_connect(
+ conn, // Connection
+ "example.skysql.com", // Host
+ "db_user", // User account
+ "db_user_password", // User password
+ "test", // Default database
+ 3006, // Port number
+ NULL, // Path to socket file
+ 0 // Additional options
+ ))
+ {
+ // Report the failed-connection error & close the handle
+ fprintf(stderr, "Error connecting to Server: %s\n", mysql_error(conn));
+ mysql_close(conn);
+ exit(1);
+ }
+
+ // Use the Connection
+ // ...
+
+ // Close the Connection
+ mysql_close(conn);
+
+ return 0;
+}
+Java developers can use MariaDB Connector/R2DBC to connect to MariaDB database products using the Reactive Relational Database Connectivity (R2DBC) API. R2DBC operations are non-blocking, which makes the R2DBC API more scalable than Java's standard JDBC API. MariaDB Connector/R2DBC is available both with a native R2DBC implementation and the Spring Data R2DBC framework.
+| Connector | +MariaDB Connector/R2DBC | +MariaDB Connector/R2DBC | +
|---|---|---|
| Supported Versions | +1.0 | +1.1 | +
| Programming Language | +Java | +Java | +
| Programming Language Version | +Java 8+ | +Java 8+ | +
| API | +https://r2dbc.io/spec/0.8.5.RELEASE/spec/html/ | +https://r2dbc.io/spec/1.0.0.RELEASE/spec/html | +
| Supports TLS | +Yes | +Yes | +
| Supports Connection Pools | +Yes | +Yes | +
| License | +Apache 2.0 | +Apache 2.0 | +
For details on how to use MariaDB Connector/R2DBC, choose a supported framework:
+| https://mariadb.com/docs/skysql-previous-release/connect/programming-languages/java-r2dbc/native/ | +The native implementation of R2DBC can be used to connect using MariaDB Connector/R2DBC from within your Java application. | +
|---|---|
| https://mariadb.com/docs/skysql-previous-release/connect/programming-languages/java-r2dbc/spring/ | +Spring Data implementation of R2DBC allows you to connect using MariaDB Connector/R2DBC using the Spring Framework. | +
Application developers can use MariaDB Connector/ODBC to establish a data source for client connections with MariaDB database products.
+The method for configuring the data source varies between operating systems.
+Configure unixODBC to recognize the driver by creating a file called MariaDB_odbc_driver_template.iniwith the relevant driver definition.
For example, on CentOS / RHEL / Rocky Linux:
+[MariaDB ODBC 3.1 Driver]
+Description = MariaDB Connector/ODBC v.3.1
+Driver = /usr/lib64/libmaodbc.so
+On Debian / Ubuntu:
+[MariaDB ODBC 3.1 Driver]
+Description = MariaDB Connector/ODBC v.3.1
+Driver = /usr/lib/libmaodbc.so
+Install the driver using the odbcinst command.
For example:
+$ sudo odbcinst -i -d -f MariaDB_odbc_driver_template.ini
+odbcinst: Driver installed. Usage count increased to 1.
+Target directory is /etc
+Determine the connection parameters for your database.
+Configure unixODBC to connect to the data source by creating a file called MariaDB_odbc_data_source_template.iniwith the relevant data source parameters. Be sure to specify SSLVERIFY = 1 for your SkySQL database.
For example:
+# Data Source for unixODBC
+[My-Test-Server]
+Description = Describe your database setup here
+Driver = MariaDB ODBC 3.1 Driver
+Trace = Yes
+TraceFile = /tmp/trace.log
+SERVER = localhost
+SOCKET = /var/run/mysqld/mysqld.sock
+USER = db_user
+PASSWORD = db_user_password
+DATABASE = test
+# Data Source for unixODBC
+[My-Test-Server]
+Description = Describe your database setup here
+Driver = MariaDB ODBC 3.1 Driver
+Trace = Yes
+TraceFile = /tmp/trace.log
+SERVER = example.skysql.com
+PORT = 3306
+SSLVERIFY = 1
+USER = db_user
+PASSWORD = db_user_password
+DATABASE = test
+SSLCA = /path/to/ca-cert.pem
+SSLKEY = /path/to/client-key.pem
+SSL_CERT = /path/to/client-cert.pem
+Install the unixODBC data source template file:
$ sudo odbcinst -i -s -h -f MariaDB_odbc_data_source_template.ini
+Test the data source My-Test-Serverconfigured in the MariaDB_odbc_data_source_template.ini
+file using the isql command. If you see the output below, you have successfully connected to your Sky database.
$ isql -v My-Test-Server
++-------------------------+
+| Connected! |
+| sql-statement |
+| help[tablename] |
+| quit |
++-------------------------+
+SQL>
+To select your new data source in your application, select the data source with the name that you configured, which is My-Test-Server in the above example.
Confirm that MariaDB Connector/ODBC has been registered withiODBC by confirming that the following options are set in the iODBCconfiguration file at /Library/ODBC/odbcinst.ini:
[ODBC]
+Trace = no
+TraceFile = /tmp/iodbc_trace.log
+
+[ODBC Drivers]
+MariaDB ODBC 3.1 Unicode Driver = Installed
+
+[MariaDB ODBC 3.1 Unicode Driver]
+Driver = /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib
+Description = MariaDB Connector/ODBC(Unicode) 3.1 64bit
+Threading = 0
+Determine the connection parameters for your database.
+Add a data source for your database to iODBC by adding the following options to the iODBC configuration file at /Library/ODBC/odbc.ini:
[ODBC Data Sources]
+My-Test-Server = MariaDB ODBC 3.1 Unicode Driver
+
+[My-Test-Server]
+Driver = /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib
+SERVER = 192.0.2.1
+DATABASE = test
+USER = db_user
+PASSWORD = db_user_password
+SERVER, SOCKET, DATABASE, PORT, USER, and PASSWORD parameters with the relevant value for your environment.iodbctestcommand:$ iodbctest "DSN=My-Test-Server"
+To select your new data source in your application, select the data source with the name that you configured, which is My-Test-Server in the above example.
MariaDB Connector/ODBC requires at least Windows 8.
+Windows 10 was used to prepare these instructions. When using other versions of Windows, these instructions may require adjustment.
+MariaDB Connector/ODBC supports failover in case one or more hosts are not available.
+The failover feature requires using MariaDB Connector/ODBC 3.1.16 or greater with MariaDB Connector/C 3.3 or greater.
+MariaDB Connector/ODBC 3.1.16 and greater is statically linked for Windows and macOS with MariaDB Connector/C 3.3.1. MariaDB Connector/ODBC 3.1.16 and greater is dynamically linked for Linux with MariaDB Connector/C.
+The failover feature is enabled by providing a comma separated list of hosts as a server name.
+The failover host string is the SERVER string. If the SERVER string does not include a port, the default port will be used.
The following syntax is required:
+"[]"":"hostname:port pairs must be be separated by a comma ","hostname:port is specified, the host string must end with a commaAn example of a failover host string:
+[::1]:3306,192.168.0.1:3307,test.example.com
| Connection Parameter | +Description | +Default Value | +
|---|---|---|
| DRIVER | +ā¢ On Linux, the name of the driver, which is configured in the | ++ |
| unixODBC driver template file. | ++ | + |
| ā¢ On macOS, the path to the driver's shared library, which is | ++ | + |
| installed at /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib | ++ | + |
| by default. | ++ | + |
| SERVER | +Host name, IPv4 address, or IPv6 address of the database | ++ |
| server. | +localhost | ++ |
| SOCKET | +ā¢ The path to the socket file. On Linux, MariaDB Enterprise Server | ++ |
| uses different default socket files on different Linux | ++ | + |
| distributions. | ++ | + |
| ā¢ On Debian / Ubuntu, the default socket file is /var/run/mysqld/mysqld.sock | ++ | + |
| or /run/mysqld/mysqld.sock. | ++ | + |
| ā¢ On CentOS / RHEL / Rocky Linux, the default socket file is /var/lib/mysql/mysql.sock. | +/tmp/mysql.sock | ++ |
| DATABASE | +Database name to select upon successful connection. The database | ++ |
| must already exist, and the user account must have privileges to select | ++ | + |
| it. | ++ | + |
| PORT | +TCP port of the database server. | +3306 | +
| USER | +The username to use for authentication. | ++ |
| PASSWORD | +User password. | ++ |
| FORWARDONLY | +When enabled, cursors are created as SQL_CURSOR_FORWARD_ONLY, | ++ |
| so they can only move forward. Starting in Connector/ODBC 3.2, cursors | ++ | + |
| are SQL_CURSOR_FORWARD_ONLY | ++ | + |
| by default. In previous releases, cursors are created as SQL_CURSOR_STATIC by | ++ | + |
| default. | ++ | + |
| NO_CACHE | +When enabled, result set streaming is enabled, which enables the | ++ |
| application to fetch result sets from the server row-by-row instead of | ++ | + |
| caching the entire result set on the client side. Since the application | ++ | + |
| is not caching the entire result set, the application is less likely to | ++ | + |
| run out of memory when working with large result sets. | ++ | + |
| STREAMRS | +Alias for the NO_CACHE connection | ++ |
| parameter. | ++ | + |
| OPTIONS | +See about:blank#OPTIONS_Bitmaskabout:blank#OPTIONS_Bitmask. | ++ |
| PREPONCLIENT | +When enabled, the SQLPrepare ODBC API | ++ |
| function uses the text protocol and client-side prepared statements | ++ | + |
| (CSPS). | ++ | + |
| ATTR | +Sets connection attributes that can be queried via the https://www.notion.so../../../../ref/mdb/performance-schema/session_account_connect_attrs/https://www.notion.so../../../../../server/ref/mdb/performance-schema/session_account_connect_attrs/ | ++ |
| and https://www.notion.so../../../../ref/mdb/performance-schema/session_connect_attrs/https://www.notion.so../../../../../server/ref/mdb/performance-schema/session_connect_attrs/ | ++ | + |
| tables when https://www.notion.so../../../../ref/mdb/system-variables/performance_schema/https://www.notion.so../../../../../server/ref/mdb/system-variables/performance_schema/ | ++ | + |
| is enabled. Specify attributes in the format ATTR={ |
++ | + |
| What | +Where to find it | +
|---|---|
| DRIVER | +ā¢ On Linux, the name of the driver, which is configured in the | +
| unixODBC driver template file. | ++ |
| ā¢ On macOS, the path to the driver's shared library, which is | ++ |
| installed at /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib | ++ |
| by default. | ++ |
| SERVER | +Fully Qualified Domain Name in the https://www.notion.so../../../connection-parameters-portal/ | +
| PORT | +Read-Write Port or Read-Only Port in the https://www.notion.so../../../connection-parameters-portal/ | +
| USER | +Default username in the Service Credentials view, or the username | +
| you created | ++ |
| PASSWORD | +Default password in the Service Credentials view, the password | +
| you set on the default user, or the password for the user you | ++ |
| created | ++ |
| SSLVERIFY | +Set to 1 to connect with SSL | +
| FORCETLS | +Set to 1 to enable TLS | +
| FORWARDONLY | +When enabled, cursors are created as SQL_CURSOR_FORWARD_ONLY, | +
| so they can only move forward. Starting in Connector/ODBC 3.2, cursors | ++ |
| are SQL_CURSOR_FORWARD_ONLY | ++ |
| by default. In previous releases, cursors are created as SQL_CURSOR_STATIC by | ++ |
| default. | ++ |
| NO_CACHE | +When enabled, result set streaming is enabled, which enables the | +
| application to fetch result sets from the server row-by-row instead of | ++ |
| caching the entire result set on the client side. Since the application | ++ |
| is not caching the entire result set, the application is less likely to | ++ |
| run out of memory when working with large result sets. | ++ |
| STREAMRS | +Alias for the NO_CACHE connection | +
| parameter. | ++ |
| OPTIONS | +See about:blank#OPTIONS_Bitmaskabout:blank#OPTIONS_Bitmask. | +
| PREPONCLIENT | +When enabled, the SQLPrepare ODBC API | +
| function uses the text protocol and client-side prepared statements | ++ |
| (CSPS). | ++ |
| ATTR | +Sets connection attributes that can be queried via the https://www.notion.so../../../../ref/mdb/performance-schema/session_account_connect_attrs/ | +
| and https://www.notion.so../../../../ref/mdb/performance-schema/session_connect_attrs/ | ++ |
| tables when https://www.notion.so../../../../ref/mdb/system-variables/performance_schema/ | ++ |
| is enabled. Specify attributes in the format ATTR={ |
++ |
OPTIONS BitmaskThe OPTIONS bitmask
+contains the following bits:
| Bit Number | +Bit Value | +Description | +
|---|---|---|
| 0 | +1 | +Unused | +
| 1 | +2 | +Tells connector to return the number of matched rows instead of | +
| number of changed rows | ++ | + |
| 4 | +16 | +Same as NO_PROMPT connection | +
| parameter | ++ | + |
| 5 | +32 | +Forces all cursors to be dynamic | +
| 6 | +64 | +Forbids the DATABASE_NAME.TABLE_NAME.COLUMN_NAME | +
| syntax | ++ | + |
| 11 | +2048 | +Enables compression in the protocol | +
| 13 | +8192 | +Same as the NAMEDPIPE connection | +
| parameter | ++ | + |
| 16 | +65536 | +Same as the USE_MYCNF connection | +
| parameter | ++ | + |
| 20 | +1048576 | +Same as the NO_CACHE connection | +
| parameter | ++ | + |
| 21 | +2097152 | +Same as the FORWARDONLY | +
| connection parameter | ++ | + |
| 22 | +4194304 | +Same as the AUTO_RECONNECT | +
| connection parameter | ++ | + |
| 26 | +67108864 | +Enables multi-statement queries | +