Skip to main content

Troubleshooting

Connection Issues​

Cannot connect to ScramDB​

psql: error: connection to server on "localhost" (127.0.0.1), port 5432 failed: Connection refused

Solutions:

  1. Check if the container is running: docker ps | grep scramdb
  2. Check logs: docker logs scramdb
  3. Verify port mapping: docker port scramdb
  4. If port 5432 is in use (e.g., by PostgreSQL), map to a different port: -p 5433:5432

Connection reset​

If connections are getting reset during long-running queries, increase the query timeout:

docker run -d -e SCRAMDB_QUERY_TIMEOUT=600 scramdb/scramdb:latest

Performance Issues​

Queries are slow​

  1. Check query acceleration: If acceleration is disabled, queries will run slower:

    docker run -e SCRAMDB_JIT_ENABLED=true scramdb/scramdb:latest

  2. First query is slow: This is expected - the engine compiles the query plan on first execution. Subsequent executions of the same query shape use optimized code.

  3. Check worker count: Ensure workers match available CPU cores:

    docker run -e SCRAMDB_WORKERS=8 --cpus=8 scramdb/scramdb:latest

  4. Memory: If the buffer pool is too small, pages get evicted and re-read from disk:

    docker run -e SCRAMDB_MEMORY_LIMIT=8G --memory=10g scramdb/scramdb:latest

High memory usage​

ScramDB uses memory primarily for:

  • Buffer pool: Cached Tundra pages (configurable)
  • Hash tables: Built during join operations (proportional to query complexity)
  • Query compilation: Optimization context (~50-100MB shared)

Reduce memory usage by lowering SCRAMDB_MEMORY_LIMIT.

Data Issues​

Data not persisted after container restart​

Mount a volume for persistent storage:

docker run -v scramdb-data:/var/lib/scramdb scramdb/scramdb:latest

WAL recovery on crash​

ScramDB uses ARIES-style WAL for crash recovery. On restart after an unclean shutdown, it automatically replays the WAL to restore consistency. Check logs for:

[INFO] WAL recovery: replaying from LSN 12345
[INFO] WAL recovery complete: 42 records replayed