> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# 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](/getting-started/create-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](/concepts/template-dependencies).

## Create the database

<Steps>
<Step>

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

</Step>
<Step>

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.

</Step>
<Step>

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

</Step>
<Step>

Select **Create & Deploy**.

</Step>
</Steps>

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.

<Steps>
<Step>

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

</Step>
<Step>

Under **Shareable Definitions**, select **New**.

</Step>
<Step>

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

</Step>
<Step>

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

</Step>
<Step>

Select **Create definition**.

</Step>
</Steps>

## Connect the app

<Steps>
<Step>

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

</Step>
<Step>

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

</Step>
<Step>

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

</Step>
<Step>

Deploy the app.

</Step>
</Steps>

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](/guides/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](/iac/databases).

## Next steps

- [Store secrets](/guides/secrets) for values that are not database
  credentials.
- [Template dependencies](/concepts/template-dependencies)
- [Volumes and backups](/guides/volumes-and-backups)
