Using skysqlcli with the DBaaS API

Use Cases

• Scripting or automating the creation or deletion of SkySQL services

• Retrieving the default database credentials for a SkySQL service

• Updating the IP allowlist for a SkySQL service

Compatibility

• Distributed Transactions

• Multi-Node Analytics

• Replicated Transactions

• Single Node Analytics

• Single Node Transactions

Installation

1. Access MariaDB Downloads for the skysqlcli utility.

2. In the "OS" dropdown, select your operating system.

3. Click the "Download" button to download the binary for your operating system.

4. Rename the downloaded file.

   On Linux:

   $ mv skysqlcli-linux skysqlcli
   

   On macOS:

   $ mv skysqlcli-macos skysqlcli
   

   On Microsoft Windows:

   C:\> ren skysqlcli-windows.exe skysqlcli.exe
   

5. Set the executable's permissions, so that it can be executed.

   On Linux and macOS:

   $ chmod 0755 skysqlcli
   

   On Microsoft Windows, the default file permissions allow the file to be executed. If you encounter issues, check the file's Access Control List (ACL) to confirm your user account or security group have Read & Execute permissions on the executable file.

6. Place the executable in an appropriate directory on your system, such as:

   Operating Systems	Typical Executable Directories
   Linux macOS	/usr/local/bin $HOME/bin
   Microsoft Windows	Any directory referenced in the PATH environment variable

Authentication and Authorization

skysqlcli interfaces with the MariaDB SkySQL DBaaS API. The DBaaS API requires authentication and authorization.

1. Sign up for SkySQL

2. Obtain a SkySQL API Key with SkySQL API: Databases scope

3. Provide the SkySQL API key to the skysqlcli command-line interface.

   Substitute your SkySQL API key in place of YOUR_SKYSQL_API_KEY using one of the following methods:

   • The --api-key command-line option can be used:

     $ skysqlcli get services \
        --api-key 'YOUR_SKYSQL_API_KEY'
     

   • A YAML configuration file can be used:

     api-key: 'YOUR_SKYSQL_API_KEY'
     

     The default configuration file is $HOME/.skysqlcli.yaml, but a different configuration file can be specified using the --config command-line option.

   • The SKYSQL_API_KEY environment variable can be used:

     $ export SKYSQL_API_KEY='YOUR_SKYSQL_API_KEY'
     

Retrieve Service Information

The following examples retrieve information about SkySQL services.

These types of operations are commonly automated to confirm service configuration, prepare to execute other commands, and to confirm service readiness to receive traffic.

$ skysqlcli get services \
   | jq .

$ skysqlcli get services \
   --name 'doc-test-tx-single' \
  | jq '{ "name": .[0].name, "id": .[0].id }'

{
  "name": "doc-test-tx-single",
  "id": "db00000001"
}

$ skysqlcli get status 'db00000001' \
   | jq .

{
  "status": "Running"
}

Create a Service

The following examples cover activities commonly performed when creating a new SkySQL service.

The use of automation to create services helps ensure repeatability and the correct creation of services of the desired specification.

$ skysqlcli create service \
   --name 'doc-test-tx-single' \
   --provider 'AWS' \
   --region 'us-east-2' \
   --release-version 'MariaDB Enterprise Server 10.6.4-1' \
   --replicas '0' \
   --size 'Sky-2x8' \
   --storage '100' \
   --tier 'Foundation' \
   --topology 'Single Node Transactions' \
   --volume-iops '100' \
   | jq .

$ skysqlcli create allowed-address 'db00000001' 'CLIENT_IP_ADDRESS/SUBNET_MASK'

$ skysqlcli get allowlist-status 'db00000001' \
  | jq .

{
  "status": "Enforcing"
}

$ skysqlcli get credentials 'db00000001' \
   | jq .

{
  "username": "DB00000001",
  "password": "SKYSQL_DEFAULT_PASSWORD"
}

$ skysqlcli get service 'db00000001' \
   | jq '{ "provider": .provider, "host": .fqdn, "read_only_port": .read_only_port, "read_write_port": .read_write_port, "ssl_tls": .ssl_tls }'

{
  "provider": "Amazon AWS",
  "host": "doc-test-tx-single.mdb0000001.db.skysql.net",
  "read_only_port": "",
  "read_write_port": "5001",
  "ssl_tls": "Enabled"
}

Delete a Service

Deletion is non-reversible. Deletion removes the service and all data in the service. Charges for a service stop accruing when the service is deleted.

Ephemeral environments (such as Continuous Integration and testing) are commonly deleted when no longer needed.

Production environments are rarely deleted. Before deleting a service, consider whether production workloads are present.

$ skysqlcli delete service 'db00000001' \
   | jq .