Commands

Subcommands, connection modes, and operational reference — applies to every installation method.

Subcommands

matviews, indexes, audit, and config query the running instance's dashboard API. Use --dashboard-port if your instance runs on a non-default port. status queries the database directly and falls back to the local state file.

Connection modes

--upstream accepts two formats that determine what Gold Lapel can do:

Observation only

A bare host:port. Proxies and logs query patterns but cannot create database objects.

# Observation-only mode — proxies and logs, but can't modify the database
goldlapel --upstream localhost:5432

Full optimization

A PostgreSQL connection string with credentials. Enables materialized views, indexes, query rewriting, and refresh.

# Full optimization mode (default) — creates materialized views, indexes, rewrites queries
goldlapel --upstream 'postgresql://goldlapel:password@localhost:5432/mydb'

Both postgresql:// and postgres:// URL schemes are supported, as well as key-value format (host=localhost port=5432 user=goldlapel dbname=mydb).

Bellhop mode

Bellhop mode is the opt-in observe-only mode. Use it to monitor query patterns without any database modifications — useful for cautious rollouts, debugging, or the free tier:

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

Stays on: connection pooling, failover, TLS, write detection, pin detection, query observation, dashboard. Paused: matview creation, query rewriting, result/batch caching, N+1 batching, coalescing, prepared statement promotion, background evaluate/refresh/shadow loops.

Live-reloadable — change mode in goldlapel.toml and it takes effect automatically. No restart, no dropped connections. Waiter selections are preserved — bellhop is "pause," not "reset."

Read replicas

Route reads to replicas and writes to the primary:

goldlapel \
  --upstream 'postgresql://user:pass@primary:5432/mydb' \
  --replica 'postgresql://user:pass@replica1:5432/mydb' \
  --replica 'postgresql://user:pass@replica2:5432/mydb'

goldlapel v0.1.0
  :7932 -> primary:5432 (waiter, pool = 20 (transaction, 2 replicas))
  dashboard: http://127.0.0.1:7933
  invalidation: :7934

Replicas are selected round-robin. After a write, reads route to the primary for --read-after-write-secs (default 5s) to ensure read-after-write consistency. If a replica fails, queries fall back to the primary. Transaction-mode pooling is auto-enabled when replicas are configured.

Automatic failover

Route traffic to a standby when the primary is down:

goldlapel \
  --upstream 'postgresql://user:pass@primary:5432/mydb' \
  --fallback 'postgresql://user:pass@standby:5432/mydb'

Background TCP health checks run against the primary every 2 seconds. Three consecutive failures trigger failover to --fallback; two consecutive successes restore the primary. Mid-session failover works between transactions.

TLS

Upstream TLS

For managed Postgres providers that require TLS, add sslmode=require to the connection string.

# Upstream TLS (managed Postgres: RDS, Supabase, Neon)
goldlapel --upstream 'postgresql://user:pass@db.example.com:5432/mydb?sslmode=require'

Client-facing TLS

Encrypts the app-to-proxy connection. Only needed when app and proxy are on different hosts across an untrusted network.

# Client-facing TLS (only needed across untrusted networks)
goldlapel \
  --upstream 'postgresql://user:pass@db.example.com:5432/mydb?sslmode=require' \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key

Mutual TLS (mTLS)

Require connecting apps to present a valid client certificate signed by your CA:

# Mutual TLS — require client certificates
goldlapel \
  --upstream 'postgresql://user:pass@db.example.com:5432/mydb?sslmode=require' \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key \
  --tls-client-ca /path/to/ca.crt

Subcommand details

goldlapel init

Generates a fully commented goldlapel.toml with all defaults and one-line explanations.

goldlapel init

Created goldlapel.toml with all settings documented.
Edit upstream to point at your database.

Guards against overwriting an existing config file.

goldlapel update

Downloads the latest Gold Lapel binary and live-reloads if a running instance is detected. Active connections are maintained throughout — the old process finishes serving its current queries while the new process takes over. Not a single connection is lost.

goldlapel update

goldlapel v0.1.0 -> v0.2.0
  downloaded goldlapel-linux-x86_64
  replaced /usr/local/bin/goldlapel

If no running instance is detected, the binary is updated in place and the next start uses the new version. Combine with --proxy-port to target a specific instance when running multiple.

Detects platform (Linux/macOS/Windows, x86_64/aarch64, glibc/musl) and downloads the correct binary. Downloaded binaries are verified with Ed25519 signatures before installation — tampered binaries are rejected automatically. Also checks automatically on startup (non-blocking) and logs a message if a newer version is available. Warns if you installed via a wrapper package manager (pip, npm, gem, etc.) — use that package manager to update instead.

goldlapel reload

Live reload — apply a new binary or configuration change without losing a single connection. Uses SO_REUSEPORT for zero-gap handoff. If the new process fails to start, the old process resumes automatically.

goldlapel reload --proxy-port 7932

The reload process: the old process flushes state to disk, spawns a new process on the same port, verifies the new process is ready, then finishes serving its active connections before exiting. No connection is interrupted. State — materialized views, indexes, counters, query patterns — is preserved across the reload.

Also available via HTTP: POST /api/reload on the dashboard port (platform-agnostic, works everywhere including Windows).

goldlapel status

Summary stats from the running proxy. With a full connection string, queries the database for authoritative matview/index counts. Without one, falls back to the local state file (~/.goldlapel/state.json).

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

goldlapel v0.1.0 — 3h 42m

  Queries observed   1,247
  Queries rewritten    892 (71.5%)
  Active matviews        3
  Active indexes         2

Top patterns by impact:
  842 queries   avg 187ms   SELECT o.id, c.name FROM orders o JOIN customers c…
  312 queries   avg 45ms    SELECT p.name, o.quantity FROM products p JOIN orde…
   43 queries   avg 12ms    SELECT u.email, s.token FROM users u JOIN sessions…

goldlapel matviews

Lists all materialized views created by Gold Lapel, including hit counts, base tables, refresh timing, whether the view uses incremental maintenance (IMMV via pg_ivm), and verification status.

goldlapel matviews

Matviews (3 active)

  View                           Tables              Hits   Last hit     Refresh     IMMV   Verified
  mv_00b59a8157e6f5ae            orders, customers    842   2m ago       5m ago      yes    yes
  mv_a3f1c2d4e5b6a7c8            products, orders     312   1m ago       3m ago      no     yes
  mv_9e8d7c6b5a4f3e2d            users, sessions       43   8m ago       12m ago     no     pending

goldlapel indexes

Lists all indexes created by Gold Lapel with their table and columns.

goldlapel indexes

Indexes (2 active)

  Index                          Table         Columns
  idx_00b59a8157e6f5ae_status    orders        status
  idx_a3f1c2d4e5b6a7c8_cat      products      category_id

goldlapel audit

Decision timeline showing every autonomous action Gold Lapel has taken — what it observed, what it did, and the measured impact. Events include pattern discovery, matview creation/routing/expansion/drop, index creation, shadow verification, and consolidation cleanup.

goldlapel audit

Audit timeline (5 events)

  [2m ago]  MATVIEW ROUTED  mv_00b59a8157e6f5ae
    OBSERVED  Pattern 00b59a81 hit 842 times, avg 187ms
    ACTION    Routing queries to materialized view
    IMPACT    71.5% of queries now served from matview

  [15m ago]  MATVIEW CREATED  mv_00b59a8157e6f5ae
    OBSERVED  Pattern 00b59a81 hit 3 times (threshold reached)
    ACTION    Created materialized view on orders JOIN customers
    IMPACT    Pending — shadow verification in progress

goldlapel config

Full live overview of the running instance: mode, uptime, query counts, strategy counters, pool stats, replica routing, failover status, configuration values, enabled/disabled strategies, license info, and top 25 query patterns by impact.

goldlapel config

goldlapel export

Exports Gold Lapel's full optimization state as a versioned JSON bundle — query patterns, matviews, indexes, strategy counters, config, audit log, and computed impact summary. Useful for migration planning, debugging, or sharing with support.

# Print to stdout
goldlapel export

# Write to file
goldlapel export --output bundle.json

The impact summary includes total queries optimized, optimization rate, cache hit rate, top 10 patterns by impact, matview utilization, and estimated time saved.

goldlapel clear-cache

Clears all caches on the running instance — result cache, batch cache, and matview staleness markers. The proxy stays running. New queries rebuild the caches naturally.

goldlapel clear-cache

Use after running migration scripts, restoring a backup, or making direct writes to the database that bypass the proxy. Equivalent to pressing "Clear All Caches" in the dashboard.

goldlapel refresh

Refresh all materialized views, or a specific one by name. IMMVs (incrementally maintained views via pg_ivm) are skipped with a message — they refresh automatically on writes.

# Refresh all matviews
goldlapel refresh

# Refresh a specific matview
goldlapel refresh mv_00b59a8157e6f5ae

goldlapel drop

Drop all materialized views and their associated indexes and metadata, or a specific view by name. Uses the same cleanup path as license expiration — indexes and metadata are cleaned up properly.

# Drop all matviews + indexes
goldlapel drop

# Drop a specific matview
goldlapel drop mv_00b59a8157e6f5ae

The proxy continues running after a drop. New matviews will be created as query patterns are re-observed.

goldlapel pause / goldlapel resume

Temporarily suspend all optimizations. The proxy continues forwarding queries but stops creating matviews, rewriting queries, caching results, and detecting N+1 patterns. Resume picks up where it left off.

# Suspend optimizations
goldlapel pause

# Resume optimizations
goldlapel resume

Pause is distinct from bellhop mode. Bellhop means "configured as passthrough-only" — pause means "temporarily suspended by the operator." The dashboard shows "paused" mode while suspended. Existing matviews and indexes are preserved — they are not dropped on pause.

goldlapel license

Shows license or trial status, tier, billing cycle, expiration, and instance count enforcement details.

goldlapel license

Gold Lapel — Standard tier (annual)
  Status:     active
  Customer:   cust_abc123
  Expires:    2027-03-15
  Instances:  1 of 1

Gold Lapel includes a 14-day trial. License path resolution: --license flag > GOLDLAPEL_LICENSE env > license in goldlapel.toml > ~/.goldlapel/license.key.

goldlapel activate <token>

Activates a license using the download token from your purchase confirmation email. Downloads and saves the license key to ~/.goldlapel/license.key.

goldlapel activate <token>

downloading license...
license saved to ~/.goldlapel/license.key
Gold Lapel — Standard tier (annual), valid until 2027-03-15

goldlapel clean --upstream <url>

Connects directly to the upstream database and removes everything Gold Lapel created — materialized views, indexes, and the _goldlapel schema. Your tables, your data, your own indexes are never touched.

Useful for resetting a development database, cleaning up after an evaluation, or starting fresh. On a database with no GL artifacts, it reports that there is nothing to clean and exits cleanly.

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

  dropped _goldlapel.mv_a1b2c3d4e5f6
  dropped _goldlapel.mv_f7e8d9c0b1a2
  dropped _goldlapel.idx_1a2b3c4d5e6f
  dropped schema _goldlapel
cleaned 3 artifacts from database

On a fresh database:

nothing to clean — no _goldlapel schema found

Gold Lapel also cleans up automatically when your license expires — no manual intervention needed. The proxy continues forwarding queries (never blocks traffic), but its artifacts are tidied away.

Opting out

Add /* goldlapel:skip */ to any query to bypass all optimization. The query is forwarded to Postgres untouched.

/* goldlapel:skip */ SELECT o.id, c.name
FROM orders o JOIN customers c ON o.customer_id = c.id
WHERE o.status = 'active';

The annotation works in any comment style. Postgres strips comments before execution, so it never reaches the database. Write detection still runs for staleness tracking.

Logging

Set RUST_LOG=info to see Gold Lapel in action:

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

INFO goldlapel::capture: query hash="00b59a815" normalized="SELECT o.id, c.name FROM orders o JOIN customers c ON o.customer_id = c.id WHERE o.status = ?"
INFO goldlapel::stats:   pattern hash="00b59a815" freq=842 avg="187ms" impact=157514
INFO goldlapel::matview: created materialized view view="_goldlapel.mv_00b59a8157e6f5ae"
INFO goldlapel::proxy:   query rewritten hash="00b59a815" view="_goldlapel.mv_00b59a8157e6f5ae"

Database objects

Gold Lapel creates objects in the _goldlapel schema:

• Materialized views: mv_<hash> (standard) or IMMVs via pg_ivm (trigger-maintained)
• Indexes: idx_<hash> — B-tree, composite, trigram, expression, partial, and covering
• Metadata tables: meta, index_meta

These are safe to drop — Gold Lapel recreates what it needs. The management connection user needs CREATE privileges on the target database.

Persistent state

Pattern stats, strategy counters, and query counters persist to ~/.goldlapel/state.json. On restart, Gold Lapel seeds from the state file immediately — it can evaluate matviews without re-observing all patterns. If pg_stat_statements is available, Gold Lapel also seeds from historical query stats at startup for zero cold-start latency.