Configuration

4 min read

Quickstart

  1. Install PgArachne
  2. Configure environment
  3. Set up security and auth
  4. Deploy behind HTTPS proxy

Configuration

PgArachne loads configuration from environment variables or a file.

Note: schema.sql attempts to create the pgarachne_admin role and grant it to pgarachne. If you run the script without superuser privileges, role creation is skipped. Create the role and grant it manually if needed.
The proxy user (DB_USER) must be a member of pgarachne and pgarachne_admin to verify and mint API tokens.
Security Note: PgArachne does not handle database passwords in the configuration file. Rely on the standard PostgreSQL .pgpass file mechanism (or PGPASSWORD system variable) for authentication.
Tip: If you run PgArachne behind a reverse proxy, set TRUSTED_PROXIES so client IPs are resolved correctly and rate limiting cannot be spoofed.
Search Order: If no configuration file is specified via CLI, it searches in:
  1. Current directory: ./pgarachne.env (All OS)
  2. User config:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. System config: /etc/pgarachne/pgarachne.env (Linux/macOS only)

Minimal Configuration Example

This is all you need to get started:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Required variables: DB_HOST, DB_PORT, DB_USER, JWT_SECRET (minimum 32 bytes; generate with openssl rand -hex 32).

Quick Validation Checklist

  • JWT_SECRET is long, random, and not reused across environments.
  • DB_USER can switch only to expected roles (verify role membership grants).
  • TRUSTED_PROXIES is set when running behind a reverse proxy.
  • LOGIN_RATE_LIMIT is enabled for internet-facing deployments.
  • METRICS_LISTEN_ADDR is private (for example 127.0.0.1:9090).

Configuration Reference

VariableRequiredDescription
Database Connection
DB_HOST✓PostgreSQL server address (e.g., localhost).
DB_PORT✓Database port.
DB_USER✓The database user PgArachne connects with.
DB_SSLMODE○PostgreSQL SSL mode. Default: require. Set disable explicitly only for local development against a non-TLS PostgreSQL.
DB_SSLROOTCERT○Path to CA root certificate (PEM).
DB_SSLCERT○Path to client certificate (PEM).
DB_SSLKEY○Path to client private key (PEM).
HTTP Server
HTTP_PORT○Port to listen on. Default: 8080.
API_PREFIX○First URL path segment for all database endpoints (/jsonrpc, /sse, /mcp). Default: db, giving routes like /db/:database/jsonrpc. Only letters, digits, hyphens and underscores are allowed.
PID_FILE○Path to daemon PID file used by -start/-stop. Default: OS user cache dir (fallback: temp dir).
ALLOWED_ORIGINS○CORS settings. Comma-separated list of allowed origins (e.g. https://myapp.com). Default: unset — cross-origin browser requests are disabled. Set * explicitly to allow any origin.
STATIC_FILES_PATH○Absolute path to serve static files (Explorer/Frontend).
Security (JWT)
JWT_SECRET✓A long, random string used to sign session tokens. Minimum 32 bytes; generate with openssl rand -hex 32.
JWT_EXPIRY_HOURS○Session validity in hours. Default: 8.
JWT_ISSUER○If set, written into the iss claim on issue and required to match exactly on validation. Leave empty to skip issuer checking.
JWT_AUDIENCE○If set, written into the aud claim on issue and required to match on validation. Leave empty to skip audience checking.
JWT_LEEWAY○Clock-skew tolerance for exp/nbf/iat validation (e.g. 30s). Default: 30s.
LOGIN_RATE_LIMIT○Max login attempts per window. Default: 5. Set 0 to disable.
LOGIN_RATE_LIMIT_PER_IP○Max login attempts per client IP across all usernames, so rotating usernames does not bypass the limit. Default: 5× LOGIN_RATE_LIMIT. Set 0 to disable.
LOGIN_RATE_WINDOW○Rate limit window duration. Default: 1m.
Login rate limiting is per instance (in-memory). In multi-instance deployments, use a shared limiter if you need global enforcement.
TRUSTED_PROXIES○Trusted proxy IPs/CIDRs for X-Forwarded-For handling. Comma-separated. If empty, forwarded headers are ignored and client IP is taken from the direct connection.
MAX_REQUEST_BYTES○Max request body size in bytes. Default: 2097152.
MCP_SQL_ERROR_DETAIL○Include the raw PostgreSQL error message in MCP tool errors. Detailed errors help LLM agents self-correct, but can expose schema details (table and constraint names) to authenticated callers. Default: false.
DIRECT_POOL_LIMIT○Max number of distinct Basic-Auth credential connection pools. Default: 1000.
METRICS_ENABLED○Enable dedicated metrics endpoint. Default: true.
METRICS_LISTEN_ADDR○Metrics listener address (host:port). Default: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Max channels per SSE connection. Default: 8.
SSE_MAX_CLIENTS○Max concurrent SSE clients per database. Default: 1000.
SSE_CLIENT_BUFFER○SSE per-client buffer size (messages). Default: 64.
SSE_SEND_TIMEOUT○Max time to wait when sending to a slow client. Default: 2s.
SSE_HEARTBEAT○Heartbeat interval for SSE connections. Default: 20s.
SSE_IDLE_TIMEOUT○Idle timeout without notifications. Default: 90s.
Logging
LOG_LEVEL○Verbosity: DEBUG, INFO, WARN, ERROR. Default: INFO.
LOG_OUTPUT○Where to write logs: stdout or file path.

Required   Optional

Security behavior: requests without a valid Authorization header are rejected before opening a database connection.

Start the server:

./pgarachne -config .env

See also

Related Docs

← Installation JSON-RPC (Hello World) →