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 that the container is running: docker ps | grep scramdb
  2. Check the logs: docker logs scramdb
  3. Verify the port mapping: docker port scramdb
  4. If port 5432 is already in use (for example by PostgreSQL), map ScramDB to a different port: -p 5433:5432
  5. Check whether the process is actually up without needing a PostgreSQL client: curl http://127.0.0.1:9090/health returns ok once the server is accepting connections. This also works as a Kubernetes httpGet liveness or readiness probe.

Connection reset during a long query​

If a client drops long-running queries, the timeout is almost always on the client side, not in ScramDB. Raise your driver's statement or socket timeout (for example statement_timeout in psql, or the equivalent option in your connection library) and retry.

Startup Issues​

ScramDB won't start: cluster mode requires an Enterprise license​

cluster mode requires an Enterprise license (multi-node clustering is an Enterprise-only
capability); this node's license resolved to Community - ...

Multi-node clustering is an Enterprise (or Trial) capability. A node checks its license before it binds any port whenever its config has a [cluster] section, and a Community node refuses to start rather than boot in a degraded or single-node mode. Fix it one of two ways:

  • Set SCRAMDB_LICENSE_KEY (or license_key under [general]) to a valid Enterprise or Trial key on every node in the cluster.
  • Remove [cluster] from the config entirely if you only need a single node; single-node ScramDB has no license gate.

See Clustering.

ScramDB won't start: unknown configuration key​

An unrecognized top-level key in the TOML file is a hard parse error, not a silently ignored typo. ScramDB stops at startup rather than run with a config it can't fully account for. The startup log names the offending key; the usual cause is a typo, or a key that has moved under a section (for example a flat key that now belongs under [general]). See Configuration for the current section layout.

Docker cluster mode fails to start: "NODE_NAME set but ADVERTISE_ADDR unset" (or similar)​

The container's entrypoint script looks at NODE_NAME, ADVERTISE_ADDR, and SEEDS together: all three unset starts single-node mode, all three set starts cluster mode, and any partial combination is a hard failure with a message naming exactly which variables are set and which are missing. It is not a fallback to single-node. Set all three, or none.

Data Issues​

Writes fail with SQLSTATE 25006 ("read_only_sql_transaction")​

ERROR:  data size exceeds Community edition limit (64 GiB); node is read-only; reads and export remain available
HINT:   Reads and COPY TO/export remain available; free space or upgrade to Enterprise to restore write access.

The Community edition caps stored data at 64 GiB. A background check samples total data size roughly once a second; the moment stored data exceeds the cap, the node flips read-only for INSERT, UPDATE, DELETE, MERGE, TRUNCATE, and COPY FROM. SELECT, other reads, and COPY TO / export are never affected, so the node stays fully readable while over the cap.

This is the same SQLSTATE (25006) PostgreSQL itself returns from a hot-standby replica that rejects a write, so most drivers and pools already have retry or error-classification logic that recognizes it.

Recovery is automatic: if stored data drops back under the cap (drop data, TRUNCATE, let retention or compaction reclaim space), the next sample flips the node back to writable, no restart or manual unlock needed. To stay above the cap and keep writing, an Enterprise or Trial license removes the ceiling entirely (SCRAMDB_LICENSE_KEY or license_key; see Configuration).

Data not persisted after a container restart​

Mount a volume so your data survives the container:

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

Recovery after a crash​

ScramDB uses a write-ahead log for crash recovery. After an unclean shutdown it automatically replays the log on startup to restore a consistent state, then continues serving. If recovery cannot complete, ScramDB stops with the reason in its logs rather than starting in a partial state.

To recover to a specific point in time instead of just the latest consistent state, use the scramdb restore CLI. The shipped Docker image archives its write-ahead log by default ([storage.wal.archive] enabled = true), so a backup taken with scramdb backup plus the archived WAL is enough to restore to any point after the backup. See Backup and restore (PITR).

Performance Issues​

Queries are slow​

  1. The first run of a query shape is slower. ScramDB compiles each new query shape to native machine code the first time it runs, then reuses that code. Run the same shape again and it takes the compiled path.

  2. Give queries enough memory. If the buffer pool is too small, hot pages get evicted and re-read from disk. Raise buffer_pool_size_bytes (or buffer_pool_percent) in the [storage] section of your config file, and the per-operator budgets in [storage.memory]. See Configuration.

  3. Check the worker count. By default ScramDB uses every available core. If you have capped it, make sure workers in the [execution] section matches the cores you want queries to use.

  4. Look at the plan. Run EXPLAIN ANALYZE <query> to see where the time actually goes, then add an index on the columns you filter or join on.

High memory usage​

ScramDB uses memory mainly for:

  • The buffer pool: cached data pages, sized by buffer_pool_size_bytes or buffer_pool_percent.
  • Query execution: hash tables and sort buffers built while a query runs, bounded by the budgets in [storage.memory].

To use less memory, lower the buffer pool size and the [storage.memory] budgets in your config file. In a container, --memory also bounds these automatically when you use the percent-based keys, since sizing reads the cgroup limit. See Configuration.