Databases

A managed database is provisioned and versioned the same way an app is, and reachable from apps in the same environment as db-<slug>. Backups are on Backups, the console on Console and logs.

ReadingCopy Anchor Link

databasesCopy Anchor Link

Any signed-in principal. Returns [Database!].

All databases in the active team, newest first.

query {
  databases(q: "shop") {
    id
    name
    type
    version
    status
    host
    port
  }
}

databaseCopy Anchor Link

Any signed-in principal. Returns Database.

One database by id, or null.

query {
  database(id: "db_9f1c2ab7d3e4f5a6") {
    id
    name
    type
    version
    status
    host
    port
  }
}

databaseRuntimeCopy Anchor Link

Any signed-in principal. Returns AppRuntime.

Live container state for a database, straight from the owning agent. Polled by the database's status badge (same shape as appRuntime).

query {
  databaseRuntime(databaseId: "db_9f1c2ab7d3e4f5a6") {
    running
    total
    unhealthy
    unreachable
  }
}

Creating and settingsCopy Anchor Link

createDatabaseCopy Anchor Link

Needs create_databases. Returns Database.

Provision a managed database. username, password and dbName are generated when omitted; environmentId files it into an environment, or omit it for the team's top level.

mutation {
  createDatabase(input: { name: "orders", type: postgres, version: "17" }) {
    id
    name
    type
    version
    status
    host
    port
  }
}

updateDatabaseCopy Anchor Link

Needs configure_databases. Returns Database.

Edit a database's public exposure (publish/unpublish + host port) and, optionally, the server it runs on. An in-place edit re-renders the compose and reroutes the container on its current host (data volume preserved). A server change recreates the container on the new host, COPIES its data volume there host-to-host (relayed through the control plane, not via S3) so the data follows the move, then tears down the old host's stack. The copy runs with both stacks stopped and rolls back on failure (the DB stays put). The connection string is re-derived. Everything else is create-only. The publish-ports grant is enforced in the data layer when exposure is on.

mutation {
  updateDatabase(
    id: "db_9f1c2ab7d3e4f5a6"
    input: { exposedPublicly: true, exposedPort: 5432 }
  ) {
    id
    name
    type
    version
    status
    host
    port
  }
}

updateDatabaseImageCopy Anchor Link

Needs configure_databases. Returns Database.

Save the database's expert overrides: custom image, custom command, and/or engine version (image tag). Applied on the next redeploy. An absent field is left unchanged; an explicit null clears the override.

mutation {
  updateDatabaseImage(id: "db_9f1c2ab7d3e4f5a6", input: { version: "17.2" }) {
    id
    name
    type
    version
    status
    host
    port
  }
}

updateDatabaseResourcesCopy Anchor Link

Needs configure_databases. Returns Database.

Save the database's per-container resource limits. Applied on the next redeploy or settings-driven reroute.

mutation {
  updateDatabaseResources(
    id: "db_9f1c2ab7d3e4f5a6"
    limits: { memoryMb: 512, cpuMilli: 500 }
  ) {
    id
    name
    type
    version
    status
    host
    port
  }
}

setDatabaseMountsCopy Anchor Link

Needs configure_databases. Returns Database.

Replace the database's config files (whole set - an omitted file is removed) and APPLY them: the files are written next to the stack and the container is recreated, unlike the image/command overrides beside them. A path inside the engine's data directory is refused.

mutation {
  setDatabaseMounts(
    id: "db_9f1c2ab7d3e4f5a6"
    mounts: [{ filePath: "postgresql.conf", mountPath: "/etc/postgresql/postgresql.conf", content: "max_connections = 200\n" }]
  ) {
    id
    name
    type
    version
    status
    host
    port
  }
}

renameDatabaseCopy Anchor Link

Needs configure_databases. Returns Database.

Rename a database - its DISPLAY name only. The container's identity (compose project, data volume, DNS name and therefore the connection string) is fixed at creation and is untouched, so nothing restarts. The name must be unique within the team.

mutation {
  renameDatabase(id: "db_9f1c2ab7d3e4f5a6", name: "orders") {
    id
    name
  }
}

updateDatabaseLogoCopy Anchor Link

Needs configure_databases. Returns Database.

Set the database's display logo (an image data-URI), or clear it with null to fall back to the engine's own brand mark. Cosmetic only.

mutation {
  updateDatabaseLogo(id: "db_9f1c2ab7d3e4f5a6") {
    id
    name
    type
    version
    status
    host
    port
  }
}

reorderDatabasesCopy Anchor Link

Needs configure_databases. Returns Boolean.

Persist the team-wide order of databases in the Storage grid. Ids are sanitised to the team's own databases; omitted ones are appended. Returns true.

mutation {
  reorderDatabases(databaseIds: [["db_9f1c2ab7d3e4f5a6"]])
}

generateAvailableDbPortCopy Anchor Link

Needs create_databases. Returns Int.

Suggest a host port that is currently free on the target server, for the database 'Expose publicly' flow. Requires the publish-ports grant.

mutation {
  generateAvailableDbPort(serverId: "srv_9f1c2ab7d3e4f5a6")
}

Running and recreatingCopy Anchor Link

setDatabaseRunningCopy Anchor Link

Needs control_databases. Returns Database.

Start (running: true) or stop the database container.

mutation {
  setDatabaseRunning(id: "db_9f1c2ab7d3e4f5a6", running: false) {
    id
    status
  }
}

restartDatabaseCopy Anchor Link

Needs control_databases. Returns Database.

Restart the database container (stop + start) without re-rendering its compose. Use redeployDatabase to apply pending settings.

mutation {
  restartDatabase(id: "db_9f1c2ab7d3e4f5a6") {
    id
    name
    type
    version
    status
    host
    port
  }
}

redeployDatabaseCopy Anchor Link

Needs control_databases. Returns Database.

Re-render the database's compose from its current settings (resource limits, image/command overrides, exposure) and reroute it on its server. The container is recreated only when its config actually changed; the data volume is always preserved.

mutation {
  redeployDatabase(id: "db_9f1c2ab7d3e4f5a6") {
    id
    name
    type
    version
    status
    host
    port
  }
}

rebuildDatabaseCopy Anchor Link

Needs delete_databases. Returns Database.

DESTRUCTIVE factory reset: tear down the database container AND its data volume, then re-provision a fresh, empty stack from the current settings - same engine, version and credentials, so the connection string is unchanged. ALL DATA IS ERASED. Use redeployDatabase for the data-preserving recreate.

mutation {
  rebuildDatabase(id: "db_9f1c2ab7d3e4f5a6") {
    id
    name
    type
    version
    status
    host
    port
  }
}

setDatabaseRestartLoopGuardCopy Anchor Link

Needs configure_databases. Returns Boolean.

Turn restart loop protection on or off for one database. Applies at once - there is nothing to redeploy.

mutation {
  setDatabaseRestartLoopGuard(id: "db_9f1c2ab7d3e4f5a6", value: true)
}

deleteDatabaseCopy Anchor Link

Needs delete_databases. Returns Boolean.

Delete its stored backups, then stop and destroy the database's container + data volume on its server, then delete it (dependent backup schedules cascade). A backup that cannot be deleted stops it all unless force, which leaves it to the orphan sweep. The teardown must verifiably succeed: if the server can't be reached, or something of the stack survives it, nothing is deleted and the mutation errors, so a live database is never silently forgotten. force deletes the record anyway (for a host that is never coming back) and queues the teardown, which Deplo retries until the host confirms it. Returns true.

mutation {
  deleteDatabase(id: "db_9f1c2ab7d3e4f5a6")
}

CredentialsCopy Anchor Link

Both return the connection string as a String, not the entity. rotateDatabasePassword cuts off anything still using the old credentials the moment it succeeds.

revealConnectionCopy Anchor Link

Needs reveal_secrets. Returns String.

Reveal the full (unmasked) connection string for a database.

mutation {
  revealConnection(id: "db_9f1c2ab7d3e4f5a6")
}

rotateDatabasePasswordCopy Anchor Link

Needs configure_databases. Returns String.

Rotate the database's engine password (auto-generated when none is given) and return the NEW connection string - shown once, like revealConnection. Engines that persist users in the data volume are told first via an exec in the running container; the compose is then re-rendered so env/command/healthcheck agree. Requires the database to be running.

mutation {
  rotateDatabasePassword(id: "db_9f1c2ab7d3e4f5a6")
}

Moving to another teamCopy Anchor Link

Needs move_databases in both teams. Ask databaseTransferInfo first: it lists the teams that can take it and what the move removes. See Move to another team.

databaseTransferInfoCopy Anchor Link

Needs move_databases. Returns DatabaseTransferInfo.

What transferring this database to another team would change, and which of the viewer's other teams could take it.

query {
  databaseTransferInfo(id: "db_9f1c2ab7d3e4f5a6") {
    backupCount
    cronCount
    databaseName
    environmentName
  }
}

transferDatabaseToTeamCopy Anchor Link

Needs move_databases. Returns Boolean.

Hand this database, with its data, to another team the viewer belongs to. It lands at that team's top level and restarts on its network; backup schedules and cron jobs are removed. Returns true.

mutation {
  transferDatabaseToTeam(id: "db_9f1c2ab7d3e4f5a6", teamId: "team_9f1c2ab7d3e4f5a6")
}

SubscriptionCopy Anchor Link

databaseStatusCopy Anchor Link

Any signed-in principal. Returns Database.

Emits the database whenever its status changes (provisioning -> running, start/stop, redeploy, ...). Fires once immediately with the current snapshot, then on every change; ends when the database is deleted.

subscription {
  databaseStatus(id: "db_9f1c2ab7d3e4f5a6") {
    id
    status
  }
}

See alsoCopy Anchor Link