DBaaS

Create a backup

POST /v1/dbaas/{id}/backups · scope dbaas:write · reversible · asynchronous · idempotent

Returns 202 as soon as the task starts, not when the archive is ready: a dump can take minutes, far beyond any HTTP timeout. The operation resolves against the backup list —a new one appears or it does not— rather than against the POST result, so it survives the call timing out while the backup is still running. Wait on it with GET /v1/operations/{id}.

curl https://api.truo.cloud/v1/dbaas/svc_10432/backups \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas backup create svc_10432

await truo.dbaas.backups.create("svc_10432");

truo_dbaas({
  "action": "backup_create",
  "id": "svc_10432"
})

operationId: dbaas.backups.create

List the service’s backups

GET /v1/dbaas/{id}/backups · scope dbaas:read

Newest first. A service whose engine has no managed backups returns an empty list, not an error.

curl https://api.truo.cloud/v1/dbaas/svc_10432/backups \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas backup list svc_10432

await truo.dbaas.backups.list("svc_10432");

truo_dbaas({
  "action": "backup_list",
  "id": "svc_10432"
})

operationId: dbaas.backups.list

Get connection details, without the credential

GET /v1/dbaas/{id}/connection · scope dbaas:read

Host, port, database, admin username, TLS mode, and the service’s CA — which is public and used to verify the server. It does not include the password or any URI containing it: the credential comes from POST /v1/dbaas/{id}/credentials, which requires the dbaas:credentials scope.

curl https://api.truo.cloud/v1/dbaas/svc_10432/connection \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas connection svc_10432

await truo.dbaas.connection.get("svc_10432");

truo_dbaas({
  "action": "connection",
  "id": "svc_10432"
})

operationId: dbaas.connection.get

Reveal the admin credential

POST /v1/dbaas/{id}/credentials · scope dbaas:credentials

Returns the admin password in plaintext. It rotates nothing: this is the credential already in use.

It is a POST rather than a GET on purpose. A GET lands in browser history, in any proxy’s logs, and in intermediate caches, and can be triggered accidentally from a link; a POST forces a deliberate action and enters the audit log as a mutation, so revealing a database’s credential leaves a trace. For the same reason it lives in its own scope (dbaas:credentials): dbaas:write creates scoped databases and users, while this grants full access to the data and survives revoking the key.

curl https://api.truo.cloud/v1/dbaas/svc_10432/credentials \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas credentials svc_10432

await truo.dbaas.credentials.create("svc_10432");

truo_dbaas({
  "action": "credentials",
  "id": "svc_10432"
})

operationId: dbaas.credentials.create

Create a database

POST /v1/dbaas/{id}/databases · scope dbaas:write · reversible · idempotent

charset and collation are MySQL-only; owner is PostgreSQL-only. Other engines ignore them. The response carries no size or table count: the database is born empty and re-reading it would cost another call just to report a zero.

curl https://api.truo.cloud/v1/dbaas/svc_10432/databases \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"appdb"}'

truo dbaas database create svc_10432

await truo.dbaas.databases.create("svc_10432", {"name":"appdb"});

truo_dbaas({
  "action": "database_create",
  "id": "svc_10432"
})

operationId: dbaas.databases.create

Delete a database

DELETE /v1/dbaas/{id}/databases/{name} · scope dbaas:write · destructive — cannot be undone · idempotent

Destructive and irreversible: the data is gone and there is no trash bin. All that remains is whatever is in GET /v1/dbaas/{id}/backups.

curl https://api.truo.cloud/v1/dbaas/svc_10432/databases/appdb \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas database delete svc_10432 appdb

await truo.dbaas.databases.delete("svc_10432", "appdb");

truo_dbaas({
  "action": "database_delete",
  "id": "svc_10432",
  "name": "appdb"
})

operationId: dbaas.databases.delete

List the service’s databases

GET /v1/dbaas/{id}/databases · scope dbaas:read

curl https://api.truo.cloud/v1/dbaas/svc_10432/databases \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas database list svc_10432

await truo.dbaas.databases.list("svc_10432");

truo_dbaas({
  "action": "database_list",
  "id": "svc_10432"
})

operationId: dbaas.databases.list

Get a database with its live state

GET /v1/dbaas/{id} · scope dbaas:read

Queries the backend. If it does not respond, the state fields come back null and capabilities omits databases/users instead of failing: a backend hiccup should not stop you from reading the rest of the resource.

curl https://api.truo.cloud/v1/dbaas/svc_10432 \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas get svc_10432

await truo.dbaas.instances.get("svc_10432");

truo_dbaas({
  "action": "get",
  "id": "svc_10432"
})

operationId: dbaas.instances.get

List managed databases

GET /v1/dbaas · scope dbaas:read

Served from the database, without querying the backend: engine, state, host, and plan come back null, and capabilities omits databases and users because knowing whether the engine has them would cost one call per page item. An absent key means “not queried”, which is not the same as false. For the live state of one, use GET /v1/dbaas/{id}.

curl https://api.truo.cloud/v1/dbaas \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas list

await truo.dbaas.instances.list();

truo_dbaas({
  "action": "list"
})

operationId: dbaas.instances.list

Restart the engine

POST /v1/dbaas/{id}/restart · scope dbaas:write · reversible · idempotent

Drops open connections: in-flight transactions are lost. Returns 202 with an already-completed operation —the restart is synchronous in both backends— so clients treat every long mutation the same way, and so the day it stops being synchronous, only the operation’s backend column changes, not the contract.

curl https://api.truo.cloud/v1/dbaas/svc_10432/restart \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas restart svc_10432

await truo.dbaas.instances.restart("svc_10432");

truo_dbaas({
  "action": "restart",
  "id": "svc_10432"
})

operationId: dbaas.instances.restart

Get the engine log’s last lines

GET /v1/dbaas/{id}/logs · scope dbaas:read

The tail of the engine process’s log, oldest to newest. It is not a query log or an audit log: these are the engine’s startup messages, errors, and warnings.

curl https://api.truo.cloud/v1/dbaas/svc_10432/logs \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas logs svc_10432

await truo.dbaas.logs.get("svc_10432");

truo_dbaas({
  "action": "logs",
  "id": "svc_10432"
})

operationId: dbaas.logs.get

Get instance metrics

GET /v1/dbaas/{id}/stats · scope dbaas:read

A snapshot, not a time series. Which fields are populated depends on the service’s backend: some measure the container and others the engine.

curl https://api.truo.cloud/v1/dbaas/svc_10432/stats \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas stats svc_10432

await truo.dbaas.stats.get("svc_10432");

truo_dbaas({
  "action": "stats",
  "id": "svc_10432"
})

operationId: dbaas.stats.get

Create a user

POST /v1/dbaas/{id}/users · scope dbaas:write · reversible · idempotent

The password is neither stored on our side nor returned later: if it is lost, change it with POST /v1/dbaas/{id}/users/{username}/password.

curl https://api.truo.cloud/v1/dbaas/svc_10432/users \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"app","password":"<password>"}'

truo dbaas user create svc_10432

await truo.dbaas.users.create("svc_10432", {"username":"app","password":"<password>"});

truo_dbaas({
  "action": "user_create",
  "id": "svc_10432"
})

operationId: dbaas.users.create

Delete a user

DELETE /v1/dbaas/{id}/users/{username} · scope dbaas:write · destructive — cannot be undone · idempotent

Cuts off everything currently connected as that user. It deletes no data: the databases the user created remain.

curl https://api.truo.cloud/v1/dbaas/svc_10432/users/app \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas user delete svc_10432 app

await truo.dbaas.users.delete("svc_10432", "app");

truo_dbaas({
  "action": "user_delete",
  "id": "svc_10432",
  "username": "app"
})

operationId: dbaas.users.delete

List the engine’s users

GET /v1/dbaas/{id}/users · scope dbaas:read

Includes the admin. On MySQL the same name can appear with several host values: the user@host pair is what identifies the user, and that is why it is the resource’s id.

curl https://api.truo.cloud/v1/dbaas/svc_10432/users \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo dbaas user list svc_10432

await truo.dbaas.users.list("svc_10432");

truo_dbaas({
  "action": "user_list",
  "id": "svc_10432"
})

operationId: dbaas.users.list

Change a user’s password

POST /v1/dbaas/{id}/users/{username}/password · scope dbaas:write · reversible · idempotent

Takes effect immediately: applications still using the old one will fail on reconnect. It also works for the admin user.

curl https://api.truo.cloud/v1/dbaas/svc_10432/users/app/password \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"<password>"}'

truo dbaas user password svc_10432 app

await truo.dbaas.users.set_password("svc_10432", "app", {"password":"<password>"});

truo_dbaas({
  "action": "user_set_password",
  "id": "svc_10432",
  "username": "app"
})

operationId: dbaas.users.set_password