Managed databases for agents

Query, export, and administer a project's managed databases through the API. This page is written for an AI agent. It extends the deployment protocol at https://app.tokay.io/llms.txt. Everything here is an escape hatch. The happy path needs none of it, so act on an explicit user request or a named readiness action, not on your own initiative.

Last updated July 14, 2026

The resource model

• A project has at most one managed instance per engine (Postgres, MySQL, MongoDB, Redis), shared by every service in the project. A resource is one running engine, not one database.
• SQL engines hold named logical databases inside the one instance, such as app or auth. There is no bind mutation. Services bind to a logical database through confirmed env var wiring during deploy.
• The resource's default database is not where your app's tables live. Queries that omit database target the engine default, and relation does not exist there usually means the query ran without a database scope. The data is still where it was. Always pass the logical database name for SQL engines.
• The query endpoint is read only. Writes fail inside a read only transaction. Data fixes go through a one-off service task, whose environment holds real credentials. Schema changes go through migrations with a deploy.
• Connection values are versioned resource outputs. Rotation writes a new current version and old versions remain restorable, so a bad rotation is fixed with a rollback.
• An external database is not a resource. It arrives as an ordinary required secret holding the connection string.

What to call

Find the resource

query Resources($projectId: ID!) {
  project(id: $projectId) {
    projectResources(first: 10) {
      nodes {
        id resourceType runtimeName runtimeDatabase
        logicalDatabases(first: 20, orderBy: [NAME_ASC]) { nodes { name } }
      }
    }
  }
}

The id here is the Relay node ID the REST endpoints below expect in their URL path.

Query

POST {API_ORIGIN}/resources/:resourceId/query
{ "query": "select count(*)::int as n from tasks", "database": "app" }

query is a SQL string for Postgres and MySQL, a command array such as ["GET", "mykey"] for Redis, and an object in command or find form for MongoDB. database applies only to SQL engines and must name a logical database Tokay knows about. The response streams one JSON object per row, each on its own line.

Failed queries still return HTTP 200 with an error row in the stream, {"_tokay_error": "QUERY_FAILED", "message": "..."}, so check the first line before treating output as rows. Envelope problems (an unknown database, extra keys, an oversized body) return HTTP 400 with the same shape. The transaction is read only. INSERT fails with SQLSTATE 25006, and the fix is a one-off task or a migration, never retrying the endpoint.

Export

POST {API_ORIGIN}/resources/:resourceId/export_ticket
{ "format": "csv", "database": "app" }

Both keys are optional. The default format is native, meaning the engine's own dump form. CSV is supported for Postgres, MySQL, and MongoDB, and arrives as a ZIP with one CSV per table or collection. Redis has no honest CSV shape and returns EXPORT_FORMAT_UNSUPPORTED_FOR_ENGINE. database scopes a SQL export to one logical database, and omitting it exports all of them.

The response is {"downloadPath": "/resource_exports/<ticket>"}. GET {API_ORIGIN}{downloadPath} with no Authorization header streams the archive. The ticket works once and expires quickly. A second GET returns 404, so mint a fresh ticket per download.

Rotate and restore credentials

query Outputs($id: ID!) {
  projectResource(id: $id) {
    resourceOutputValues(first: 20, orderBy: CREATED_AT_DESC) {
      nodes {
        id isCurrent version createdAt
        resourceOutputDefinition { id name isUserRotatable isUserRollbackable }
      }
    }
  }
}

Rotate only when the user asks or a credential is known to be exposed. Rotation restarts consumers and is never routine maintenance. Only definitions with isUserRotatable: true accept rotation. For a managed Postgres that means the password. Host, port, and URL are derived from it. Rotation takes the definition id rather than the value id.

mutation Rotate($projectResource: ID!, $def: ID!) {
  rotateResourceOutputValue(input: { projectResource: $projectResource, resourceOutputDefinition: $def }) {
    resourceOutputValue { id version isCurrent }
  }
}

Rotation creates a new current version and Tokay redelivers the dependent values to consuming services without any code change. rollbackProjectResourceOutput makes the previous version current again and redoProjectResourceOutput reverses the rollback, both with the same input shape. Stored values are never readable back through the API, so track versions by version and createdAt, not by content.

Snapshots

query Snaps($id: ID!) {
  projectResource(id: $id) {
    projectResourceSnapshots(first: 10, orderBy: CREATED_AT_DESC) {
      nodes { id createdAt snapshotReason storageBytes storageRemovedAt }
    }
  }
}

Tokay snapshots a managed database immediately before a release action mutates it, and rehearsals may create their own temporary snapshots. Restore is a user decision, never a recovery you attempt on your own. It replaces current data, so summarize what will be lost and get the user's confirmation first, then call restoreProjectResourceSnapshot(input: { projectResourceSnapshot: $id }). A snapshot with storageRemovedAt set no longer holds restorable bytes.

Error shapes