MariaDB skysqlcli Utility

Overview

The skysqlcli utility can create, monitor, and delete database services in MariaDB SkySQL on the command-line:

  • It provides a command-line interface for the MariaDB SkySQL DBaaS API

  • It does not require a web browser or REST client

  • It automatically handles authentication, so that users do not need to request the bearer token

  • It can be used in scripts and automation

  • It supports Linux, macOS, and Microsoft Windows

The skysqlcli utility is a Technical Preview. Software in Tech Preview should not be used for production workloads.

Alternatively, SkySQL services can be managed interactively using your web browser and the SkySQL Portal.

For a guided walkthrough on how to use the skysqlcli utility, see "Get Started Using SkySQL DBaaS API".

Use Cases

The skysqlcli utility supports use cases that require a command-line interface to manage services in MariaDB SkySQL:

  • Create, list, and delete MariaDB SkySQL services

  • Retrieve the default database credentials for MariaDB SkySQL services

  • Monitor the status of MariaDB SkySQL services

  • Update the allowlist for MariaDB SkySQL services

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

The skysqlcli command-line interface requires an API key for authentication and authorization:

  1. Sign up for SkySQL

  2. Obtain a SkySQL API Key

  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'
      

Common Operations

Examples of common operations are listed below.

For a full list of supported operations and command-line options, see skysqlcli Commands.

Add IP Address to Allowlist

SkySQL blocks access to a database service except by IP addresses on the allowlist.

The skysqlcli command-line interface can add an IP address to the allowlist for a service using the create allowed-address command.

Add an IP address to the service's allowlist by providing the service ID and the client's IP address:

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

Replace 'CLIENT_IP_ADDRESS' with the IP address or subnet that the client connects from and replace SUBNET_MASK with the corresponding subnet mask. If 'CLIENT_IP_ADDRESS' is a single IPv4 address, then SUBNET_MASK should be 32.

The status of the operation can be checked using the using the get allowlist-status command:

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

When the operation is complete, the output shows:

{
  "status": "Enforcing"
}

For additional information, see "IP Allowlist for Services".

Check Service Status

The skysqlcli command-line interface can check the status of a database service using the get status command.

New services remain in the Pending state until the creation process is fully complete.

Check the status of the service by providing the service ID:

$ skysqlcli get status 'db00000001' \
   | jq .
{
  "status": "Running"
}

When the status shows "Running", the service is available.

Create a Database Service

The skysqlcli command-line interface can create a database service using the create service command.

The create service command has some mandatory options:

Command-line Option

Argument

--name

  • Specify a name for the new database service

--provider

--region

--release-version

  • Specify a release version

  • Available versions can be shown using the get versions command

--replicas

  • For a single node topology, specify "0"

  • For a multi-node topology, specify the number of replicas

  • Supported replica counts for each topology can be shown using the get topologies command

--size

--storage

--tier

  • Specify either "Foundation" or "Power", depending on the tier.

  • Available tiers can be shown using the get tiers command

--topology

  • Specify the service topology, which can be "Single Node Transactions", "Replicated Transactions", "Distributed Transactions", "Single Node Analytics", or "Multi-Node Analytics"

  • Available topologies can be shown using the get topologies command.

--volume-iops

  • For AWS, specify the provisioned IOPS for the transactional storage

  • For GCP, omit this option

For example, create a Single Node Transactions service in AWS using the following options:

$ 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 .

On success, the command will return JSON with details about the new service. In the output, find the service ID (with the "id" key) to check the status of the service creation process.

Delete a Database service

The skysqlcli command-line interface can delete a database service using the delete service command.

Delete the service by providing the service ID:

$ skysqlcli delete service 'db00000001' \
   | jq .

List Database Services

The skysqlcli command-line interface can list database services using the get services command.

List all services:

$ skysqlcli get services \
   | jq .

On success, the command will return JSON with details about each service associated with the SkySQL account.

Obtain Database Credentials

The skysqlcli command-line interface can show the default database credentials for a service using the get credentials command.

Determine the database credentials for a service by providing the service ID:

$ skysqlcli get credentials 'db00000001' \
   | jq .
{
  "username": "DB00000001",
  "password": "SKYSQL_DEFAULT_PASSWORD"
}

Obtain Service Connection Details

The skysqlcli command-line interface can show the connection details for a service using the get services command.

Determine the connection details for a service by providing the service ID:

$ 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"
}

For Single Node Transactions and Single Node Analytics services, the value of read_only_port is always an empty string.

If the value of ssl_tls is Enabled, you will need to download the SkySQL CA chain for your chosen cloud provider:

Obtain Service ID

The skysqlcli command-line interface requires a service ID as input for some commands.

The skysqlcli command-line interface can show the service ID for a service using the get services command.

Obtain a service's ID by extracting the value of the "id" key from the JSON object:

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