REST Client Access to the DBaaS API

Overview

SkySQL operations can be automated using the MariaDB SkySQL DBaaS API.

A REST Client is one way to access the SkySQL DBaaS API.

Any REST client can be used. The examples on this page use cURL.

The examples on this page demonstrate common service management operations. For a full list of supported REST API endpoints, see "SkySQL API Reference".

The MariaDB SkySQL DBaaS API is a Technical Preview. Software in Tech Preview should not be used for production workloads.

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

Authentication and Authorization

The MariaDB SkySQL DBaaS API requires authentication and authorization.

To authenticate and authorize with the API:

  1. Sign up for SkySQL

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

  3. Use the API key to request a bearer token

  4. Use the bearer token to authenticate for API requests:

    • The Authorization header must be in the format Authorization: Bearer SKYSQL_BEARER_TOKEN, where SKYSQL_BEARER_TOKEN is the bearer token

    • The endpoint depends on the specific API request.

Retrieving Service Information

The following examples retrieve information about SkySQL services.

These types of operations are commonly automated to confirm service configuration, prepare for other REST API calls, and to confirm service readiness to receive traffic.

Services List

Similar to the "Your Services" list in the SkySQL Portal, you can retrieve the list of all active services you (or your SkySQL Team) have created.

Detail

Description

Endpoint

https://api.skysql.net/services/

Method

GET

Behavior

  • Returns JSON with an array of servers.

Parameters

  • None

Response Code

200 - Success (expected)

API References

Sample Request

https://api.skysql.net/services/

Command-Line Example

$ curl --location \
   --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
   https://api.skysql.net/services/ \
   | jq .

Retrieve Service ID by Service Name

REST API calls related to specific services require that the Service ID be specified. The Service ID can be looked-up from the Service Name.

Detail

Description

Endpoint

https://api.skysql.net/services/

Method

GET

Behavior

  • Returns JSON with server IDs

Parameters

  • name=SERVICE_NAME_PREFIX - returns IDs for names that match the provided prefix

Response Code

200 - Success (expected)

API References

Sample Request

https://api.skysql.net/services/?name=doc-test-tx-single

Command-Line Example

$ curl --location \
   --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
   https://api.skysql.net/services/?name=doc-test-tx-single \
   | jq '{ "name": .[0].name, "id": .[0].id }'

Sample Response

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

Service Status

Service status indicates when a new service is ready to receive connections.

Detail

Description

Endpoint

https://api.skysql.net/services/SERVICE_ID/status/

Method

GET

Behavior

  • Returns JSON with server status for the service with Service ID SERVICE_ID

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

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

Parameters

  • None

Response Code

200 - Success (expected)

API References

Sample Request

https://api.skysql.net/services/db00000001/status/

Command-Line Example

For a Service ID of db00000001:

$ curl --location \
   --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
   https://api.skysql.net/services/db00000001/status/ \
   | jq .

Sample Response

{
  "status": "Running"
}

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

Create a Database Service

SkySQL enables creation of services with multiple cloud providers and regions, customized to your specifications.

Detail

Description

Endpoint

https://api.skysql.net/services/

Method

POST

Content Type

application/json

Behavior

  • Initiates service creation based on specification provided in the request body.

  • The request body must be a valid JSON object.

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

Request Body

  • name (required key) - String for the name of the new database service

  • provider (required key) - String to specify the cloud provider

    • "AWS"

    • "GCP"

  • region (required key) - String to specify the region

  • release_version (required key) - String to specify the software version

  • replicas (required key) - String to specify the count of replicas

  • size (required key) - String to specify the instance size

  • tier (required key) - String to specify the tier

    • "Foundation"

    • "Power"

  • topology (required key) - String to specify the topology

    • "Single Node Transactions"

    • "Replicated Transactions"

    • "Distributed Transactions"

    • "Single Node Analytics"

    • "Multi-Node Analytics"

  • tx_storage (required key) - String to specify the amount of transactional storage in GB

  • volume_iops (required key for AWS, omit for GCP) - String to specify the amount of provisioned IOPS

Response Code

200 - Success (expected)

API References

Sample Request Body

{
  "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",
  "tier": "Foundation",
  "topology": "Single Node Transactions",
  "tx_storage": "100",
  "volume_iops": "100"
}

Sample Request

https://api.skysql.net/services/

Command-Line Example

With the request body saved to request.json:

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

Add IP Address to Allowlist

By default, access to SkySQL services is blocked by a firewall. An IP allowlist specifies which IP addresses are permitted to connect to the service.

Detail

Description

Endpoint

https://api.skysql.net/services/SERVICE_ID/security/allowlist/

Method

POST

Content Type

application/json

Behavior

  • Adds the specified addresses to the allowlist to access the service with Service ID SERVICE_ID

  • The specified CLIENT_IP_ADDRESS IPv4 address with SUBNET_MASK subnet mask defines which addresses are allowlisted

  • If CLIENT_IP_ADDRESS references a single IPv4 address, use a SUBNET_MASK of 32

  • The request body must be a valid JSON object

  • The status of the operation can be checked using a using a Read Allowlist Status request

Request Body

  • ip_address (required key) - String to specify the client IPv4 address and subnet mask

Response Code

200 - Success (expected)

API References

Sample Request Body

{
  "ip_address": "CLIENT_IP_ADDRESS/SUBNET_MASK"
}

Sample Request

For a Service ID of db00000001:

https://api.skysql.net/services/db00000001/security/allowlist/

Command-Line Example

With the request body saved to request.json:

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

To check the status of this operation:

$ curl --location \
   --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
   https://api.skysql.net/services/db00000001/security/allowlist/status/ \
   | jq .

Sample Request

{
  "status": "Enforcing"
}

Obtain Database Credentials

Default credentials are set at time of service creation.

Detail

Description

Endpoint

https://api.skysql.net/services/SERVICE_ID/security/credentials/

Method

GET

Behavior

  • Returns JSON with default username and default password.

  • Returned default password is as of time of service launch and does not reflect password changes.

Parameters

  • None

Response Code

200 - Success (expected)

API References

Sample Request

For a Service ID of db00000001:

https://api.skysql.net/services/db00000001/security/credentials/

Command-Line Example

$ curl --location \
   --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
   https://api.skysql.net/services/db00000001/security/credentials/ \
   | jq .

Sample Output

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

Obtain Service Connection Details

Service details are used to connect to the database service.

Detail

Description

Endpoint

https://api.skysql.net/services/SERVICE_ID/

Method

GET

Behavior

  • Returns JSON with service details, which can be filtered to those needed to connect to the service.

  • 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:

Parameters

  • None

Response Code

200 - Success (expected)

API References

Sample Request

For a Service ID of db00000001:

https://api.skysql.net/services/db00000001/

Command-Line Example

For a Service ID of db00000001:

curl --location \
  --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
  https://api.skysql.net/services/db00000001/ \
  | jq '{ "provider": .provider, "host": .fqdn, "read_only_port": .read_only_port, "read_write_port": .read_write_port, "ssl_tls": .ssl_tls }'

Sample Output

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

Using the Service

After creating a SkySQL service, it is typical to:

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

Detail

Description

Endpoint

https://api.skysql.net/services/SERVICE_ID/status/

Method

DELETE

Behavior

  • Deletes the service with Service ID of SERVICE_ID

Parameters

  • None

Response Code

200 - Success (expected)

API References

Sample Request

For a Service ID of db00000001:

https://api.skysql.net/services/db00000001/

Command-Line Example

For a Service ID of db00000001:

$ curl --location --request DELETE \
   --header 'Authorization: Bearer SKYSQL_BEARER_TOKEN' \
   https://api.skysql.net/services/db00000001/ \
   | jq .

Shell Scripting

curl is a command-line HTTP/HTTPS client.

jq is a command-line JSON processor.

curl and jq can be used together in shell scripts to interact with a REST API. For example:

#!/bin/env bash

SKYSQL_API_KEY='...'

SKYSQL_AUTH_RESPONSE="$(curl -sS --location --request POST \
   --header "Authorization: Token $SKYSQL_API_KEY" \
   --header 'Content-length: 0' \
   https://id.mariadb.com/api/v1/token/)"

if [[ "$SKYSQL_AUTH_RESPONSE" == *entitlements* ]]; then
   SKYSQL_BEARER_TOKEN="$(echo "$SKYSQL_AUTH_RESPONSE" | jq -r .token)"
else
   echo "Failed to authenticate with API key:"
   echo "$SKYSQL_AUTH_RESPONSE"
   exit 1
fi

SKYSQL_SERVICES_RESPONSE="$(curl -sS --location \
   --header "Authorization: Bearer $SKYSQL_BEARER_TOKEN" \
   https://api.skysql.net/services/)"

if [[ "$SKYSQL_SERVICES_RESPONSE" == '['* ]]; then
   (echo "Current services:"
    echo "$SKYSQL_SERVICES_RESPONSE" | jq .
    ) | less
else
   echo "Failed to get list of services:"
   echo "$SKYSQL_SERVICES_RESPONSE"
   exit 1
fi

Troubleshooting

Invalid token

Cause

An invalid SkySQL API key is provided when requesting a bearer token.

Effect

Authentication fails and an error is returned.

Solution

Use a valid SkySQL API key to request a bearer token.

Example Error

{
  "detail": "Invalid token."
}

JWT is invalid

JWT is short for "JSON Web Token".

Cause

An invalid or expired bearer token is provided when sending an API request.

Effect

Authentication fails and an error is returned.

Solution

Request a bearer token and re-send the request.

Example Error

{
  "detail": "JWT is invalid"
}

Setup incomplete

Cause

An API request is sent when account billing details are incomplete.

Effect

The API request fails with an error.

Solution

Setup account billing details.

Example Error

{
  "detail": "Setup incomplete, missing billing and/or default project"
}