How to Connect Logto to a PostgreSQL Database: Configuration Guide

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.

Setting the DB_URL Environment Variable

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

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:

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

Shell export – Export the variable before launching Logto:

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

Docker run – Pass the variable when starting the container:

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 (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:

pnpm cli db seed

This command, referenced in AGENTS.md and .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:

pnpm cli connector link -p .

Docker Compose Quick Start

The repository provides a ready-to-run 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:

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):

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 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 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. The configuration loader in 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}