Databases API

SMLL runs PostgreSQL (CloudNativePG) and MySQL (Percona XtraDB Cluster). The API covers provisioning, credentials, backups, restores, replicas and forks.

All paths below are relative to:

https://api.smll.io/api/v1/workspaces/{workspaceID}/vpcs/{vpcID}/databases

Endpoints

Provision a database

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
        "name": "app-db",
        "engine": "postgresql",
        "instance_type": "smll.small",
        "storage_gb": 10,
        "postgres_version": "16",
        "replicas": 1,
        "external_access_enabled": true
      }' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases"

Provisioning is asynchronous. The response comes back with status: "creating"; poll the detail endpoint until it reads running.

Connection details

curl -s -H "$AUTH" \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases/$DATABASE_ID/connection"

The response carries both routes to the database:

Use the internal host from services in the same VPC: it stays inside the network and skips the edge proxy. Use the external host from your laptop, CI, or anything off-platform.

External access has to be switched on (external_access_enabled), and is then reachable at a per-database subdomain:

postgresql://app:<password>@<shortID>.eu-central-1.database.smllapp.com:5432/<shortID>
mysql://app-<shortID>:<password>@<shortID>.eu-central-1.mysql.smllapp.com:3306/<shortID>

<shortID> is the first 8 characters of the database UUID.

Backups and restores

Take a backup on demand:

curl -s -X POST -H "$AUTH" \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases/$DATABASE_ID/backups"

Restores do not overwrite the source. A restore provisions a new database from the backup, which is why the request takes a name:

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"app-db-restored","backup_name":"..."}' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases/$DATABASE_ID/backups/restore"

If the name is already taken in the VPC you get 409. If no completed backup exists yet, the platform triggers one and returns 409 telling you to retry shortly.

That shape is deliberate: recovery never destroys the thing you are recovering from. Point your application at the restored database once you have checked it.

Forks

A fork gives you a second database seeded from this one, for a staging environment or a migration rehearsal:

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"app-db-staging"}' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases/$DATABASE_ID/fork"

A fork is a restore in friendlier clothes: it takes the latest backup, triggering a fresh one first if none exists, and restores it into a new cluster. So the copy reflects the last backup rather than the parent's state this instant, and a fork of a busy database can take a while. It is a fully independent database from the moment it exists, and writes to it never reach the parent.

Replicas

curl -s -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"replicas":2}' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases/$DATABASE_ID/replicas"

Replicas serve reads through read_only_host. Each one is a running instance of the same plan and is metered as such, so check the cost estimator before scaling up.

Queries and schema

GET /schema returns tables and columns. POST /query runs SQL and returns rows. Both require Owner or Admin, because they can read and modify any data in the database.

These back the dashboard's SQL console. For application traffic, connect directly with a normal driver rather than proxying queries through the API.

IP allowlists

With external access on, the database is reachable from the internet and is protected by its password. An allowlist narrows that to known addresses:

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"cidr":"203.0.113.4/32","description":"office"}' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/databases/$DATABASE_ID/ip-allowlist"

An empty allowlist means no IP restriction, not a closed door. Adding the first rule is what starts the filtering, so add your own address before you add anything else, or you will lock yourself out.

Status values

Status is resynced against the live cluster whenever you list or read a database, so it reflects the cluster rather than the last thing the API was told.