Connect a database to your app

Requirements: PostgreSQL connections require agent 0.6.13+; MariaDB requires agent 0.6.17+. Local connection tools require MCP 0.36.0+; the backup recovery tools require MCP 0.39.0+. Update existing agents explicitly before creating a connection. Each operation requires the matching engine capability; PostgreSQL rotation uses postgres-service-binding-rotation-v1.

A service binding gives one application a dedicated database and login. For PostgreSQL, database ownership is held by a separate role that cannot log in. The application receives a dedicated login; rotating or removing it retains database ownership and data. The platform stores an encrypted credential; only the authorized agent obtains it for the matching controlled deployment. The application receives DATABASE_URL in its private runtime environment. The provider's administrator password is not copied to the application or returned through the portal or MCP.

Before you start

Use a generated image-mode custom application and a running PostgreSQL or MariaDB catalog application on the same server. Associate both with the same project environment: the consumer has a web or worker role and the provider has the database role. The consumer must be running or failed, and neither application may have a pending runtime operation.

An existing DATABASE_URL, custom network layout, source build, different server or an engine other than PostgreSQL/MariaDB is not supported. The agent must support deploy-cancel-v1 and the matching engine protocol: postgres-service-binding-v2 (agent 0.6.13+) or mysql-service-binding-v2 (agent 0.6.17+). Incompatible agents receive no binding deployment command.

API credentials need deploy scope to prepare/apply and read to read a review. Hosted MCP requires unrestricted account credentials. Portal changes require the account's service-management permission and a valid session CSRF token; viewers can read a saved review.

Review in the portal

In My apps → Advanced, open Database connection on the image application's card. Select a PostgreSQL or MariaDB provider on the same server and choose Review database connection. Verify the application, provider, environment, managed variable, dedicated database and expiry before choosing Confirm and connect.

Preparation does not create a database or enqueue a deployment. Applying may restart the application and interrupt traffic. A saved connection reference on the card is configuration evidence, not a live connectivity check.

Use MCP

Call impreza_prepare_service_binding with deployment_id and provider_deployment_id.
Read the returned changes and review_digest. The returned plan_id identifies the saved review.
Call impreza_get_service_binding_plan with binding_plan_id to read it again.
After explicit confirmation, call impreza_apply_service_binding_plan with binding_plan_id, the exact review_digest and confirm: true.
Follow the returned command_id in deployment history. Acceptance means queued; it does not mean the database is connected or healthy.

Neither the review nor its receipt contains a password. Do not ask the customer to paste a generated database credential into an MCP conversation.

Environment wiring: preparation also accepts wire: true — on apply, every other eligible web/worker component of the same environment receives its own binding to the same provider, each with its own credential and deploy job; the receipt names anything skipped. Available through the REST API and hosted MCP since 25 September 2026. See environment wiring.

REST contract

Use the standard authenticated API headers. Replace IDs and the digest with values returned for your account.

POST /v1/platform/deployments/custom/dpl_aaaaaaaaaaaaaaaa/prepare-binding
Content-Type: application/json

{"provider_deployment_id":"dpl_bbbbbbbbbbbbbbbb"}

The 201 response includes plan_id, review_digest, expires_at, status: "ready_for_review" and the reviewed changes. It contains no secret. The optional boolean wire fans the connection out to the environment's other eligible web/worker components on apply (one binding each); see environment wiring.

GET /v1/platform/binding-plans/bplan_cccccccccccccccccccccccc

POST /v1/platform/binding-plans/bplan_cccccccccccccccccccccccc/apply
Content-Type: application/json

{"review_digest":"<64-character digest from this review>","confirm":true}

A 202 response contains an accepted receipt and replayed. Repeating the same plan with its exact digest returns the same command receipt rather than creating another deployment. If the response is lost, read the saved plan and retry that same confirmation.

Verify the result

The agent checks provider container/network identity, provisions the dedicated engine-specific login/database and verifies password authentication before replacing the consumer. The application keeps its routes, resource limits and volumes. The connection uses the provider's existing private Docker network; it adds no host port and does not change the catalog provider's existing published ports.

Check the deployment result, then verify a database operation from your application. A successful historical receipt is not a continuous health guarantee. A failed credential authorization during preparation preserves the previous serving container and runtime credential in the tested synchronous path.

Route updates preserve the local managed credential. API variable edits and redeploy inputs cannot override DATABASE_URL while the binding reference is configured. Exact generated credentials are redacted in deployment output and log transport; the application and server administrator still control the data they can read. This is not a guarantee against arbitrary secret encoding or deliberate fragmentation.

Manual image rollback refuses a retained release that changes the managed database connection. It cannot restore an older database login independently of the connection workflow. This refusal happens before replacing containers; ordinary application settings keep their existing rollback behavior.

Review connection removal

In the same Database connection section, a manager can choose Review connection removal. The review identifies the exact application, binding and database. Confirming queues a replacement without the managed DATABASE_URL or provider network. The agent disables the dedicated login and its password only after it verifies a healthy replacement without that attachment. The database, role and stored data are retained; this is not a database deletion operation.

With MCP, call impreza_prepare_service_binding_removal with the consumer's deployment_id and its exact binding_id. Read and apply the returned plan using the existing review tools and explicit confirmation. The equivalent REST preparation is:

POST /v1/platform/deployments/custom/dpl_aaaaaaaaaaaaaaaa/prepare-binding-removal
Content-Type: application/json

{"binding_id":"bnd_eeeeeeeeeeeeeeeeeeeeeeee"}

The review includes operation: "remove", database_data_retained: true, login_disabled_after_replacement: true and cleanup_retry. Preparing does not queue work. Applying may interrupt traffic; follow the resulting command rather than treating acceptance as completion.

A successful replacement can still report cleanup as pending. The card then shows removal pending verification. After the current operation finishes, use Review cleanup retry, or prepare another removal review for the same binding. Each retry needs its own review and confirmation. Repeating an already accepted review only retrieves its receipt. Redeploy, promotion and manual rollback cannot overwrite pending cleanup.

The agent needs postgres-service-binding-retire-v2 and controlled-deployment support (agent 0.6.13+). An incompatible agent does not receive the removal command; update it explicitly first. Only an accepted matching retired outcome erases the encrypted server-side binding credential. Historical runtime releases can still contain the old credential in private agent storage; it is no longer a usable login after verified retirement.

Rotate the credential

A manager can replace the dedicated login of an existing connection without losing the database or its data. The agent creates a distinct new login, replaces the application with the rotated DATABASE_URL and disables the previous login only after the replacement is healthy. If startup fails, the previous application keeps serving with the current credential. Preparing a rotation never changes the serving credential.

In the same Database connection section, choose Rotate credentials. Verify the application, provider, environment, managed variable, rotation reference and expiry before choosing Confirm rotation. While a rotation is outstanding, the card shows it as in progress and offers Review rotation retry and Review abandonment instead. Retrying applies the pending credential change; abandoning discards it and keeps the current credential. Either restarts the application and may interrupt traffic.

With MCP, call impreza_prepare_service_binding_rotation with the consumer's deployment_id, its exact binding_id and mode (rotate or abandon). Read and apply the returned plan using the existing review tools and explicit confirmation. The equivalent REST preparation is:

POST /v1/platform/deployments/custom/dpl_aaaaaaaaaaaaaaaa/prepare-binding-rotation
Content-Type: application/json

{"binding_id":"bnd_eeeeeeeeeeeeeeeeeeeeeeee","mode":"rotate"}

The review includes operation: "rotate" (or "abandon_rotation"), rotation_id, database_data_retained: true, credential_delivery: "agent_only" and, for an outstanding operation, retry and cleanup_only. It expires after 15 minutes and contains no secret. Apply it through the existing POST /v1/platform/binding-plans/{plan_id}/apply with its exact review_digest and confirm: true. Acceptance queues one controlled replacement; follow the resulting command rather than treating acceptance as completion.

Required healthy startup: rotation reviews require runtime.startup.require_healthy: true for rotation and abandonment. Each running container must provide a Docker healthcheck and report healthy; merely being running is insufficient. An existing startup timeout is retained (30–600 seconds), otherwise it defaults to 60 seconds. Failed checks recover the previous release where available and retain the credentials for a reviewed retry. The required startup policy remains on the application after completion. Use a healthcheck that tests your application's readiness, including database access when needed; Docker health alone cannot prove that every application function works. The control plane enforces this policy. Agent 0.6.15 adds an independent guard against commands with missing or optional health requirements; update existing agents explicitly after active operations finish. Local MCP 0.37.1 clarifies that the apply tool also applies reviewed credential rotation.

A failed startup retains both credentials and requires a newly reviewed retry. If the replacement is healthy but the previous login could not be confirmed disabled, the rotation stays pending cleanup; prepare another rotate review to retry that cleanup. Abandonment discards the unused candidate credential and keeps the current one, and is refused once only cleanup remains. Each retry or abandonment needs its own review and confirmation.

Rotation requires an agent announcing postgres-service-binding-rotation-v1. An incompatible agent refuses the command, and the failed job directs you to update the agent explicitly, which preserves its identity, configuration and applications. Rotation also requires a connection on the current v2 protocol. Connections created through the current workflow already use it; an earlier first-protocol connection is not adopted for rotation.

Limits and recovery

Reviews expire after 15 minutes; at most 20 pending reviews are stored per account.
Changes to the application, provider, environment, ownership or binding rules invalidate the review. Prepare a new one rather than editing its payload.
Applying serializes concurrent confirmations and stores the binding, manifest, job and receipt atomically. A storage failure rolls that transaction back.
An active connection or pending removal prevents uninstalling either application or detaching either project membership. Complete and verify removal before changing those dependencies.
Variable reads, edits and lifecycle commands recheck current server ownership. A deployment's historical account ID alone does not authorize access after its server changes owner.
PostgreSQL objects with unverifiable ownership are refused. Existing data is not silently adopted or deleted.
After a verified retirement, an unconfirmed result remains in the agent's private journal. Recovery after agent or server restart resends that result without repeating the replacement. The receipt is cleared only after the API acknowledges it.
A restart during an incomplete replacement or a missing/unverifiable receipt still requires review. A restart during replacement is not proof that the operation completed.
Do not manually reset a managed PostgreSQL login outside the reviewed rotation: the running application and its retained configuration may still depend on that credential.
A pending rotation serializes against connection removal, redeploy, promotion, rollback and a second rotation. Complete or abandon it before changing those dependencies; those operations cannot overwrite a pending rotation or its cleanup.
It does not provide cross-host networking, host-wide egress isolation, replicas or automatic agent updates; PostgreSQL point-in-time recovery is a separate workflow. Managed PostgreSQL backup and assisted restore require the newer agent protocol described below.

See project environments, image promotion, deployment safety and explicit agent updates.

Consistent backups and assisted restore

Available with agent 0.6.18+ and the capabilities below. Update existing agents explicitly. Managed database verification runs within the existing backup workflow; assisted restoration uses the portal, REST API and MCP.

A backup of a supported managed PostgreSQL binding adds a consistent pg_dump and mandatory restoration into a temporary verification database. Verification receives a temporary, operation-scoped login with no membership of the stable database owner; the serving login is confined to the dump stage. The result includes the verified table count and dump checksum, and the agent removes the temporary database and login before reporting success. An unverified database backup or failed cleanup fails closed. This does not make filesystem volumes and PostgreSQL one atomic application snapshot. Pending credential rotation/removal, an offline provider or a legacy binding is refused. The agent must announce postgres-service-binding-backup-v2 and controlled-deployment support.

Assisted database restoration is available in the portal, REST API and local MCP 0.39.0+. See the recovery workflow. With deploy scope, call POST /v1/backups/{backup_id}/prepare-database-restore with optional target_binding_id (omit to use the original connection); inspect the returned new database name and review. Read it with GET /v1/database-restores/{restore_id} (read scope), then apply using POST /v1/database-restores/{restore_id}/apply with the exact review_digest and boolean confirm: true.

The agent must announce postgres-service-binding-restore-v2. Only a verified managed dump matching the target database engine is accepted, with a maximum expanded size of 512 MiB. SQL from the archive runs through a temporary login that can create objects only in the new database and cannot assume the stable owner role or administer the serving database. After a successful restore, the agent transfers the new objects to the stable owner and removes the temporary login. Current ownership of source backup, storage and both target apps is checked again at apply and credential dispatch. Transferred or revoked resources return 404; changed or busy resources and stale reviews return 409.

The restore verifies downloaded chunks and the reviewed dump checksum, restores into a new database, and verifies its table count. Source ACLs are not imported and the new database grants no privileges to PUBLIC. The existing binding is not cut over. Review the returned command's verified result before considering a manual migration. A failed cleanup requires investigation; a retained temporary database can contain data. PITR/WAL archiving, automatic cutover and native MySQL providers are outside this workflow. An eligible target binding may be on another server; only its provider receives the new database, and application traffic stays unchanged.

MariaDB connections

Agent 0.6.17+ supports the MariaDB catalog provider through the same reviewed connection, removal and rotation workflows. The engine is derived from the provider; clients cannot override it. MariaDB uses dedicated logins with grants limited to the managed database, not PostgreSQL owner roles. Removal retains the database and retires access; rotation requires a healthy application. The agent must announce the matching mysql-service-binding-v2 and rotation capabilities. Do not apply PostgreSQL SQL or recovery procedures to MariaDB. Agent 0.6.18+ adds mysql-service-binding-backup-v1 and mysql-service-binding-restore-v1. Each backup must restore successfully into a scratch database before success. The verification and restore stages use temporary logins restricted to the new database, with exact database grants and cleanup of both users and grants. The serving login receives no additional access; a successful assisted restore retains its new database for administrator inspection without a cutover.

Supported snapshots contain InnoDB tables only. Views, triggers, routines, events and other table engines are refused; avoid concurrent schema changes. A process or host crash can leave data or a temporary login requiring administrator reconciliation. See recovery limits.

For configuration export, metrics and backup download/restore, see application operations.

Review a managed database connection