Attaching a Database

Attaching a Database to a Web Application or Background Worker injects a connection-string environment variable into the app — DATABASE_URL by default, or any name you choose. The platform wires the database credentials directly into the variable, so you never copy a password or store the connection string yourself.

Attachments work for all four engines: PostgreSQL, Redis, MongoDB, and MariaDB. If you haven’t created a Database yet, start with Databases.

The same card also attaches Object Storage buckets, which inject a set of S3 credential variables instead of a single connection string — see Object Storage Buckets.

How attachments work

• The Database and the app must live in the same Environment. The dashboard only offers databases from the app’s environment as attach candidates.

• Each attachment injects one environment variable holding a ready-to-use connection string for that engine:

  Engine	Connection string
  PostgreSQL	postgresql://…
  Redis	redis://default:<password>@<host>:6379
  MongoDB	mongodb://… (the standard connection string)
  MariaDB	mysql://<user>:<password>@<host>:<port>/<database>

• The variable is managed by the platform. It does not appear in the app’s editable environment-variable list, and detaching removes it.

• Attaching and detaching require the database-management permission on the project. Organization Owners and Admins have it; other members get it through group permissions.

Attach in the dashboard

1. Open your app — for example Organization acme → Project shop → Environment production → the web application.
2. Go to the Config tab. Below the environment variables you’ll find the Attached Resources card.
3. Pick a database from the dropdown — say shop-db (PostgreSQL).
4. Optionally type a variable name. Leave it blank to use DATABASE_URL.
5. Click Attach.

The attachment appears in the list with the variable name next to the database. The platform updates the app’s deployment configuration so its instances receive the variable.

Choosing the variable name

The default DATABASE_URL is fine when an app uses a single database. When you attach more than one — a PostgreSQL database and a Redis cache, for instance — give each attachment a distinct name so your code can tell them apart, such as DATABASE_URL and REDIS_URL. Names are uppercased automatically as you type.

Attach from the CLI

With CLI 0.9.0 or later, select the app and database explicitly:

paas apps attach web shop-db -o acme -p shop -e production
paas apps attach worker shop-db --env-var REPORTING_DB_URL -o acme -p shop -e production
paas apps attachments web -o acme -p shop -e production

--env-var defaults to DATABASE_URL. The attachment list shows the ID used for detaching, without displaying credentials. To connect Redis alongside the primary database, attach it under --env-var REDIS_URL. See app attachment commands.

Older CLIs support paas attach shop-db -a web and --as REPORTING_DB_URL; these aliases remain available. Their detach command takes a resource name and optional --as, whereas paas apps detach takes an attachment ID.

Verify from your app

After the app rolls out, check that it received the variable without printing the connection string:

paas run -o acme -p shop -e production -a web -- sh -c 'if [ -n "$DATABASE_URL" ]; then echo "DATABASE_URL is set"; else echo "DATABASE_URL is missing"; exit 1; fi'

Look for the explicit confirmation; the one-off command guide explains remote exit-status limitations. Presence alone does not prove connectivity. Exercise a database-backed app endpoint, or run your framework’s connection check and report only success or a redacted error. See network access if the connection times out.

Detaching

In Attached Resources, click Detach, or find the attachment ID and remove it:

paas apps attachments web -o acme -p shop -e production
paas apps detach web ATTACHMENT_ID -o acme -p shop -e production

Replace ATTACHMENT_ID with the ID from the list. Detaching removes that injected variable and rolls out the app; it does not delete the database. Update code that depends on the connection first. Deleting a database is a separate, destructive operation; review backup and deletion behavior.

Next steps

• Databases — create and manage database resources
• Database Backups — what’s backed up for PostgreSQL and MariaDB
• Environment Variables — app configuration you manage yourself
• Access Control — who can manage databases