API Launch Walkthrough

Overview

This walkthrough explains how to launch a SkySQL service by manually interacting with the REST API 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

This Quickstart describes how to make API calls using curl, but could be adapted for an alternative REST API client. curl is available for Linux, macOS, and MS Windows. Install curl then proceed.

Examples below also use jq, a JSON parsing utility. jq is available for Linux, macOS, and MS Windows. Install jq then proceed.

Launch a Service

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

  2. Use the API key to obtain a short-lived bearer token:

    • Substitute your API key for SKYSQL_API_KEY

    $ curl --location --request POST \
       --header 'Authorization: Token SKYSQL_API_KEY' \
       --header 'Content-length: 0' \
       https://id.mariadb.com/api/v1/token/ \
       | jq .
    

    On success, the command will return JSON with token details. The bearer token will be shown next to the "token" key. This bearer token is valid for 1 hour.

  3. Prepare a request body that specifies the desired service options. In our example, we have saved this in a file named request.json which we will reference in the next step.

    This configuration 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.

    {
      "name": "quickstart-1",
      "provider": "AWS",
      "region": "us-east-2",
      "release_version": "MariaDB Xpand 6.0.3",
      "replicas": 3,
      "size": "Sky-4x16",
      "tier": "Foundation",
      "topology": "Distributed Transactions",
      "tx_storage": 100,
      "volume_iops": 100
    }
    
  4. Create a database service, authenticating with the bearer token:

    • Substitute your bearer token for SKYSQL_BEARER_TOKEN

    $ curl --location --request POST \
       --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
       --header 'Content-type: application/json' \
       --data '@request.json' \
       https://api.skysql.net/services/ \
       | jq .
    

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

  5. Add your client IP address to the IP allowlist for the service:

    • Substitute your bearer token for SKYSQL_BEARER_TOKEN

    • Substitute the service ID for SKYSQL_SERVICE_ID

    • Substitute your client IPv4 address for CLIENT_IP_ADDRESS

    $ curl --location --request POST \
       --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
       --header 'Content-type: application/json' \
       --data '{ "ip_address": "CLIENT_IP_ADDRESS/32" }' \
       https://api.skysql.net/services/SKYSQL_SERVICE_ID/security/allowlist/ \
       | jq .
    

    Upon success, a JSON payload will be returned which contains your client IP address and the service's name.

  6. Check the service state:

    • Substitute your bearer token for SKYSQL_BEARER_TOKEN

    • Substitute the service ID for SKYSQL_SERVICE_ID

    $ curl --location \
       --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
       https://api.skysql.net/services/SKYSQL_SERVICE_ID/status/ \
       | 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"
    }
    
  7. Obtain the hostname and port of the service:

    • Substitute your bearer token for SKYSQL_BEARER_TOKEN

    • Substitute the service ID for SKYSQL_SERVICE_ID

    $ curl --location \
       --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
       https://api.skysql.net/services/SKYSQL_SERVICE_ID/ \
       | 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".

  8. Obtain the default username and password for the service:

    • Substitute your bearer token for SKYSQL_BEARER_TOKEN

    • Substitute the service ID for SKYSQL_SERVICE_ID

    $ curl --location --request GET \
       --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
       --header 'Content-type: application/json' \
       https://api.skysql.net/services/SKYSQL_SERVICE_ID/security/credentials/ \
       | jq .
    

    The default username and password will not be available until the service state is "Running".

  9. If ssl_tls is Enabled on your service (the default), download the certificate authority chain used to verify the server's SSL certificate:

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