Database

Comicarr uses SQLite by default, which requires zero configuration and works out of the box. For larger libraries, you can switch to PostgreSQL or MySQL by setting a connection URL and installing the matching driver package.

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

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

On Docker, DATA_DIR is /config/comicarr, so the default DB is /config/comicarr/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/comicarr.db

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

PostgreSQL is supported for external backends.

Driver: psycopg2-binary via the optional postgres extra — not bundled in the default Docker image.

Manual install:

uv sync --extra postgres
# or
pip install "comicarr[postgres]"
# or
pip install psycopg2-binary

Docker users must install the driver into the image (custom Dockerfile/uv sync --extra postgres) or run a custom build. The published ghcr.io/frankieramirez/comicarr image runs uv sync --no-dev without database extras.

config.ini

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

Environment Variable

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

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

Driver: mysqlclient (mysql extra) or pure-Python PyMySQL (mysql-pure extra). Neither is in the default Docker image.

uv sync --extra mysql
# or
pip install mysqlclient

config.ini

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

Docker Compose with PostgreSQL

Example pattern (you must also provide the Postgres driver in the Comicarr image):

services:
  comicarr:
    image: ghcr.io/frankieramirez/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

Comicarr includes a CLI migrator for moving data between database URLs:

python3 Comicarr.py migrate \
  --from sqlite:////path/to/comicarr.db \
  --to postgresql://comicarr:password@localhost:5432/comicarr

Validate first with the tool’s validation options if available in your version’s --help. Always back up both databases before migrating.

Mylar3 library migration

Importing from Mylar3 is separate from backend migration. Use the Mylar3 migration guide (first-run wizard / REST migration endpoints).

On this page