> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-refactor-full-audit-reorg.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Lightdash to use an external database

<Note>
  🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to connect your data warehouse, go to the [Connect a project](/get-started/quickstart/connect-project) guide.
</Note>

<Info>
  Lightdash requires a **PostgreSQL** database (version 12 or greater).
</Info>

In production, we recommend using a managed database service (depending on your cloud provider). This ensures that your database is highly available and secure. You can also use a self-hosted database, but you will need to manage the database yourself.

The following configuration shows an example of how to configure Lightdash to use an external database. You can use this as a starting point for your own configuration.

## Configuration options for external database

```yaml theme={null}
# values.yaml

# Disable the internal database
postgresql:
  enabled: false

# Configure Lightdash to use an external database
externalDatabase:
  host: lightdash-db.mycompany.com
  port: 5432
  user: lightdash
  password: lightdash
  database: lightdash
```

Optionally you can pass any of the [PostgreSQL Environment Variables](https://www.postgresql.org/docs/current/libpq-envars.html) to the `configMap`

## Required pg extensions for external database

Lightdash requires the following extensions to be installed on the database:

* `uuid-ossp` — used for generating unique IDs
* `pgvector` — **required for Enterprise AI features** (AI Analyst embeddings and verified answers)

## Running Postgres in production

Beyond the connection settings above, this is what to run on the database side to match Lightdash Cloud:

* **Managed Postgres** (Cloud SQL / RDS / Azure Database) — version **14+** recommended (12 is the documented minimum).
* **High availability:** a regional / multi-AZ primary, with a **cross-region replica for disaster recovery**.
* **Backups:** daily automated backups with **point-in-time recovery enabled**, ≥ 7 days of transaction logs, and 7–31 retained backups.
* **SSD storage** with auto-resize.
* **Sizing:** 2 vCPU / 8 GB RAM is a solid single-org baseline; 4 vCPU / 16 GB+ for large orgs or heavy scheduler usage.
* **Connection budget:** every backend and worker pod opens its own pool. Set `PGMAXCONNECTIONS: "50"` and `PGMINCONNECTIONS: "0"` in `configMap`, then make sure Postgres `max_connections` covers `pods × PGMAXCONNECTIONS` with headroom.
* **Query insights / slow-query logging** enabled on the database side.
* **TLS to the database** via the chart's `ssl` block, which injects `PGSSLMODE=verify-full` and `NODE_EXTRA_CA_CERTS`:

```yaml theme={null}
ssl:
  enabled: true
  configMapName: lightdash-db-ca   # your CA cert
  certFileName: ca.pem
```

## Migrations

Migrations run automatically when the Lightdash server or workers start, including on upgrade. If a migration fails with a `pg_lock` error, the lock lives in the `knex_migrations_lock` table — release it there before retrying. For multi-replica deployments, enable the migration job so replicas don't race; see [Upgrading Lightdash](/self-host/upgrading#database-migrations).