How to Connect Logto to a SQLite Database

Logto does not support SQLite databases and requires PostgreSQL for all data storage, meaning you cannot configure a SQLite connection string in the DB_URL environment variable.

Logto is an open-source identity and access management platform architecturally bound to PostgreSQL. While lightweight databases like SQLite are attractive for development or embedded deployments, the codebase explicitly expects a PostgreSQL DSN and will fail to initialize with any other database type.

Why Logto Requires PostgreSQL

Logto’s core data layer is built around the PostgreSQL database engine. According to the source code in packages/shared/src/node/env/GlobalValues.ts, the application reads the DB_URL environment variable and validates that it points to a PostgreSQL DSN. The underlying database driver is hardcoded to use pg, the official Node.js PostgreSQL client, which cannot communicate with SQLite file-based databases.

The database connection flows through several critical components:

• packages/shared/src/node/env/GlobalValues.ts – Reads and validates DB_URL
• packages/cli/src/commands/install/utils.ts – Generates .env files containing only PostgreSQL connection strings
• docker-compose.yml – Defines the official PostgreSQL service configuration

The Technical Blockers for SQLite Support

Connecting Logto to a SQLite database would require extensive architectural changes beyond simply changing a connection string. The codebase contains PostgreSQL-specific implementations at multiple layers.

Database Driver Dependencies

The pg driver is deeply integrated into the query execution layer. Replacing it with a SQLite-compatible driver like sqlite3 would require rewriting the entire data access layer, as the connection pooling, query parameter binding, and result set handling differ significantly between PostgreSQL and SQLite clients.

Schema Migrations and SQL Dialects

All database schema definitions and migrations reside in packages/schemas/alterations/ and are written exclusively for PostgreSQL syntax. These include PostgreSQL-specific data types, JSON operators, and DDL statements that have no SQLite equivalents. Rewriting these migrations would require maintaining a completely separate schema versioning system.

Environment Configuration Constraints

The CLI installation utilities in packages/cli/src/commands/install/utils.ts automatically generate .env files with PostgreSQL connection strings. There is no configuration pathway to specify SQLite file paths, and the environment validation logic rejects non-PostgreSQL DSNs during startup.

Attempting to Use SQLite (And Why It Fails)

If you attempt to bypass PostgreSQL and point Logto to a SQLite database, the application will crash during initialization.

First, set up the environment variable with a SQLite path:

# ❌ This configuration will fail

export DB_URL="sqlite:///path/to/logto.db"
pnpm start:dev

Logto will produce runtime errors because the pg driver cannot parse sqlite:// protocols, and the migration runner in packages/schemas will fail to execute PostgreSQL-specific SQL against a SQLite file. The initialization sequence expects to connect to a running PostgreSQL server to perform version checks and migration table creation.

Recommended PostgreSQL Setups for Development

For lightweight development environments where you want minimal overhead, use a containerized PostgreSQL instance rather than attempting SQLite.

Use the official Docker Compose configuration:

# Start PostgreSQL via Docker

docker-compose up -d postgres

# Configure Logto with the local PostgreSQL DSN

export DB_URL="postgres://postgres:p0stgr3s@localhost:5432/logto"
pnpm start:dev

This approach satisfies Logto’s database requirements while keeping the setup ephemeral and development-friendly.

Summary

• Logto requires PostgreSQL specified via the DB_URL environment variable, as enforced in packages/shared/src/node/env/GlobalValues.ts.
• SQLite is not supported; attempting to use a sqlite:// connection string results in runtime errors and migration failures.
• The codebase uses the pg driver exclusively, with no abstraction layer for other database engines.
• Schema migrations in packages/schemas/alterations/ contain PostgreSQL-specific SQL that cannot execute on SQLite.
• Use Docker to run PostgreSQL locally for development instead of attempting SQLite workarounds.

Frequently Asked Questions

Can I use SQLite with Logto for local development?

No. Logto’s architecture is specifically built for PostgreSQL, and the codebase contains no SQLite-compatible drivers or SQL dialects. Even for local development, you must connect to a PostgreSQL instance, which can be easily run via Docker using the provided docker-compose.yml file.

What happens if I set DB_URL to a SQLite connection string?

Logto will fail to start. The application expects a PostgreSQL DSN in DB_URL and uses the pg driver to establish connections. When it encounters a sqlite:// protocol or file path, the driver initialization fails, causing the server to exit with database connection errors before completing migrations.

Where are the database migration scripts located?

All migration scripts are stored in packages/schemas/alterations/ and are written specifically for PostgreSQL. These scripts handle schema changes, data transformations, and version tracking using PostgreSQL-specific features and syntax that are incompatible with SQLite’s capabilities.

Does Logto support other databases like MySQL or MongoDB?

No. The current implementation only supports PostgreSQL. The data layer in packages/shared/src/node/env/GlobalValues.ts validates PostgreSQL connection strings, and the query layer depends on PostgreSQL-specific features throughout the schema definitions and application code.

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