# Review a managed database connection

Source: https://docs.imprezahost.com/service-bindings.html

**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](project-environments.html): 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

1. Call `impreza_prepare_service_binding` with `deployment_id` and `provider_deployment_id`.
2. Read the returned changes and `review_digest`. The returned `plan_id` identifies the saved review.
3. Call `impreza_get_service_binding_plan` with `binding_plan_id` to read it again.
4. After explicit confirmation, call `impreza_apply_service_binding_plan` with `binding_plan_id`, the exact `review_digest` and `confirm: true`.
5. 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](project-environments.html#environment-wiring).

## REST contract

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

```http
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](project-environments.html#environment-wiring).

```http
GET /v1/platform/binding-plans/bplan_cccccccccccccccccccccccc
```

```http
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:

```http
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:

```http
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](agent-updates.html), 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](customer-workflows.html#pitr) is a separate workflow. Managed PostgreSQL backup and assisted restore require the newer agent protocol described below.

## Related guides

See [project environments](project-environments.html), [image promotion](image-promotions.html), [deployment safety](deployment-safety.html) and [explicit agent updates](agent-updates.html).


## 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](customer-workflows.html#restore). 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](customer-workflows.html#restore).

For configuration export, metrics and backup download/restore, see
[application operations](customer-workflows.html).