PlanetScale

PlanetScale gives you a managed database, a branch of its schema, and a deploy request that puts the branch back onto production. Two capabilities answer that. /v1/provisioning (28 operations) makes the database — POST /v1/provisioning/sql launches your org's own PostgreSQL instance on port 5432 and answers with a postgres:// DSN. /v1/git (44) carries the other half, because the schema change is a file in a repo and that repo already has a branch, a proposal and a merge.

The structural difference is that one. PlanetScale hands you a second branch — inside the database, with its own host, its own password and its own deploy request number — that has to be kept in step with the git branch holding the same migration. Here there is one branch.

Start here

Mint a key, create the database, read it back until it says ready.

# 1. mint a key — sk- belongs on a server, pk- is safe in a browser
curl -sS -X POST https://api.hanzo.ai/v1/account/keys \
  -H "Authorization: Bearer $HANZO_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"type":"secret"}'

# 2. launch your org's own PostgreSQL instance — the DSN is in this answer only
curl -sS -X POST https://api.hanzo.ai/v1/provisioning/sql \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"orders"}'

# 3. read it back until status goes from provisioning to ready
curl -sS https://api.hanzo.ai/v1/provisioning/sql/orders \
  -H "Authorization: Bearer $HANZO_API_KEY"

Step 2 answers 201 with connectionString while the instance is still booting; step 3 reconciles status against the operator's live view, so ready there means psql will connect. Neither path carries an organization slug — the key does.

Core capabilities

Nouns

The database

Six other kinds sit on the same two routes: datastore for analytics, docdb on the MongoDB wire protocol, kv, search, vector and s3. Same body, same result shape, same one-name-per-resource rule.

The schema change

Insights, and the rest

The call

PlanetScale, from nothing to a deployed schema change:

curl -sS -X POST https://api.planetscale.com/v1/organizations/acme/databases \
  -H "Authorization: $PLANETSCALE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"orders","region":"us-east"}'

curl -sS -X POST \
  https://api.planetscale.com/v1/organizations/acme/databases/orders/branches \
  -H "Authorization: $PLANETSCALE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"add-line-items","parent_branch":"main"}'

curl -sS -X POST \
  https://api.planetscale.com/v1/organizations/acme/databases/orders/branches/add-line-items/passwords \
  -H "Authorization: $PLANETSCALE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"app","role":"readwriter"}'

curl -sS -X POST \
  https://api.planetscale.com/v1/organizations/acme/databases/orders/deploy-requests \
  -H "Authorization: $PLANETSCALE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"branch":"add-line-items","into_branch":"main"}'

curl -sS -X POST \
  https://api.planetscale.com/v1/organizations/acme/databases/orders/deploy-requests/12/deploy \
  -H "Authorization: $PLANETSCALE_TOKEN"

Five calls, and five identifiers that must agree: acme, orders, add-line-items, main, 12. A sixth is the git branch carrying the same migration, which this API never sees and cannot check.

Hanzo. The database, once:

curl -sS -X POST https://api.hanzo.ai/v1/provisioning/sql \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"orders","instance":"checkout"}'

{
  "id": "rs_7c1f",
  "kind": "sql",
  "name": "orders",
  "port": 5432,
  "status": "provisioning",
  "connectionString": "postgres://..."
}

There is no acme in that path. The store root and the instance both come from the org claim in the key, so a caller has no way to write another tenant's name down. instance binds the result: the checkout app's addons Secret receives SQL_URL, so the DSN reaches the process that needs it without a copy step. Omit instance and you keep the DSN yourself.

Then the schema change, on the branch you already pushed:

curl -sS -X POST https://api.hanzo.ai/v1/git/repos/orders/pulls \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"head":"add-line-items","base":"main","title":"add line items"}'

curl -sS -X POST https://api.hanzo.ai/v1/git/repos/orders/pulls/4/merge \
  -H "Authorization: Bearer $HANZO_API_KEY"

The merge is a fast-forward or nothing. It moves base only when base is already an ancestor of head — the case where nothing is lost and nothing is invented — and answers 409 when base has moved on independently, saying so. A deploy request is a state machine you poll through queued and in-progress; this answers with the revision base now points at. The build it fires is the same one a git push of those bytes fires, so merging is not a second road into production with its own rules. Proposing the same head into the same base twice while the first is open is a 409, so a retried run leaves one thing to review.

What does not carry

No database branch. PlanetScale forks the schema, and on a data branch the rows, into a copy with its own host and password. A name here is one instance and one DSN. A staging database is a second POST /v1/provisioning/sql under a second name, seeded by the same migrations rather than forked from production.

No deploy request, no schema diff, no revert window. PlanetScale reads your DDL, shows you the diff, applies it outside the request path and holds a window in which you can put it back. Nothing here reads your DDL. The merge moves a ref and the build runs your migration, so a bad migration is undone by another migration.

No backup or restore route. The API document has zero paths matching backup, restore or point-in-time. Restoring last night into a fresh branch, which is one of the better things PlanetScale sells, has no equivalent call. Schedule a dump on /v1/tasks (5) and land it in /v1/s3 (6).

No region, no size, no read replica. provisionRequest has exactly two fields, name and instance. There is nowhere to write us-east, ask for more memory, or add a read-only region. The instance lands in your org's tenant namespace and scales up rather than out.

No Vitess. No keyspaces, no vindexes, no horizontal sharding, and no online DDL running a ghost table behind your statement. The engine is PostgreSQL, so MySQL dialect, inline ENUM columns and SHOW statements go with it. If you are already on PlanetScale for Postgres, only the branch model changes.

The credential is returned once. connectionString and password come back at create and no read carries them again — GET /v1/provisioning/sql/{name} answers host, port, username and status, never the password — and there is no rotate route beside it. PlanetScale mints a new password whenever you ask. Lose this one and you provision again.