Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Understand the managed database model before creating, connecting, backing up, importing, or promoting one.

​
Prerequisites

  • Basic knowledge of relational databases

​
Workflow

1
Treat databases as their own resource type, not as special cases of stacks.
2
Connect applications through the displayed stable endpoint rather than a physical runtime address.
3
Use Backups for durable recovery and Import / Export for portable logical SQL movement.

​
Project and standalone databases

A database can belong to a project or directly to your account. Both contexts expose the same core detail surfaces, but authorization and API paths differ. Project database reads require project access and mutations require project mutation permission. Standalone databases are owner-only. A database used through the wrong route family, a cross-tenant identifier, or a hidden transfer candidate returns not found rather than exposing the resource.
  • Project base: /api/v1/projects/{projectID}/databases/{databaseID}.
  • Standalone base: /api/v1/databases/{databaseID}.
  • The dashboard provides equivalent database and Import / Export views in both contexts.

​
Engines and capability scope

The general managed database surface supports PostgreSQL, MySQL, and Redis. Full-database Import / Export is narrower: it requires a running PostgreSQL or MySQL database on the digest-qualified hosted V2 containerd runtime, a stable-endpoint lineage, and a transfer-capable hosted agent.
  • Redis is not eligible for full SQL transfer.
  • Connected-node, legacy, and unqualified database runtimes are not eligible.
  • Selective table export, server-global roles/grants, custom URL authentication headers, and automatic promotion are excluded.
  • Eligible transfers are available on every active plan; transfer creation has no plan-tier entitlement check.

​
Stable endpoint identity

A hosted V2 database has one logical identity and a current physical generation. Applications connect to the stable hostname. Import candidates and retained generations are internal physical generations and never become application connection targets. Transfer promotion changes which physical generation the stable endpoint serves while preserving the private/public hostname, port, database name, credentials, CA, TLS policy, public-access mode and allowlist, proxy policy, and firewall policy. The previous generation remains read-only for the exact rollback window.

​
What the database detail surface includes

  • Provisioning, running, stopping, recovery, and failure state.
  • Stable connection details and credentials on demand.
  • Private and public-access policy, including allowlists where enabled.
  • Metrics, logs, observability, database browsing, and lifecycle actions.
  • Pooler, clone, backup, and restore controls where eligible.
  • Import / Export for qualified hosted V2 PostgreSQL and MySQL databases.

​
Backups and transfers are different

Backups are the durable recovery path and use recovery-specific encryption, credentials, records, retention controls, and storage. Import / Export moves portable logical SQL through an independent private transfer bucket with short-lived artifacts. A transfer export is not a backup policy, and a backup artifact cannot be substituted as transfer validation evidence.

​
Expected result

You can choose the correct database context, connection identity, recovery path, and transfer workflow without relying on hidden runtime details.

Create a database

Provision a managed database with the right engine, size, context, access, and hosted V2 expectations.

Credentials, pooling, and usage expectations

Use stable connection details, TLS, public-access policy, and pooler endpoints without relying on physical runtime addresses.

Import and export a database

Move complete PostgreSQL or MySQL databases as portable SQL with resumable uploads, private candidates, structural validation, explicit promotion, and 24-hour rollback.

Back up and restore a database

Use durable recovery storage correctly and understand why backups are independent from portable SQL transfers.