deploy.database.bindBind a managed Postgres database (a dedicated app role by default)
mode=app_role creates role app_<slug> and its database (or grants on an existing one); its password is a secret the binding reads at every rollout. mode=master hands the app the master credential. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.
Depending on the resource, the call checks rds:ModifyDBInstance, deploy:DeployApp instead; hold all of them to be sure it is allowed.
Request syntax
PUT /deploy/api/apps/{id}/database
{
"dbInstanceId": "string",
"dbBranchId": "string",
"database": "string",
"mode": "enum",
"envPrefix": "string",
"pooled": "boolean",
"redeploy": "boolean"
}Path parameters
idRequiredstring
Constraints: uuid
Request body
dbInstanceIdRequiredstring
The managed Postgres database (instance) to bind
Constraints: 3-64 chars
dbBranchIdOptionalstring
A branch of the database (ewbr-…) to connect to instead: the branch's master user and port, no pooler
Constraints: /^ewbr-[0-9a-f]{12}$/
databaseOptionalstring
Database inside the instance (app_role mode creates it if missing). Default: the app’s slug as a Postgres name; in master mode or for a branch, the instance’s own database
Constraints: /^[a-z_][a-z0-9_]{0,62}$/
modeOptionalenum
app_role (default): a role of the app’s own, its password kept in Secrets; master: the instance’s master credential
One of:
app_role,masterenvPrefixOptionalstring
Put in front of every generated variable name (e.g. CACHE_ gives CACHE_REDIS_URL), so one app can hold several bindings of a kind; default empty
Constraints: max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/
pooledOptionalboolean
Connect through the PgBouncer pooler (default true) or straight to Postgres on 5432; ignored for a branch
redeployOptionalboolean
Also roll the live deployment onto the new configuration; default false
Response
200 with `data`: the binding — id, appId, dbInstanceId, database, dbBranchId, mode, roleName and credentialSecretId (app_role), envPrefix, pooled, status, statusMessage, createdAt and updatedAt. The top-level `redeploy` is null unless redeploy was requested; then { ok: true, deploymentId, generation, reusedDeploymentId } or { ok: false, error }.
A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.
Fields of data
idAlwaysstring
Binding idappIdAlwaysstring
The apporgIdAlwaysstring
OrganizationdbInstanceIdAlwaysstring
The bound database instancedatabaseAlwaysstring
Database inside the instance the app connects todbBranchIdAlwaysstring, may be null
Branch of the database the app connects to instead; null: the database itselfmodeAlwaysone of app_role, master
app_role: a role of the app’s own; master: the master credentialroleNameAlwaysstring, may be null
The app’s role, for app_role; null for mastercredentialSecretIdAlwaysstring, may be null
The Secret holding the role’s password, for app_role; null for masterenvPrefixAlwaysstring
Prefix of the generated variable names; empty for nonepooledAlwaysboolean
Whether it connects through the connection poolerstatusAlwaysone of pending, ready, error
pending, ready or errorstatusMessageAlwaysstring, may be null
What was done, or what failedcreatedAtAlwaysstring
When it was boundupdatedAtAlwaysstring
When it was last changed
Checked against the handlers: every route test validates their answers against this schema.
Errors
- 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
- 401No credentials, or an access key that is unknown, revoked or expired.
- 403The caller's policies do not allow deploy:ManageDatabaseBinding on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
- 404The resource does not exist in your organization.
Examples
The required parameters only, with example values. Replace id and the other placeholders with your own.
dcloud deploy database bind id --db-instance-id examplecurl -X PUT "https://console.platform-development.deutschecloud.app/deploy/api/apps/id/database" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"dbInstanceId":"example"}'Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_database_bind.