Environment Variables Reference¶

This page provides the complete configuration reference for RockLake. Every environment variable recognized by the system is documented here: its purpose, type, default value, valid range, and examples. Configuration is the primary way operators control RockLake's behavior in production — from specifying where catalog data is stored, to tuning performance parameters, to enabling TLS encryption.

RockLake follows the twelve-factor app methodology: configuration comes from the environment, not from configuration files. This makes deployment straightforward across diverse environments (Docker, Kubernetes, systemd, Lambda) without needing to manage config file paths or formats.

Precedence Rules¶

When the same option is specified in multiple places, the highest-priority source wins:

1. Command-line flags (highest priority): --storage, --bind, etc.
2. Environment variables: ROCKLAKE_STORAGE, ROCKLAKE_BIND, etc.
3. Compiled defaults (lowest priority): built into the binary

Command-line flags always override environment variables. This allows operators to temporarily override configuration without modifying the deployment environment.

Storage Configuration¶

These variables control where RockLake stores catalog data and how it authenticates to object storage providers.

ROCKLAKE_STORAGE¶

The object storage path for the catalog. This is the most important configuration variable — it determines where all catalog data is persisted.

Valid formats:

# Local filesystem (development only)
ROCKLAKE_STORAGE=./my-catalog
ROCKLAKE_STORAGE=/var/lib/rocklake/catalog

# Amazon S3
ROCKLAKE_STORAGE=s3://my-bucket/catalog/

# S3 Express One Zone
ROCKLAKE_STORAGE=s3://my-bucket--usw2-az1--x-s3/catalog/

# Google Cloud Storage
ROCKLAKE_STORAGE=gs://my-bucket/catalog/

# Azure Blob Storage
ROCKLAKE_STORAGE=az://my-container/catalog/

Important: The path should be dedicated to this RockLake instance. Do not share a storage path between multiple independent catalogs.

AWS_REGION¶

The AWS region for S3 access. Required when using S3 storage (unless the region can be inferred from the bucket name or endpoint).

AWS_REGION=eu-west-1
AWS_REGION=ap-southeast-1

AWS_ENDPOINT_URL¶

Custom endpoint URL for S3-compatible storage services (MinIO, Ceph, DigitalOcean Spaces, Cloudflare R2, etc.).

# MinIO (local development)
AWS_ENDPOINT_URL=http://localhost:9000

# Cloudflare R2
AWS_ENDPOINT_URL=https://ACCOUNT_ID.r2.cloudflarestorage.com

# DigitalOcean Spaces
AWS_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com

AWS_ACCESS_KEY_ID¶

Static AWS access key for authentication. Prefer IAM roles (instance profiles, IRSA, ECS task roles) over static credentials in production.

AWS_SECRET_ACCESS_KEY¶

Static AWS secret key. Always used in conjunction with AWS_ACCESS_KEY_ID.

AWS_SESSION_TOKEN¶

Temporary session token for AWS STS credentials (assumed roles, federated access).

GOOGLE_APPLICATION_CREDENTIALS¶

Path to a GCS service account JSON key file. Used when running outside GCP (where Application Default Credentials are not available).

GOOGLE_APPLICATION_CREDENTIALS=/etc/rocklake/gcs-key.json

AZURE_STORAGE_ACCOUNT¶

Azure storage account name. Required for Azure Blob Storage.

AZURE_STORAGE_ACCESS_KEY¶

Azure storage account access key.

Server Configuration¶

These variables control the network listener, session management, and access control.

ROCKLAKE_BIND¶

The address and port RockLake listens on for PostgreSQL wire protocol connections.

# Listen on all interfaces (required in Docker/K8s)
ROCKLAKE_BIND=0.0.0.0:5432

# Non-standard port (to avoid conflict with local PostgreSQL)
ROCKLAKE_BIND=127.0.0.1:5433

# IPv6
ROCKLAKE_BIND=[::]:5432

Security note: Binding to 0.0.0.0 exposes the service to the network. Ensure network-level access control (security groups, network policies) is in place.

ROCKLAKE_MAX_SESSIONS¶

Maximum number of concurrent client connections. Connections beyond this limit receive an immediate error.

ROCKLAKE_MAX_SESSIONS=128

Sizing guidance: Each session uses minimal memory (a few KB for session state). The limit protects against connection exhaustion, not memory exhaustion. Set based on your expected peak concurrent connections plus 20% headroom.

ROCKLAKE_PASSWORD¶

When set, requires clients to authenticate with this password during the PostgreSQL startup handshake.

ROCKLAKE_PASSWORD=my-secure-password

Authentication flow: Uses PostgreSQL's cleartext password authentication. For production, combine with TLS to protect the password in transit.

ROCKLAKE_REQUIRE_TLS¶

When true, rejects connections that do not use TLS encryption.

ROCKLAKE_REQUIRE_TLS=true

Requires ROCKLAKE_TLS_CERT and ROCKLAKE_TLS_KEY to also be set.

ROCKLAKE_READ_ONLY¶

When true, the instance rejects all write operations (DDL, data file registration, etc.). Useful for read replicas or maintenance windows.

ROCKLAKE_READ_ONLY=true

Write attempts return SQLSTATE 25006 (read_only_sql_transaction).

TLS Configuration¶

ROCKLAKE_TLS_CERT¶

Path to the TLS certificate file in PEM format. Required to enable TLS.

ROCKLAKE_TLS_CERT=/etc/rocklake/tls/server.crt

The certificate file should contain the full chain (server certificate followed by intermediate certificates).

ROCKLAKE_TLS_KEY¶

Path to the TLS private key file in PEM format.

ROCKLAKE_TLS_KEY=/etc/rocklake/tls/server.key

Logging Configuration¶

RUST_LOG¶

Controls log output verbosity using the tracing subscriber's filter syntax. Supports per-crate granularity.

# Basic levels
RUST_LOG=info          # Default: operational messages
RUST_LOG=debug         # Verbose: includes internal state
RUST_LOG=warn          # Quiet: only warnings and errors

# Per-crate filtering
RUST_LOG=rocklake_pgwire=debug,rocklake_catalog=info
RUST_LOG=rocklake_catalog::gc=trace
RUST_LOG=info,rocklake_pgwire::handler=debug

Common debugging configurations:

ROCKLAKE_LOG_FORMAT¶

Controls the output format of log messages.

# Human-readable (for terminal/development)
ROCKLAKE_LOG_FORMAT=text
# Output: 2025-01-15T10:30:00Z INFO rocklake_pgwire: new session from 192.168.1.5:4321

# Structured JSON (for log aggregation: Datadog, Loki, CloudWatch)
ROCKLAKE_LOG_FORMAT=json
# Output: {"timestamp":"2025-01-15T10:30:00Z","level":"INFO","target":"rocklake_pgwire","message":"new session","client":"192.168.1.5:4321"}

Performance Tuning¶

These variables control RockLake's internal performance behavior. The defaults are appropriate for most workloads. Change them only after benchmarking demonstrates a benefit.

ROCKLAKE_HOT_KEY_CACHE¶

Enables or disables the hot key cache (in-memory caching of frequently-accessed system keys like counters and epoch).

ROCKLAKE_HOT_KEY_CACHE=false  # Disable for debugging cache issues

Disabling this forces every read to go to SlateDB (and potentially object storage). Useful only for debugging.

ROCKLAKE_BATCH_SIZE¶

Maximum number of key-value mutations allowed in a single write batch. Prevents unbounded memory usage from very large transactions.

ROCKLAKE_BATCH_SIZE=5000  # For bulk operations (many columns per table)

ROCKLAKE_PREFETCH_DEPTH¶

Number of SST blocks to prefetch during prefix scans. Higher values improve sequential read performance but use more memory.

ROCKLAKE_PREFETCH_DEPTH=8  # For high-latency storage (cross-region S3)

ROCKLAKE_CACHE_SIZE_MB¶

SlateDB block cache size in megabytes. The block cache stores recently-read SST blocks in memory to avoid repeated object storage fetches.

ROCKLAKE_CACHE_SIZE_MB=256  # For large catalogs (many tables/files)

Sizing guidance: The working set for most catalogs fits in 64–128 MB. Larger caches help when the catalog has thousands of tables or hundreds of thousands of data files.

ROCKLAKE_INLINE_THRESHOLD_BYTES¶

Maximum size of inlined data in catalog values. Files smaller than this threshold may have their content stored directly in the catalog (alongside their metadata) rather than as separate objects.

ROCKLAKE_INLINE_THRESHOLD_BYTES=8192  # Inline larger files
ROCKLAKE_INLINE_THRESHOLD_BYTES=0     # Never inline (always reference)

Metrics Configuration¶

ROCKLAKE_METRICS_BIND¶

Address and port for the Prometheus metrics HTTP endpoint.

ROCKLAKE_METRICS_BIND=0.0.0.0:9090

When set, RockLake exposes a /metrics endpoint in Prometheus exposition format at the specified address.

Health Check Configuration¶

ROCKLAKE_HEALTH_BIND¶

Address and port for the HTTP health check endpoint.

ROCKLAKE_HEALTH_BIND=0.0.0.0:8080

When set, exposes /health/live (liveness) and /health/ready (readiness) endpoints.

Example Configurations¶

Local Development¶

ROCKLAKE_STORAGE=./dev-catalog
ROCKLAKE_BIND=127.0.0.1:5433
RUST_LOG=debug
ROCKLAKE_LOG_FORMAT=text

Production (AWS S3)¶

ROCKLAKE_STORAGE=s3://mycompany-lakehouse/catalog/
AWS_REGION=us-east-1
ROCKLAKE_BIND=0.0.0.0:5432
ROCKLAKE_TLS_CERT=/etc/rocklake/tls/server.crt
ROCKLAKE_TLS_KEY=/etc/rocklake/tls/server.key
ROCKLAKE_REQUIRE_TLS=true
ROCKLAKE_PASSWORD=${ROCKLAKE_PASSWORD_FROM_SECRETS}
ROCKLAKE_MAX_SESSIONS=128
ROCKLAKE_CACHE_SIZE_MB=256
ROCKLAKE_METRICS_BIND=0.0.0.0:9090
ROCKLAKE_HEALTH_BIND=0.0.0.0:8080
RUST_LOG=info
ROCKLAKE_LOG_FORMAT=json

Docker Compose (with MinIO)¶

ROCKLAKE_STORAGE=s3://catalog/data/
AWS_ENDPOINT_URL=http://minio:9000
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_REGION=us-east-1
ROCKLAKE_BIND=0.0.0.0:5432
RUST_LOG=info

Further Reading¶

• Deployment: Configuration — Deployment-specific configuration guidance
• Performance: Tuning — When and how to adjust performance parameters
• Deployment: TLS — TLS setup guide