CLI Launch Walkthrough

This page is part of MariaDB's Documentation.

The parent of this page is: Quickstart Launch Walkthrough

Topics on this page:

Overview
Dependency
Launch a Service

Overview

This walkthrough explains how to manually launch a SkySQL service using skysqlcli as described in our Quickstart experience.

We demonstrate a configuration that is suitable for a quick test. A more customized configuration should be selected for performance testing or for alignment to the needs of production workloads.

Done with this walkthrough? Return to Step 2 of the Quickstart

Dependency

The SkySQL DBaaS REST API is currently available as a Technical Preview. skysqlcli is a command-line service management utility which uses the REST API.

Download the SkySQL API CLI binary for your operating system.
- Save or rename the downloaded file as skysqlcli
- If on Linux or macOS, chmod 0755 skysqlcli

Launch a Service

Go to the Generate API Key page and generate a key with a "write" scope. Save the resulting key in a file for use later in this process.

Create a database service, authenticating with the API key:

Substitute your API key for SKYSQL_API_KEY

$ skysqlcli create service \
   --api-key 'SKYSQL_API_KEY' \
   --name 'quickstart-1' \
   --provider 'AWS' \
   --region 'us-east-2' \
   --release-version 'MariaDB Xpand 6.0.3' \
   --replicas '3' \
   --size 'Sky-4x16' \
   --storage '100' \
   --tier 'Foundation' \
   --topology 'Distributed Transactions' \
   --volume-iops '100' \
   | jq .

Upon success, the command will return JSON with details about the new service. Take note of the service ID (with the "id" key).

Add your client IP address to the IP allowlist for the service:
- Substitute the service ID for SKYSQL_SERVICE_ID
- Substitute your client IPv4 address for CLIENT_IP_ADDRESS
- Substitute your API key for SKYSQL_API_KEY
```
$ skysqlcli create allowed-address 'SKYSQL_SERVICE_ID' \
   'CLIENT_IP_ADDRESS/32' \
   --api-key 'SKYSQL_API_KEY'
```
Upon success, a JSON payload will be returned which contains your client IP address and the service's name.
Check the service state:
- Substitute the service ID for SKYSQL_SERVICE_ID
- Substitute your API key for SKYSQL_API_KEY
```
$ skysqlcli get status 'SKYSQL_SERVICE_ID' \
   --api-key 'SKYSQL_API_KEY' \
   | jq .
```
When the service is still being launched, the JSON payload will contain "Pending" as the service state:
```
{
  "status": "Pending"
}
```
When the service has been launched, the JSON payload contains "Running", and you can continue with the next steps:
```
{
  "status": "Running"
}
```
Obtain the hostname and port of the service:
- Substitute the service ID for SKYSQL_SERVICE_ID
- Substitute your API key for SKYSQL_API_KEY
```
$ skysqlcli get service 'SKYSQL_SERVICE_ID' \
   --api-key 'SKYSQL_API_KEY' \
  | jq '{ "provider": .provider, "host": .fqdn, "read_only_port": .read_only_port, "read_write_port": .read_write_port, "ssl_tls": .ssl_tls }'
```
Upon success, the command will return JSON with connection parameters. Take note of the hostname (with the "host" key) and port (with the "read_write_port" key).

The hostname and port will not be available until the service state is "Running".
Obtain the default username and password for the service:
- Substitute the service ID for SKYSQL_SERVICE_ID
- Substitute your API key for SKYSQL_API_KEY
```
$ skysqlcli get credentials SKYSQL_SERVICE_ID \
   --api-key 'SKYSQL_API_KEY' \
  | jq .
```
The default username and password will not be available until the service state is "Running".
If ssl_tls is Enabled on your service (the default), download the certificate authority chain used to verify the server's SSL certificate:
- For AWS services
```
$ curl -O https://supplychain.mariadb.com/aws_skysql_chain.pem
```
- For GCP services
```
$ curl -O https://supplychain.mariadb.com/skysql_chain.pem
```

Done with this walkthrough? Return to Step 2 of the Quickstart