Database

Comicarr uses SQLite by default, which requires zero configuration and works out of the box. For larger libraries or multi-instance deployments, you can switch to PostgreSQL or MySQL by setting a single connection URL.

Settings

Setting	Type	Default	Description
`DATABASE_URL`	string	—	Database connection URL. When unset, Comicarr falls back to a SQLite database at `DATA_DIR/comicarr.db`.

The DATABASE_URL can be set in the [Database] section of config.ini or as an environment variable. The environment variable takes precedence over the config file value.

Passwords stored in DATABASE_URL inside config.ini are encrypted at rest using Fernet symmetric encryption. Environment variables are not encrypted — secure them through your OS or container runtime instead.

Resolution Order

Comicarr resolves the database connection using this priority:

DATABASE_URL environment variable
DATABASE_URL in the [Database] section of config.ini
Default SQLite database at DATA_DIR/comicarr.db

Database Backends

SQLite is the default backend. No additional packages or services are required. Comicarr automatically applies the following optimizations:

WAL mode for concurrent read/write performance
64 MB page cache to reduce disk I/O
15-second busy timeout to handle lock contention gracefully
Foreign keys enabled for referential integrity

config.ini

[Database]
# No DATABASE_URL needed — Comicarr uses SQLite at DATA_DIR/comicarr.db by default.
# To use a custom path:
DATABASE_URL = sqlite:////config/comicarr.db

SQLite URLs use three slashes for a relative path (sqlite:///comicarr.db) and four slashes for an absolute path (sqlite:////config/comicarr.db).

PostgreSQL is recommended for large libraries or when multiple Comicarr instances share one database.

Driver: psycopg2-binary — included in the Docker image, or install manually:

pip install psycopg2-binary

config.ini

[Database]
DATABASE_URL = postgresql://comicarr:password@localhost:5432/comicarr

Environment Variable

DATABASE_URL=postgresql://comicarr:password@localhost:5432/comicarr

URL Format

postgresql://user:password@host:5432/database

MySQL (and MariaDB) are supported as an alternative external backend.

Driver: mysqlclient — install manually:

pip install mysqlclient

config.ini

[Database]
DATABASE_URL = mysql://comicarr:password@localhost:3306/comicarr

Environment Variable

DATABASE_URL=mysql://comicarr:password@localhost:3306/comicarr

URL Format

mysql://user:password@host:3306/database

Docker Compose with PostgreSQL

A common pattern is to run PostgreSQL as a sidecar service alongside Comicarr:

services:
  comicarr:
    image: ghcr.io/comicarr/comicarr:latest
    environment:
      - DATABASE_URL=postgresql://comicarr:changeme@postgres:5432/comicarr
    volumes:
      - ./config:/config
      - ./comics:/comics
    ports:
      - "8090:8090"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: comicarr
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: comicarr
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U comicarr"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

Migrating Between Backends

There is no automated migration tool between database backends. If you switch from SQLite to PostgreSQL (or vice versa), you will need to export and re-import your data manually, or start with a fresh database and re-add your library.

On this page