Application database bindings

An application binding gives one Container, Deployment, or eligible workload service private access to one managed database. Gateway creates a distinct engine user or role for the binding and grants only the database permissions that binding requires. The engine identity belongs to the binding, not to a transient workload process.

Use a binding when an application needs database access without sharing an owner credential or publishing the database to a broader network. The database owner approves the permissions, the application owner chooses how connection values enter the workload, and the platform owner keeps the Database and Docker Nodes available. Success means the application can perform its required work, cannot perform ungranted work, and keeps access after a controlled workload recreation without creating duplicate identities.

The main risk is credential or permission reuse. Create a separate binding for each workload boundary, keep the database private by default, and retire the binding when the workload no longer needs it.

Operator details: transport and ownership model

For every binding, the target Docker daemon owns a TCP listener on a dedicated bridge network. Gateway reconciles that listener as part of the binding’s desired state. The private endpoint therefore stays associated with the workload environment rather than being implemented by a separate per-binding process.

The daemon listener and the binding’s engine identity are separate but coordinated records. Each binding has its own database principal, so one workload’s credential rotation, deletion, or permission change does not silently change another workload’s access. Recreating a bound workload preserves the binding relationship and its distinct engine identity; Gateway reconciles the listener and injects the current connection settings again.

The nginx/workload Secure Link connector is a separate real component. It serves its ingress and relay purpose and is not the transport implementation for managed database bindings. Troubleshoot binding listener state and database readiness independently from Secure Link health unless the reported operation explicitly identifies an ingress/relay issue.

Create a binding

Before creating a binding, confirm that the managed database is Ready, the target Docker node is online, the workload is eligible, and you have access to both resources. Review the intended database or role permissions and make sure the workload can consume the delivered connection settings without placing them in source control.

1. Select the managed database and the target workload.
2. Choose the intended least-privilege database access.
3. Create the binding and wait for Gateway to provision its engine identity and reconcile the daemon-owned listener.
4. Apply or recreate the workload only when its configuration change requires it.
5. Verify a real application query, then inspect binding telemetry and workload and database logs.

Use private bindings for workload access even when direct TCP publication is enabled for an external client. Publication is opt-in and does not replace binding isolation.

Bindings can target an eligible standalone Container, Deployment, or Compose service. Gateway delivers a connection URI and, where configured, individual host, port, database, user, and password values to the selected workload environment. Treat every delivered value as a secret even though the listener itself is private. Do not copy the URI into Compose source, image layers, screenshots, logs, or Pages runtime configuration.

One database can serve multiple workloads through separate bindings. That is preferable to reusing one shared account: each binding can be audited, rotated, permissioned, and retired independently. Gateway rejects conflicting environment-variable assignments rather than silently replacing an existing application value.

Verify isolation

After creation or workload recreation, verify all of the following:

• the binding reports Ready and its target workload is running;
• the workload received the expected variable names without exposing their values;
• a permitted query succeeds and a deliberately ungranted operation fails;
• binding runtime telemetry shows the expected stream and no sustained admission rejects;
• recreating the workload preserves the same binding relationship and does not create an additional engine role;
• an unrelated workload cannot reach the private listener or reuse the binding identity.

Credential reveal is an exceptional diagnostic action. It requires explicit access and should be followed by normal secret-handling controls; avoid revealing credentials merely to prove that a binding works when an application query and telemetry provide safer evidence.

Reconciliation and failure handling

Desired binding state remains durable through workload recreation, Docker daemon restart, node reconnection, and Relay restart. Reconciliation restores the daemon-owned listener and confirms the engine identity without creating a new identity for every transient runtime. This is how Gateway avoids orphan roles after normal restart and recreation paths.

For a failed binding, diagnose in this order: managed database readiness; target database node; target Docker node; binding desired state; daemon listener state; engine identity and permissions; then application configuration. Inspect the binding operation and telemetry before retrying. Do not delete the engine role, bridge network, or listener manually as a general repair tactic, because that can desynchronize the durable record from the database and daemon.

Delete and recover

Delete the binding through Gateway when the workload no longer needs access. Gateway removes the listener relationship and retires the binding’s engine identity as part of one recorded lifecycle, preventing the normal deletion path from leaving unused identities behind. Delete the binding before deleting the database or the workload whenever possible, then verify that the listener, telemetry, and engine principal cleanup have completed.

If a deletion is interrupted, leave the durable binding record in place and use its operation state for recovery. Manual role deletion is an exceptional recovery procedure because it can make a future reconciliation fail; use it only with an explicit, coordinated recovery plan.

Operator details: upgrade and compatibility

Current bindings use daemon-owned listeners and do not require a per-binding database connector image. During an upgrade from an older release, successful reconciliation can retire legacy connector containers after the new daemon and binding identity are ready. Do not delete legacy artifacts early: allow the recorded migration to prove the replacement path first.

An application-only Gateway restart should not terminate established binding traffic when the Relay and target daemons remain healthy. A Relay update is a data-plane maintenance event and can interrupt streams; clients should use bounded reconnect and retry behavior. A target Docker daemon or Node restart requires listener reconciliation, so verify both the binding state and a real query after reconnect.