# How to Connect Logto to a PostgreSQL Database: Configuration Guide

> Connect Logto to PostgreSQL easily. Learn how to configure Logto with a PostgreSQL database using the DB_URL environment variable and seed the database schema for seamless integration.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Logto connects to PostgreSQL via the `DB_URL` environment variable using the standard PostgreSQL DSN format, then initializes the schema with `pnpm cli db seed` before starting the service.**

Logto stores all tenant data in a PostgreSQL database and requires a valid connection string at startup. According to the logto-io/logto source code, the core service reads the `DB_URL` variable from the environment to build a connection pool using the Slonik PostgreSQL client, as implemented in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts).

## Setting the DB_URL Environment Variable

Logto expects a PostgreSQL connection URL in the standard DSN format:

```text
postgresql://<username>:<password>@<host>:<port>/<database>

```

You can provide this value through one of three methods:

**Environment file** – Create a `.env` file at the repository root:

```env
DB_URL=postgresql://postgres:my-secret@localhost:5432/logto
TRUST_PROXY_HEADER=1

```

**Shell export** – Export the variable before launching Logto:

```bash
export DB_URL=postgresql://postgres:my-secret@127.0.0.1:5432/logto

```

**Docker run** – Pass the variable when starting the container:

```bash
docker run -e DB_URL=postgresql://postgres:pass@host:5432/logto svhd/logto:latest

```

The `databaseUrl` getter in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) (lines 66-68) parses this value and exposes it to the core service for pool creation.

## Seeding the Database Schema

After configuring `DB_URL`, you must initialize the database tables before Logto can start.

Run the CLI seed command:

```bash
pnpm cli db seed

```

This command, referenced in [`AGENTS.md`](https://github.com/logto-io/logto/blob/main/AGENTS.md) and [`.github/CONTRIBUTING.md`](https://github.com/logto-io/logto/blob/main/.github/CONTRIBUTING.md), creates the required tables and inserts initial tenant data. Without this step, Logto will fail to start because it cannot locate the expected schema.

For local development, you can optionally link connectors after seeding:

```bash
pnpm cli connector link -p .

```

## Docker Compose Quick Start

The repository provides a ready-to-run [`docker-compose.yml`](https://github.com/logto-io/logto/blob/main/docker-compose.yml) that demonstrates the complete PostgreSQL connection pattern. It automatically injects `DB_URL` and runs the seed command via the container entrypoint.

Download and launch the stack:

```bash
curl -fsSL https://raw.githubusercontent.com/logto-io/logto/HEAD/docker-compose.yml | \
docker compose -p logto -f - up

```

The compose file defines the following connection string (see lines 13-15):

```yaml
environment:
  - DB_URL=postgres://postgres:p0stgr3s@postgres:5432/logto

```

The entrypoint executes `npm run cli db seed -- --swe` before starting the application, ensuring the database is ready before accepting traffic.

## Connection Internals and Validation

Logto validates the `DB_URL` format at startup through the `GlobalValues` class. The implementation requires the protocol to be `postgresql://` or `postgres://`, and uses the parsed components to configure the Slonik connection pool.

If `DB_URL` is missing or malformed, the application throws immediately during the environment initialization phase, preventing runtime connection failures.

For production deployments, ensure the PostgreSQL user has CREATE privileges on the target database so that `pnpm cli db seed` can execute DDL statements.

## Summary

- Logto requires the `DB_URL` environment variable pointing to a PostgreSQL instance in standard DSN format.
- The connection string is parsed in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) via the `databaseUrl` getter.
- You must run `pnpm cli db seed` after setting `DB_URL` to create the necessary tables and seed initial data.
- Docker Compose users can launch the full stack with the provided `curl` command, which automatically configures the database connection and runs the seed command.
- Logto uses the Slonik PostgreSQL client to manage connection pooling once the URL is validated.

## Frequently Asked Questions

### What PostgreSQL versions are compatible with Logto?

Logto requires PostgreSQL 14 or later. The [`docker-compose.yml`](https://github.com/logto-io/logto/blob/main/docker-compose.yml) in the repository specifies `postgres:17-alpine` as the default image, but any version from 14 upward supports the required JSONB and UUID features used by the schema.

### Can I use a PostgreSQL connection pooler like PgBouncer?

Yes, you can point `DB_URL` to a pooler endpoint, but ensure the pooler operates in transaction mode or session mode compatible with Slonik's connection requirements. Logto requires persistent connections for certain tenant-scoped queries, so session pooling is recommended over transaction pooling for administrative operations.

### Where should I place the .env file for local development?

Place the `.env` file at the repository root, adjacent to [`package.json`](https://github.com/logto-io/logto/blob/main/package.json). The configuration loader in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) reads environment variables from the Node.js process, which typically inherits values from a `.env` file if your process manager or Docker setup loads it. The [`.github/CONTRIBUTING.md`](https://github.com/logto-io/logto/blob/main/.github/CONTRIBUTING.md) (lines 84-88) documents this pattern for contributors.

### Why does Logto fail to start after setting DB_URL?

If Logto exits immediately after setting the connection string, the database likely lacks the required schema. Confirm you executed `pnpm cli db seed` to create tables. Additionally, verify the PostgreSQL user has CREATE, INSERT, and SELECT permissions on the target database, and that the hostname in `DB_URL` is reachable from the Logto container or host.