Storage

required

The storage option is used to configure how and where data is stored.

LightHouse uses SQL databases for data storage. SQLite, MySQL, and PostgreSQL are supported.

driver

enum sqlite optional LH_STORAGE_DRIVER

The driver option specifies which database driver to use.

Supported values:

• sqlite - SQLite database (default, file-based)
• mysql - MySQL database
• postgres - PostgreSQL database

config.yaml (SQLite)

storage:
    driver: sqlite
    data_dir: /path/to/data

config.yaml (MySQL)

storage:
    driver: mysql
    dsn: "user:pass@tcp(127.0.0.1:3306)/lighthouse?charset=utf8mb4&parseTime=True&loc=Local"

config.yaml (PostgreSQL)

storage:
    driver: postgres
    dsn: "host=localhost user=postgres password=postgres dbname=lighthouse port=5432 sslmode=disable TimeZone=UTC"

data_dir

directory path required for SQLite LH_STORAGE_DATA_DIR

The data_dir option sets the directory where the SQLite database file (lighthouse.db) will be stored.

This option is only required when using the sqlite driver.

config.yaml

storage:
    driver: sqlite
    data_dir: /var/lib/lighthouse

dsn

string required for MySQL and PostgreSQL LH_STORAGE_DSN

The dsn option specifies the Data Source Name (connection string) for the database.

This option is required when using MySQL or PostgreSQL drivers.

MySQL DSN Format

user:password@tcp(host:port)/dbname?charset=utf8mb4&parseTime=True&loc=Local

config.yaml

storage:
    driver: mysql
    dsn: "lighthouse:secret@tcp(127.0.0.1:3306)/lighthouse?charset=utf8mb4&parseTime=True&loc=Local"

PostgreSQL DSN Format

host=hostname user=username password=password dbname=database port=5432 sslmode=disable TimeZone=UTC

config.yaml

storage:
    driver: postgres
    dsn: "host=localhost user=lighthouse password=secret dbname=lighthouse port=5432 sslmode=disable"

DSN Components (Alternative)

Instead of providing a full dsn string, you can specify individual connection components:

Option	Description	Environment Variable
user	Database username	LH_STORAGE_USER
password	Database password	LH_STORAGE_PASSWORD
host	Database host (default: localhost)	LH_STORAGE_HOST
port	Database port	LH_STORAGE_PORT
db	Database name (default: lighthouse)	LH_STORAGE_DB

Sensitive Data

Use LH_STORAGE_PASSWORD environment variable to avoid storing database passwords in config files.

config.yaml

storage:
    driver: postgres
    user: lighthouse
    password: secret
    host: db.example.com
    port: 5432
    db: lighthouse

debug

boolean false optional LH_STORAGE_DEBUG

The debug option enables debug logging for database operations. This is useful for troubleshooting database issues.

config.yaml

storage:
    driver: sqlite
    data_dir: /var/lib/lighthouse
    debug: true

endpoint_auth

The endpoint_auth section configures JTI (JWT ID) storage for endpoint authentication replay prevention.

config.yaml

storage:
    driver: sqlite
    data_dir: /var/lib/lighthouse
    endpoint_auth:
        jti_backend: cache
        jti_cleanup_interval: 1h

jti_backend

enum "cache" optional LH_STORAGE_ENDPOINT_AUTH_JTI_BACKEND

Specifies the backend used for JWT ID (JTI) replay prevention storage. Valid values:

• "cache" — Uses the configured cache backend (Redis or in-memory). JTIs expire automatically based on their TTL. No cleanup required.
• "db" — Uses the database table jtis_used. Requires periodic cleanup via jti_cleanup_interval.

The JTI storage prevents replay attacks by ensuring each client assertion JWT can only be used once.

jti_cleanup_interval

duration 1h optional LH_STORAGE_ENDPOINT_AUTH_JTI_CLEANUP_INTERVAL

How often to clean up expired JTIs from the database. Only applicable when jti_backend is set to "db".

The cleanup runs as a background goroutine and removes JTIs whose expiration time has passed.