> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-e6012f7f.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/setup-lightdash/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 if you use an [enterprise license key](/self-host/customize-deployment/enterprise-license-keys)**. Lightdash uses `pgvector` to store embeddings that power enterprise AI features (AI Analyst, AI agents, and related capabilities). Install it on your Postgres database before starting a licensed Lightdash instance — on managed services like AWS RDS, Google Cloud SQL, and Azure Database for PostgreSQL, enable the `vector` extension in your instance's configuration, then run `CREATE EXTENSION IF NOT EXISTS vector;` in the Lightdash database.

## Migrations

Migrations are ran automatically on starting the Lightdash server or workers. When upgrading Lightdash, migrations will be ran automatically.

If a migration gets stuck — for example after an interrupted deploy:

* **On Lightdash `1.123.0` and later**, an interrupted migration's lock expires on its own and another process takes over automatically. To inspect migration state, or release a lock that is genuinely stuck, run the built-in `migrate` command inside a Lightdash container (`kubectl exec` / `docker compose exec`):

  ```bash theme={null}
  pnpm -F backend migrate-production status
  pnpm -F backend migrate-production unlock --actor "<your identity>"
  ```

  Do **not** edit the `knex_migrations_lock` table manually on these versions — it can release a lock that a live migration legitimately holds. The [upgrade runbook](/self-host/upgrade-runbook#recovery) covers how to read `status`, when `unlock` refuses, and what resumes on its own afterwards.

* **On versions before `1.123.0`**, if migrations fail due to a pg\_lock error, check for a table called `knex_migrations_lock` to manually release the lock.