> ## Documentation index
> The full klickops handbook index is at https://klickops.io/llms.txt
> The HTML of this page is at https://klickops.io/en/docs/databases
> Language: en

# Databases

A managed PostgreSQL or Valkey instance that lives inside your project, backed up on a schedule, and reachable from your apps by name.

## What it is

A database in klickops is a managed instance you create from the Databases page of a project. klickops runs it, patches it, watches it, and takes the backups. You get a connection string and a console. Nothing about it lives outside the project, so deleting the project deletes the database with it.

Two engines are available today. **PostgreSQL** is the full-featured one, with replicas, connection pooling, extensions, and point-in-time restore. **Valkey** is a single in-memory instance for caches, sessions, and queues, with no replication and no backups by design.

## When you'd use it

- Your app needs a database and you would rather not operate one.
- You want connection details injected into the app instead of pasted into a secret by hand.
- You are moving off a hosted provider and want the data where your project is.

> [!Not this]
> If you need a database that outlives the project, or one that several projects share, create it in its own project and reach it with a firewall rule. A database cannot be moved between projects after it is created.

## Create a database

1. Open your project, go to **Databases**, then **New database**.
2. Pick the engine. Choosing PostgreSQL fills in the defaults below; choosing Valkey switches to the cache defaults and drops the backup step.
3. Set the size. Storage is a slider with your plan's ceiling drawn on it. CPU and memory follow the size you pick and can change later without data loss.
4. Decide how many instances. **PostgreSQL starts at three**, one primary and two replicas, which is what lets it survive losing a node. Drop it to one for a development database, and the cost drops with it.
5. Choose a backup destination. Daily backups are on by default for PostgreSQL and the wizard will not finish without a bucket to write them to.
6. Create. The instance is usually ready in under two minutes, and the page shows the phase while it comes up.

![The Databases list of a project, with the available engines below it.](/handbook/databases-list.webp)

## Connect an app to it

Open the database, go to **Connect**, and choose the app. klickops writes the host, port, database name, user, and password into the app as a binding, so rotating the password later updates the app without you editing anything.

The credentials sit on that tab if you need them locally. The password stays masked until you reveal it, and the API never returns it in a list response.

```bash
# a psql session through klickops, no local postgres client needed
klops db query orders-db --project shop -c "select count(*) from orders"
```

## Operating it day to day

Every database opens on **Overview**, and the tab strip is the whole surface. Valkey shows a shorter one: it has a command console instead of a SQL editor, and no backups tab.

| Tab | What lives there |
| --- | --- |
| Connect | Credentials, app bindings, connection pooler |
| Query | Run SQL against the instance. Valkey shows a command console |
| Browse | Tables and rows, read-only |
| Data and backups | Schedule, restore points, dump import and export |
| Storage | Grow the volume. Storage grows and never shrinks |
| Updates | Minor patches and major version upgrades |
| Metrics | Connections, cache hit rate, disk, CPU |
| Logs | Instance logs, live and historical |
| Advanced | Extensions, server parameters, TLS, client access rules |

## Settings reference

| Setting | Default | What it does |
| --- | --- | --- |
| Version | PostgreSQL 16, Valkey 8.1 | Pre-picked so the name is the only field you must fill in. Minor patches land in the maintenance window; a major version change is an explicit upgrade with a plan you approve first. |
| Storage | 10 GB | Volume size. Grows online, never shrinks. Your plan's ceiling is drawn on the slider. |
| Instances | 3 for PostgreSQL, 1 for Valkey | Three nodes is the default: one primary, two replicas, automatic failover. A single instance costs a third as much and cannot survive a node failure. |
| Connection pooler | off | Puts PgBouncer in front of the instance. Turn it on when you have more clients than connections. |
| Backups | on, daily, 7 days | PostgreSQL only, and it needs a destination bucket before it can run. Write-ahead logs are kept too, so you can restore to any second inside the window. Valkey has no backups at all. |
| Extensions | none | PostgreSQL extensions such as `postgis` or `pgvector`. Installing one restarts the instance. |
| Parameters | engine defaults | Server parameters. Most changes restart the instance, and the save banner says so before you commit. |
| TLS | required | Whether clients must connect over TLS. Leave it on. |
| Update policy | automatic | Whether klickops applies minor patches for you, or waits for you to click. |

## Limits and gotchas

- **Storage only grows.** There is no shrink. Size for a year, not for a decade.
- **Valkey has no backups.** It is a cache. Treat everything in it as disposable.
- **PostgreSQL backups need somewhere to go.** They are on by default, but nothing is written until you point them at a bucket.
- **Major upgrades are one way.** The plan shows what changes and takes a backup first, but there is no downgrade afterwards.
- **The instance is not reachable from the internet.** Apps in the same project reach it by name; anything else needs a firewall rule.

> [!Careful]
> Deleting a database deletes its volume and its backups. The dialog asks you to type the database name because there is nothing to undo afterwards. Export a dump first if you are unsure.

## Related

- [Apps](/docs/apps) is what usually connects to this, from its Configuration tab.
- [Domains](/docs/domains) if you are exposing something that talks to it.