feat: add default PostgreSQL service to Docker Compose, configure Comet to use it, and introduce SQLite concurrency warnings

.env-sample

@@ -32,9 +32,15 @@ PUBLIC_METRICS_API=False # Set to True to allow public access to the metrics API
 # ============================== #
 # Database Configuration         #
 # ============================== #
-DATABASE_TYPE=sqlite # Options: sqlite, postgresql - If you have enabled auto-scaling for FASTAPI_WORKERS and are using PostgreSQL, remember to drastically increase your maximum number of connections to your DB if Comet is experiencing connection issues
-DATABASE_URL=username:password@hostname:port # For PostgreSQL
-DATABASE_PATH=data/comet.db # Only relevant for SQLite
+# ⚠️  WARNING: SQLite has POOR CONCURRENCY support and should ONLY be used for development/testing!
+# SQLite cannot handle multiple concurrent writers well, leading to:
+#   - "database is locked" errors with multiple workers
+#   - Performance issues with background scraper
+#   - Data corruption risks under heavy load
+# For production deployments, use PostgreSQL!
+DATABASE_TYPE=postgresql # Options: sqlite, postgresql - Use postgresql for production, sqlite for development only
+DATABASE_URL=comet:comet@localhost:5432/comet # For PostgreSQL (user:password@host:port/database)
+DATABASE_PATH=data/comet.db # Only relevant for SQLite (development only)
 DATABASE_BATCH_SIZE=20000 # The batch size for the database import and export operations
 DATABASE_READ_REPLICA_URLS='' # Optional JSON array of PostgreSQL read-only URLs, e.g. '["user:pass@replica-1/db", "user:pass@replica-2/db"]'
 DATABASE_STARTUP_CLEANUP_INTERVAL=3600 # Minimum seconds between heavy startup cleanup sweeps (0=every start, -1=disable)

comet/core/logger.py

@@ -188,6 +188,23 @@ def log_startup_info(settings):
         f"Database ({settings.DATABASE_TYPE}): {settings.DATABASE_PATH if settings.DATABASE_TYPE == 'sqlite' else settings.DATABASE_URL} - TTL: metadata={settings.METADATA_CACHE_TTL}s, torrents={settings.TORRENT_CACHE_TTL}s, live_torrents={settings.LIVE_TORRENT_CACHE_TTL}s, debrid={settings.DEBRID_CACHE_TTL}s, metrics={settings.METRICS_CACHE_TTL}s - Debrid Ratio: {settings.DEBRID_CACHE_CHECK_RATIO} - Startup Cleanup Interval: {settings.DATABASE_STARTUP_CLEANUP_INTERVAL}s{replicas}",
     )
 
+    # SQLite concurrency warnings
+    if settings.DATABASE_TYPE == "sqlite":
+        logger.warning(
+            "⚠️  SQLite has poor concurrency support and is NOT recommended for production. "
+            "Consider using PostgreSQL for better performance and reliability."
+        )
+        if settings.FASTAPI_WORKERS != 1:
+            logger.warning(
+                f"⚠️  SQLite with {settings.FASTAPI_WORKERS} workers may cause database locking issues. "
+                "Use PostgreSQL or set FASTAPI_WORKERS=1."
+            )
+        if settings.BACKGROUND_SCRAPER_ENABLED:
+            logger.warning(
+                "⚠️  Background scraper with SQLite may cause database locking issues. "
+                "Use PostgreSQL for reliable background scraping."
+            )
+
     logger.log(
         "COMET",
         f"Anime Mapping: source={settings.ANIME_MAPPING_SOURCE} - refresh_interval={settings.ANIME_MAPPING_REFRESH_INTERVAL}s",

docker-compose.yaml

@@ -1,6 +1,3 @@
-volumes:
-  comet_data:
-
 services:
   comet:
     container_name: comet
@@ -8,7 +5,59 @@ services:
     restart: unless-stopped
     ports:
       - "8000:8000"
+    environment:
+      DATABASE_TYPE: ${DATABASE_TYPE:-postgresql}
+      DATABASE_URL: ${DATABASE_URL:-comet:comet@postgres:5432/comet}
     env_file:
       - .env
     volumes:
       - comet_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8000/health"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    container_name: comet-postgres
+    image: postgres:18-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: comet
+      POSTGRES_PASSWORD: comet
+      POSTGRES_DB: comet
+    command:
+      - "postgres"
+      - "-c"
+      - "shared_buffers=128MB"
+      - "-c"
+      - "effective_cache_size=384MB"
+      - "-c"
+      - "maintenance_work_mem=64MB"
+      - "-c"
+      - "checkpoint_completion_target=0.9"
+      - "-c"
+      - "wal_buffers=8MB"
+      - "-c"
+      - "random_page_cost=1.1"
+      - "-c"
+      - "effective_io_concurrency=200"
+      - "-c"
+      - "work_mem=8MB"
+      - "-c"
+      - "max_connections=100"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U comet -d comet"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  comet_data:
+  postgres_data: