Configuration

Sensible defaults. Works as-is. Options when you need them.

goldlapel --upstream 'postgresql://user:pass@localhost:5432/mydb'

Example goldlapel.toml

A production-ready config file. All fields are optional — Gold Lapel only needs upstream. Copy what you need, ignore the rest.

upstream = "postgresql://goldlapel:password@localhost:5432/mydb"
mode = "waiter"
proxy_port = 7932
dashboard_port = 7933
invalidation_port = 7934
logical_decoding = true
fallback = "postgresql://goldlapel:password@standby:5432/mydb"
replicas = [
    "postgresql://goldlapel:password@replica1:5432/mydb",
    "postgresql://goldlapel:password@replica2:5432/mydb",
]

[l1]
enabled = true
cache_size = 32768
subscriber_connections = 1

[l2]
result_cache = true
result_cache_size = 65536
prepared_cache = true
prepared_cache_size = 1024

[l3]
matviews = true
indexes = true
threshold = 1
refresh_interval_secs = 60
shadow_verification = true

[sql]
rewrite = true
join_reorder = true
subquery_flatten = true
predicate_pushdown = true

[thresholds]
min_pattern_count = 1
refresh_interval_secs = 60
pattern_ttl_secs = 604800
read_after_write_secs = 5

[cache]
result_cache_size = 65536
prepared_cache_size = 1024
batch_cache_size = 64
batch_cache_ttl_secs = 300

[pool]
enabled = true
size = 50
mode = "transaction"
idle_timeout_secs = 300
timeout_secs = 10

[tls]
cert = "/path/to/server.crt"
key = "/path/to/server.key"

[n1]
threshold = 5
window_ms = 500
cross_threshold = 10

[disable]
trigram_indexes = true

[enable]
coalescing = true

[exclude]
tables = ["migrations", "sessions"]

# [oidc]
# issuer = "https://accounts.google.com"
# client_id = "your-client-id"
# client_secret = "your-client-secret"
# redirect_uri = "https://gl.example.com:7933/auth/oidc/callback"

# [saml]
# idp_metadata_url = "https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml"
# sp_entity_id = "https://gl.example.com:7933"
# acs_url = "https://gl.example.com:7933/auth/saml/acs"

How configuration works

Precedence

Configuration sources are checked in order, highest priority first:

1. CLI flags (--mode waiter)
2. Shell environment variables (GOLDLAPEL_MODE=waiter)
3. .env file in the working directory
4. goldlapel.toml config file
5. Built-in defaults

Higher-priority sources always win. A CLI flag overrides the same setting from any other source. At startup, Gold Lapel logs every non-default setting with its resolved value and source (cli, env, .env, config, default).

Config file (goldlapel.toml)

Run goldlapel init to generate a fully commented config file with all settings documented and default values:

goldlapel init

Gold Lapel auto-discovers goldlapel.toml in the current directory on startup. Use --config to load from a different location:

goldlapel --config /etc/goldlapel/production.toml

All fields are optional — only set what you want to change. Unknown keys are rejected (catches typos before they become silent misconfigurations). The example config above shows the full TOML format.

Environment variables

Set environment variables directly in your shell:

export GOLDLAPEL_UPSTREAM='postgresql://goldlapel:password@localhost:5432/mydb'
export GOLDLAPEL_POOL_SIZE=50
goldlapel

Or create a .env file in the directory where you run Gold Lapel:

GOLDLAPEL_UPSTREAM=postgresql://goldlapel:password@localhost:5432/mydb
GOLDLAPEL_POOL_SIZE=50
GOLDLAPEL_RESULT_CACHE_SIZE=65536

Every CLI flag has a GOLDLAPEL_ env var equivalent — see the full reference tables below.

Wrapper config objects

Language wrappers accept a config dict/object that maps directly to CLI flags. Every setting in the reference tables below can be set via the config object.

Python (snake_case)

import goldlapel

gl = goldlapel.start("postgresql://user:pass@localhost/mydb", config={
    "pool_size": 50,
    "disable_matviews": True,
    "replica": ["postgresql://user:pass@replica1/mydb"],
})

JavaScript (camelCase)

import * as goldlapel from 'goldlapel';

const gl = await goldlapel.start('postgresql://user:pass@localhost/mydb', {
  config: {
    poolSize: 50,
    disableMatviews: true,
    replica: ['postgresql://user:pass@replica1/mydb'],
  },
});

Naming convention: Python, Ruby, Go, and PHP use snake_case keys. JavaScript, Java, and .NET use camelCase keys. Both map to the same CLI flags (pool_size / poolSize → --pool-size).

Boolean keys like disable_matviews are flags — True enables them, False (or omitting) leaves them off. Array keys like replica produce repeated CLI flags.

Unknown keys raise an error immediately with the full list of valid keys. Use config_keys() to see all valid keys programmatically:

# Python
goldlapel.config_keys()

# JavaScript
import { configKeys } from 'goldlapel'
configKeys()

Live reload

Gold Lapel polls goldlapel.toml every 30 seconds. Every setting live-reloads — edit the file, save, and changes take effect automatically. No restart, no dropped connections. Parse errors keep the current config.

[oidc]
issuer = "https://accounts.google.com"
client_id = "your-client-id"
client_secret = "your-client-secret"
# redirect_uri defaults to dashboard URL + /auth/oidc/callback

[saml]
idp_metadata_url = "https://login.microsoftonline.com/.../federationmetadata.xml"
# sp_entity_id defaults to dashboard URL
# acs_url defaults to dashboard URL + /auth/saml/acs

Tuning tips

Full reference

Pick your config method. Tables show the relevant key, default, and description.

All settings live-reload — edit goldlapel.toml and changes take effect automatically.

Core

Replicas & failover

TLS

L1 — Native cache

L2 — Proxy cache

L3 — Materialized views & indexes

SQL optimization

Thresholds

Caching

N+1 detection

Write acceleration

Connection pooling

Exclusions

OIDC (SSO)

SAML 2.0 (SSO)

Disable toggles

All strategies are enabled by default. Disable individually.

Enable toggles

These strategies are disabled by default. Enable individually.