Connect a managed database
Provision a database, connect your service, and understand backup and restore.
Choose an environment-managed database for access within one environment, or Managed Postgres for logical databases that can attach to services across the product’s environments. Configure the connection, then redeploy the consuming service.
Before you start
- Have a product, an environment and a service that needs a database.
- Choose the database model before provisioning; their connection and restore workflows differ.
- For MCP, use a product-scoped token with Deployment
writefor provisioning, connections, backups and resizing;readfor inspection; andadminfor restore or deletion.
1. Provision an environment database
On the environment canvas, choose Add service → Databases, or call deployment_managed_service_provision. Set the name and engine; choose a version and storage if the defaults do not fit.
Engine | Versions | Default |
|---|---|---|
PostgreSQL | 15, 16, 17 | 16 |
MySQL | 8.0, 8.4 | 8.4 |
Redis | 7, 8 | 7 |
MongoDB | 7, 8 | 8 |
Storage defaults to 5 GiB, with a range of 1–1024 GiB. The initial database name defaults to app for PostgreSQL, MySQL and MongoDB. The generated or chosen slug uses lowercase letters, digits and dashes, starts with a letter, and must be unique within the environment.
Wait for provisioning to become ready. If it becomes provisioning_failed, read the error and retry with deployment_managed_service_reconcile. Use deployment_managed_service_types to inspect available engines and versions.
2. Connect the service
Open the database node’s Connect view, or call deployment_managed_service_connect_info. Copy the reference for the connection value your library expects. Nothing is injected automatically.
For a PostgreSQL database with slug postgres, set service variable DATABASE_URL to ${{postgres.DATABASE_URL}}. Replace the slug with yours and mark the service variable as secret. All engines authenticate; passwords and full connection strings are secret values.
Engine | Published keys |
|---|---|
PostgreSQL | HOST, PORT, USER, PASSWORD, DATABASE, URL, DATABASE_URL, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE |
MySQL | HOST, PORT, USER, PASSWORD, DATABASE, URL, DATABASE_URL, MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE, MYSQL_URL |
Redis | HOST, PORT, PASSWORD, URL |
MongoDB | HOST, PORT, USER, PASSWORD, DATABASE, URL, MONGODB_URI |
Aliases carry the same values as the corresponding plain keys. An environment-managed database has no public address; connect from a service in the same environment.
3. Redeploy and verify it works
Redeploy the consuming service to resolve its variables. Check that the deployment becomes Active, then run an application read/write operation and read the result back. Inspect service and database logs if the connection fails; do not print credentials while diagnosing it.
Managed Postgres
For a product-level instance, use Databases → Add database, or deployment_cloud_sql_instance_create.
- Give the instance a label. Choose Postgres 16, 17 or 18 (default 18), and tier
db-custom-1-3840(default),db-custom-2-7680ordb-custom-4-15360. Creating the first Managed Postgres database from the environment canvas creates adefaultinstance if needed. - Create a logical database with
deployment_cloud_sql_database_create. Its label is optional; actual database and role names are generated. - Once the instance and database are ready, attach the database with
deployment_cloud_sql_database_attach. Supply the database, service and environment IDs. One database can attach to several services. - Redeploy each attached service and verify an application read/write operation.
Attachment creates secret service variables DATABASE_URL, PGHOST, PGPORT, PGUSER, PGPASSWORD and PGDATABASE. Passwords are not returned in database or instance views. Detaching removes those six variables; deleting a logical database detaches it from every service first.
Back up and restore
Model | Backup behavior | Restore scope |
|---|---|---|
Environment-managed database | Ready databases are backed up daily at 03:00 UTC. On-demand backups run while the database serves. All snapshots, including manual ones, expire after seven days. | Replaces that database’s contents in place; start from ready or stopped |
Managed Postgres | Nightly backups with point-in-time recovery; seven days of backups and transaction logs. On-demand backups keep the instance available. | Restoring a backup run replaces the entire instance, including every logical database, and makes it unavailable for several minutes |
Before restoring, take a fresh backup if current data still matters. In Backups, choose a completed snapshot or backup run. MCP uses deployment_managed_service_restore for an environment database or deployment_cloud_sql_instance_restore for an instance. The Managed Postgres dialog asks you to type the instance label.
After restore, wait for readiness and verify expected records through the application. Export data yourself if it must outlive the seven-day window.
An environment database’s last backup timestamp is recorded after a snapshot is confirmed ready and can lag by up to a day. An empty timestamp means no backup is recorded yet. Managed Postgres reports backup/PITR settings with their observation time; an unobserved blank value does not mean disabled.
Resize, stop or delete
Environment database Settings provides storage growth, stop, start and delete. Resize requires ready and cannot shrink storage. Stop requires ready, preserves storage and credentials, and prevents connections; stop dependent workloads first. Start resumes a stopped database with its data. Delete removes the database and storage.
Other lifecycle states include stopping, stopped, starting, resizing, backing_up, restoring and deleting. Wait for an action to finish before starting an incompatible one.
Managed Postgres instances can move to another supported tier. Instance deletion is refused while any logical database or attachment remains. Use the generated reference for exact lifecycle operation inputs.