Skip to Content

Add a database and connect an app

Create a managed PostgreSQL or Valkey and give an app short-lived credentials for it.

Goal: a PostgreSQL database (or a Valkey cache) in your project, and an app that reaches it through a DB_URL variable, without a password stored anywhere.

Before you start

  • A project on a running cluster.
  • The app that will use the database, or a plan for it. To deploy a template that needs a database (for example an analytics app), you do not need this guide: its Dependencies tab creates the database for you. See template dependencies.

Create the database

On the project canvas, search the template list for PostgreSQL (or Valkey) and select it. The Deploy PostgreSQL dialog opens.

On General, enter a Name such as db and pick the Version (PostgreSQL 18 is the default). Total Instances sets how many copies run: 2 or more keeps a standby ready if the primary fails.

On Storage, set the Size of each instance's disk.

Select Create & Deploy.

A Valkey app starts as Standalone. Its Settings tab switches it to Replicated or Cluster later.

Share access with a definition

Credentials come from a definition: a named set of permissions that other apps can ask for.

Open the database app and go to its Databases tab (Access for Valkey).

Under Shareable Definitions, select New.

Enter a Definition Name, such as orders-readwrite, and set the Permissions.

Pick the Injection Format: a single connection string, separate HOST, PORT and so on, or both. Set the Default Env Prefix, for example DB.

Select Create definition.

Connect the app

Open the app that needs the database and go to its Env Vars tab.

Select Add from Secrets and find the definition under Dynamic Credentials.

Pick it. The tab adds DB_URL={{dynamic:orders-readwrite}}.

Deploy the app.

Each pod gets its own short-lived login when it starts. A-Line.cloud renews it while the pod runs, and the password never shows up in the app's settings.

Verify

  • The app's Logs show it connected, or no connection errors.
  • The database's Databases tab lists the running credentials of the definition.
  • The database's Overview shows the Service endpoints. For PostgreSQL, apps should use <name>-pooler-rw (the pooled primary, through PgBouncer) on port 5432.

Troubleshooting

  • The definition is not listed in Add from Secrets: the app and the database must run on the same cluster. Search by the definition's name.
  • "too many connections": every pod holds its own connections, and a small PostgreSQL allows 100 by default. Use fewer replicas, connect through the pooler, or give the database more resources.
  • Permission denied on a table: the definition's Permissions do not cover it. Change the definition's permissions.

Back it up

Database apps get a Backups tab. Add a policy there; see Volumes and backups.

In IaC

A database is an app file with a template source. Roles go in its databases block (roles for Valkey), and the consuming app asks for a lease in its env. See Databases and leases.

Next steps

On this page