Production hardening checklist
By the end of this page you will have gone through every default that matters before ScramDB takes production traffic, and you'll know exactly which ones are one-line config changes versus real, named limitations to plan around. Each item links to the page that shows the full how-to.
1. Turn off --pg-no-auth
The shipped Docker image and the Kubernetes StatefulSet both run with --pg-no-auth by default: every connection is trusted, no password, no hba_file. Override the container command and drop the flag, or set pg_no_auth = false explicitly in your config TOML (the engine itself already defaults it off; this item is about the shipped image's startup command, not the engine). See Docker: Securing a node for the exact command.
2. Set hba_file to rules that match your network
The built-in default (localhost trusted, everything else password) is a reasonable starting point but is rarely the final posture for a deployment behind a load balancer or on a shared network. Write an explicit rule file scoped to your actual CIDR ranges, and pair hostssl with a password method to require TLS from any address you don't outright trust:
# /etc/scramdb/pg_hba.conf
host all all 10.0.0.0/8 trust
hostssl all all 0.0.0.0/0 password
hostssl all all ::/0 password
See Authentication for the full grammar.
3. Set tls_cert and tls_key
TLS is off by default: both fields default to an empty path, and an empty path disables encryption entirely. Set both under [general] to a real certificate and key. See TLS encryption for generating a certificate and verifying the connection is actually encrypted.
4. Bind pg_address to the interface you actually need
pg_address defaults to 127.0.0.1:5432 (loopback only) in the engine itself; the shipped image overrides it to 0.0.0.0:5432. If your deployment doesn't need to be reachable from every interface, bind to the specific one it does need. A container behind a load balancer or in its own network namespace is the normal exception to this, not a violation of it: 0.0.0.0 inside a container that's otherwise firewalled is a common and reasonable setup, just make sure something is actually doing that firewalling.
5. Keep the metrics endpoint private
The metrics endpoint (metrics_port, default 9090) listens on loopback (127.0.0.1) unless [general] metrics_listen_address says otherwise, so a bare install exposes nothing. A scraper on another machine needs it on every interface (metrics_listen_address = "*", which the shipped image and the Helm chart set); then require a token as well, so reaching the port is not enough to read it:
[general]
metrics_listen_address = "*"
metrics_bearer_token_file = "/etc/scramdb/metrics/token" # chmod 600; Prometheus sends it as a bearer token
The server refuses to start when the token file is readable by every user. Every request, /health included, then needs Authorization: Bearer <token>; anything else gets 401. Set metrics_port = 0 to turn the endpoint off entirely.
6. Firewall the cluster transport and the MCP port
A cluster node listens on three more ports, 7190, 7191 and 7192, for traffic between nodes. They bind every interface by default (cluster_listen = "0.0.0.0:7190"). Allow them from the cluster's own nodes only, and turn on mutual TLS between nodes (tls_cert, tls_key and tls_ca under [cluster]), which covers all three; see TLS between cluster nodes.
Port 9191, the Semantic AI MCP server, answers only authenticated requests once it is reachable beyond the machine. MCP_AUTH=basic maps each request's HTTP Basic credentials to a database role, and MCP_AUTH=bearer takes an agent token; the published image sets basic. Bound beyond loopback with neither set, it answers every request 401. Keep the port on a network you control, or turn the server off with [udf.daemon] enabled = false. Ports lists every port and the firewall rules between machines.
7. Least privilege for application roles
Don't connect application traffic as the bootstrap superuser (scramdb). Create a role scoped to exactly the tables and columns the application touches, and use row-level security for per-tenant isolation instead of relying on the application layer to filter correctly on every query:
CREATE TABLE orders (id int PRIMARY KEY, customer text, total numeric);
CREATE ROLE app_svc LOGIN PASSWORD 'a-real-password';
GRANT SELECT, INSERT, UPDATE, DELETE ON orders TO app_svc;
See Roles and privileges for table/column grants and Row-level security for per-tenant policies.
8. Secrets
Prefer SCRAMDB_LICENSE_KEY over license_key in the config TOML: the environment variable wins if both are set, and it keeps the token out of an operator-readable file on disk. See Configuration: Environment variables.
If you use the UDF package registry with a bearer token, [udf.registry].token_file must be mode 0600 or tighter. This is enforced, not a suggestion: ScramDB refuses to start if the token file is group- or world-readable.
chmod 600 /etc/scramdb/registry-token
9. Know what is actually enforced
USAGE on a schema (a qualified name in a schema the role may not use is refused, an unqualified one skips it, see Schema USAGE), CONNECT (a login without it is refused) and TEMPORARY (a temporary table, view or sequence without it is refused) on a database, USAGE on a type, USAGE on a language (a role without it cannot make a function, a procedure or a DO block in that language, see Language privileges; an untrusted language is the superuser's alone and refuses GRANT and REVOKE with 42809), CREATE (schema and database level), a role's CREATEDB and INHERIT, the ADMIN, INHERIT and SET options of a membership, a role's CONNECTION LIMIT, and VALID UNTIL are enforced, see Roles and privileges and Managing roles and passwords. The predefined role pg_read_all_settings gates the settings only a superuser sees otherwise, and pg_execute_server_program gates COPY ... PROGRAM, which runs a shell command with the server's own rights: grant it only to a role you would let log in to the server host. Privileges that are not available yet are listed in Roles and privileges.
Three things hold with nothing to configure. Every name the server writes into text it makes itself (a stored view or index definition, the SQL a foreign key runs, the output names of a rewritten query) is quoted when it needs it, so a role, schema, table or column named with quotes, spaces or a keyword cannot split into other statements on any node of a cluster. A refusal names the object and the privilege and never carries a value of a row the role cannot read: a 23505 unique violation shows its key values only to a role that may read the column. And the views of the node's own operation (scram_quarantined_tables, scram_disk, scram_daemons) show the whole node to a superuser or a pg_read_all_stats member and a role's own database to any other role, see Roles and privileges. A replica read of a cluster never answers a statement that depends on the caller's role or settings: it runs on the node's own path.
10. The UDF sandbox guarantee
Every installed user-defined function, in every language ScramDB supports, runs sealed: no filesystem access, no network, no subprocess, no environment access. This holds regardless of what a package's own manifest declares wanting; ScramDB doesn't widen what a module can do based on its own stated capabilities today, every module is sealed the same way no matter what it asks for.
Resource caps bound a runaway call:
| Cap | Default | Bounds |
|---|---|---|
fuel_per_batch | 500,000,000 | Compute per batch |
memory_bytes | 64MB | Linear memory per invocation |
timeout_ms | 1000 | Wall-clock time per invocation; for a Python or Ruby function, the processor time of the call beyond the interpreter's start |
output_bytes | 16MB | Result size per invocation |
Breaching any of these surfaces as a loud, typed error naming the function and the specific limit it hit, never a silent truncation. For Python and Ruby functions, see Writing a package.
Python and Ruby. LANGUAGE python and LANGUAGE ruby functions run through their own interpreted path, and statement_timeout or a cancel bounds a statement that runs one. Install only function bodies you trust in those languages. If you don't need UDFs at all, set [udf].enabled = false to disable the substrate entirely, including the Wasm engine startup cost.
11. Registry egress control for UDF packages
For an air-gapped deployment, set [udf.registry].offline = true. Every name-form install verb (scram.install('ns/pkg'), scram.upgrade, scram.versions) then refuses loudly instead of dialing out. The bytes-upload install form (scram.install(bytea) / scram.register) always works either way: it makes no network call, so it's the escape hatch for offline installs.
Use allow and deny glob lists to control which package names may install at all, independent of offline mode:
[udf.registry]
offline = true
allow = ["mycompany/*"]
deny = []
deny wins over allow on a match.
12. Encrypt the disks and buckets
ScramDB does not encrypt anything it writes: its data files, its write-ahead log, its backups, its WAL archive and the objects of its cold tier are stored as they are. TLS protects the connection, and nothing else. Put the data directory on an encrypted volume, and give every bucket that holds a backup, an archive or cold-tier objects the encryption your cloud provides.
Hold the line when the application is the attack surface
A SQL injection in an application runs with the application's role and nothing more: ScramDB applies that role's privileges and row-level security to every statement it runs, exactly as PostgreSQL does. What it can reach is what you granted. Four rules close what an injection could still use:
- Never key row-level security to a setting the client can change. A policy written as
USING (tenant = current_setting('app.tenant'))is bypassed by any statement that runsSET app.tenant = '2', injected ones included. Key policies to the role (current_user, a membership the role holds) or to a value only aSECURITY DEFINERfunction can set. - Grant only the columns and tables the application reads. An injection reads every row and column the role may read, password hashes in an application table included: keep secrets in tables or columns the role holds no
SELECTon. - Do not show database errors to end users. Log them and answer a generic message; an error text echoed back is how error-based injection reads data one value at a time.
- Bound statements per role.
ALTER ROLE app_svc SET statement_timeout = '5s'(andidle_in_transaction_session_timeout) stops time-based probing and runaway statements from holding workers.
Pass values as parameters (the extended protocol's $1, every driver's placeholders), never by building SQL text from input.