Topology Selections with the SkySQL DBaaS API


This reference page details how to select topologies with the SkySQL DBaaS API for SkySQL.

SkySQL offers databases for Transactions (OLTP and general purpose) and Analytics (OLAP, ad hoc queries and large data) workloads.

Reliability and scaling features differ by topology, allowing you to right-size choices for your business needs.

Nodes running in AWS with a ARM64 hardware architecture use AWS Graviton processors.

Available Topologies

To choose a specific topology, you must also choose the corresponding service type:

Service Type

Topology Name

Topology Full Name





ColumnStore Data Warehouse

Run advanced analytical queries for millions of data records

  • MariaDB Enterprise ColumnStore

  • MariaDB MaxScale



Serverless Analytics

Zero-ETL, real time analytics on any data in SkySQL or cloud storage

  • Apache Spark SQL



Enterprise Server With Replica(s)

Read scaling with high availability

  • MariaDB Enterprise Server

  • MariaDB MaxScale



Enterprise Server Single Node

For small projects and development with moderate concurrency

  • MariaDB Enterprise Server



Xpand Distributed SQL

Read/write scaling with high concurrency and availability

  • MariaDB Xpand

  • MariaDB MaxScale

REST Client

A REST client can use the SkySQL DBaaS API to query topology selections and choose a topology for a new service.

Query Options with REST Client

A REST client can query the SkySQL DBaaS API for the topology selections for a specific service type.

To see the available topologies for a service type, use curl to call the /provisioning/v1/topologies API endpoint:

$ curl -sS --location \
   --header "Authorization: Bearer ${SKYSQL_API_KEY}" \
   '' \
   | jq .
    "id": "b34aa182-4c05-462f-8d4e-33a98de60803",
    "name": "es-single",
    "display_name": "Enterprise Server Single Node",
    "service_type": "transactional",
    "storage_engine": "innodb",
    "order": 100
    "id": "44a8a054-3d7a-4525-b104-b99b1e24d233",
    "name": "es-replica",
    "display_name": "Enterprise Server With Replica(s)",
    "service_type": "transactional",
    "storage_engine": "innodb",
    "order": 200
    "id": "fe99fb34-5299-4ba7-a5de-a24ccae64d88",
    "name": "xpand",
    "display_name": "Xpand Distributed SQL",
    "service_type": "transactional",
    "storage_engine": "xpand",
    "order": 300

For the topology that you would like to select, extract the name attribute from the output and provide that value to the /provisioning/v1/services API endpoint as the topology attribute.

Select Option with REST Client

A topology is selected during service launch. When using a REST client, select a topology by calling the /provisioning/v1/services API endpoint with the topology attribute set.

For example, prepare a request body containing the desired service options in a file called request-service.json:

$ cat > request-service.json <<EOF
  "service_type": "transactional",
  "topology": "es-single",
  "provider": "gcp",
  "region": "us-central1",
  "architecture": "amd64",
  "size": "sky-2x8",
  "storage": 100,
  "nodes": 1,
  "version": "10.6.11-6-1",
  "name": "skysql-nr-quickstart",
  "ssl_enabled": true

Then use curl to call the /provisioning/v1/services API endpoint to create (launch) a new database service and save the response to the response-service.json file:

$ curl -sS --location --request POST \
   --header "Authorization: Bearer ${SKYSQL_API_KEY}" \
   --header "Accept: application/json" \
   --header "Content-type: application/json" \
   --data '@request-service.json' \ \
   | tee response-service.json | jq .

Upon success, the command will return JSON with details about the new service.


Terraform can use the SkySQL Terraform provider to choose a topology for a new service. When using Terraform, select a topology using the topology attribute for the skysql_service resource:

# Create a service
resource "skysql_service" "default" {
  service_type        = "transactional"
  topology            = "es-single"
  cloud_provider      = "gcp"
  region              = "us-central1"
  architecture        = "amd64"
  size                = "sky-2x8"
  storage             = 100
  nodes               = 1
  version             = "10.6.11-6-1"
  name                = "skysql-nr-quickstart"
  ssl_enabled         = true
  deletion_protection = true
  wait_for_creation   = true
  wait_for_deletion   = true
  wait_for_update     = true
  is_active           = true