Topology Selections with the SkySQL DBaaS API

This page is part of MariaDB's Documentation.

The parent of this page is: Launch-Time Selections for the SkySQL DBaaS API

Topics on this page:

Overview
Available Topologies
REST Client
- Query Options with REST Client
- Select Option with REST Client
Terraform

Overview

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	Description	Products
`analytical`	`csdw`	ColumnStore Data Warehouse	Run advanced analytical queries for millions of data records	MariaDB Enterprise ColumnStore MariaDB MaxScale
`analytical`	`sa`	Serverless Analytics	Zero-ETL, real time analytics on any data in SkySQL or cloud storage	Apache Spark SQL
`transactional`	`es-replica`	Enterprise Server With Replica(s)	Read scaling with high availability	MariaDB Enterprise Server MariaDB MaxScale
`transactional`	`es-single`	Enterprise Server Single Node	For small projects and development with moderate concurrency	MariaDB Enterprise Server
`transactional`	`xpand`	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}" \
   'https://api.mariadb.com/provisioning/v1/topologies?service_type=transactional' \
   | 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
}
EOF

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' \
   https://api.mariadb.com/provisioning/v1/services \
   | tee response-service.json | jq .

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

Terraform

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
}