← Docs

Architecture

How the self-optimizing proxy works, from query capture to transparent rewriting.

Overview

Gold Lapel is a transparent PostgreSQL proxy written in Rust. It sits between your application and Postgres, speaking the native wire protocol. Your application connects to Gold Lapel exactly as it would connect to Postgres — same drivers, same queries, same transactions.

App  ->  Gold Lapel  ->  PostgreSQL
              |                  |
         query capture      read replicas
         pattern detection  failover standby
         matview creation
         query rewriting
         N+1 batching
         caching
         connection pooling

The proxy runs on a single async runtime and handles thousands of concurrent connections with minimal overhead.

Proxy layer

Gold Lapel speaks PostgreSQL's native wire protocol — both the simple query protocol and the extended protocol used by ORMs and prepared-statement drivers — so every driver, ORM, and migration tool works without changes.

In observation mode, the proxy is a pass-through that captures and logs queries but cannot modify the database. In optimization mode, it can create database objects, rewrite queries, and manage caching.

Client-facing TLS is supported with optional mutual TLS (mTLS) for client certificate authentication.

Query capture and normalization

Gold Lapel observes every query that passes through and learns which patterns matter most — so it knows where to focus its optimization effort.

Every query is normalized — literal values are replaced with placeholders to produce a canonical pattern hash. This means SELECT * FROM users WHERE id = 1 and SELECT * FROM users WHERE id = 42 are recognized as the same pattern.

Gold Lapel tracks per-pattern statistics including call count, duration, and impact score. These statistics drive all optimization decisions.

Cold-start from pg_stat_statements

When pg_stat_statements is available, Gold Lapel reads historical query stats at startup — so it knows your hottest queries before it sees a single live request. It gracefully falls back to learning from live traffic when the extension is not installed.

Pattern detection

Gold Lapel identifies which queries are worth optimizing by tracking how often each pattern appears and how much time it costs.

A background task periodically evaluates all known patterns against the configured threshold. Once a pattern crosses the threshold, Gold Lapel considers it for materialized view and index creation.

Pattern tracking uses LRU eviction — the least-recently-seen patterns are dropped first when the cap is reached. This prevents unbounded memory growth in high-cardinality environments without losing the patterns that matter.

Materialized view creation

When a query pattern repeats often enough, Gold Lapel pre-computes the results into a materialized view — turning expensive multi-table queries into fast single-table lookups.

When a pattern qualifies, Gold Lapel creates a materialized view in its own schema. Gold Lapel materializes a wide range of query shapes:

  • JOINs — multi-table joins replaced with pre-joined materialized views
  • GROUP BY — queries with GROUP BY materialized for fast lookups
  • Subqueries — uncorrelated and correlated subqueries materialized into pre-joined views
  • CTEs — Common Table Expressions with JOINs
  • DISTINCT — handled correctly through the matview and rewrite layers
  • UNION — both branches processed independently
  • SELECT * — wildcard queries expanded into explicit column references for correct rewriting

Matview consolidation

When multiple query patterns share the same join graph, Gold Lapel consolidates them into a single wide materialized view instead of creating duplicates. A new pattern can be routed to an existing matview, or an existing matview can be expanded to cover the new pattern's columns.

Consolidation has safety ceilings to prevent over-growth. Certain query types bypass consolidation entirely when shared views would compromise correctness.

Incremental matviews (pg_ivm)

When the pg_ivm extension is available, Gold Lapel creates Incrementally Maintainable Materialized Views (IMMVs) instead of standard matviews. IMMVs auto-refresh via triggers on base tables — no manual REFRESH MATERIALIZED VIEW needed. Writes to IMMV-backed tables trigger immediate cache invalidation.

Not all queries are eligible for IMMVs — certain query shapes fall back to standard matviews automatically.

Query rewriting

Your application sends the same query it always did. Gold Lapel silently redirects it to the pre-computed materialized view — same columns, same order, dramatically less work for Postgres.

Rewriting is transparent — the application has no idea it happened. The rewrite ensures the application receives the same columns in the same order. If a query includes /* goldlapel:skip */, it is forwarded to Postgres untouched.

RLS preservation

Row-Level Security policies are preserved through rewrites. Gold Lapel ensures that matview-backed queries enforce the same row-level constraints as the originals, and monitors for policy changes automatically.

Deep pagination detection

Queries with high OFFSET values trigger warnings with concrete keyset pagination suggestions.

Shadow verification

Gold Lapel never routes production traffic to a materialized view it hasn't verified first. Every new view is tested against the original query to confirm correctness before activation.

Verification compares the materialized view's results against the source query. Matching results activate rewriting; mismatches keep the matview (for indexing benefits) but block rewriting. Unverified matviews are retried automatically in the background.

Shadow verification is on by default and can be disabled with --disable-shadow-mode.

Automatic indexing

Gold Lapel creates targeted indexes based on your actual query patterns — indexes matched to what your application asks for in practice.

Gold Lapel creates targeted indexes on base tables based on observed query patterns:

  • B-tree indexes — single-column indexes for unindexed WHERE clause columns
  • Composite indexes — multi-column indexes for queries filtering on multiple columns simultaneously
  • Trigram GIN indexes — for LIKE '%pattern%' queries that defeat B-tree indexes. Requires the pg_trgm extension
  • Full-text search GIN indexes — for to_tsvector() @@ to_tsquery() queries. No extension required — uses PostgreSQL's built-in full-text search
  • Phonetic search indexes — for soundex() and dmetaphone() equality queries. B-tree expression indexes for fuzzy name matching. Requires the fuzzystrmatch extension
  • Vector similarity HNSW indexes — for pgvector <=> and <-> distance queries. Approximate nearest neighbor search for embeddings. Requires the pgvector extension
  • Expression indexes — indexes on computed expressions like LOWER(email) or UPPER(name)
  • Partial indexes — indexes with IS NULL/IS NOT NULL predicates as WHERE clauses, covering only matching rows
  • Covering indexes — B-tree indexes that INCLUDE non-key columns from SELECT, enabling index-only scans
  • Matview indexes — indexes on materialized views for frequently filtered columns, plus a unique index required for concurrent refresh

Each index type can be individually toggled via --disable-* flags.

Refresh lifecycle

Materialized views need to stay current as your data changes. Gold Lapel handles this automatically — refreshing views that are actively used and cleaning up ones that aren't.

Refreshes are activity-based: views refresh only when active and stale. Refreshes use REFRESH MATERIALIZED VIEW CONCURRENTLY to avoid blocking reads. The refresh interval is configurable.

Unused views are dropped automatically to reclaim resources. Stale or missing matviews fall back to the original query transparently.

N+1 detection and batching

ORMs sometimes generate the same query many times per request — a pattern that is easy to miss in application code. Gold Lapel catches these patterns automatically and collapses them into a single round-trip.

Gold Lapel detects N+1 query patterns in real time — when the same normalized query repeats rapidly, it is flagged as an N+1 pattern.

Cross-connection detection

Connection poolers distribute N+1 patterns across multiple connections. Gold Lapel detects these patterns both per-connection and globally, catching N+1 queries regardless of how connections are distributed.

Speculative prefetch

When an N+1 pattern fires, Gold Lapel prefetches all rows the remaining queries will need in a single round-trip. Subsequent queries for the same pattern serve instantly from cache. Write-driven invalidation ensures cache correctness.

Caching layers

Multiple layers of caching keep your hottest queries fast, with automatic invalidation when the underlying data changes — no manual cache-busting.

Gold Lapel provides multiple caching layers, all with write-driven invalidation:

  • Prepared statement cache — proxy-side prepared statement promotion for repeated rewritten queries
  • Local cache — query results cached in memory. The second time a query runs, it's served directly — no round-trip to Postgres. Write-driven invalidation keeps cached data fresh. No Redis, no Memcached, no infrastructure to manage
  • Batch cache — N+1 prefetch results cached with LRU eviction and table-based invalidation on writes
  • Query coalescing — request collapsing for identical in-flight queries. When multiple connections send the exact same query simultaneously, subsequent connections subscribe to the first's result

Each cache layer can be individually configured or disabled.

Connection pooling

Gold Lapel manages a pool of database connections so your application doesn't exhaust PostgreSQL's connection limit — even under high concurrency.

Gold Lapel includes a built-in connection pool with two modes:

  • Session mode (default) — reuses upstream connections across client sessions with automatic health checks and session cleanup
  • Transaction mode — shares upstream connections between transactions. Auto-detects session-scoped state and pins the connection when needed, gracefully degrading to session mode

Pool size and acquire timeout are configurable.

Upstream pooler auto-detection

When Gold Lapel detects an upstream connection pooler (Supabase Supavisor, Neon, AWS RDS Proxy, PgBouncer) by hostname, it automatically disables its own pool to avoid stacking poolers.

Read replica routing

Gold Lapel automatically sends reads to your replicas and writes to the primary — no application code changes, no read/write splitting middleware.

Routing uses conservative classification — read-only queries go to replicas, everything else routes to the primary. A per-session read-after-write safety window ensures clients see their own writes despite replication lag. If a replica connection fails, the query falls back to the primary — no queries lost.

Failover

If your primary goes down, Gold Lapel detects the failure and routes traffic to a standby — automatically, between transactions, without dropping connections.

Background health checks probe the primary continuously. Failures trigger failover to the configured fallback endpoint; successes restore the primary. Mid-session failover works between transactions.

Both replicas and failover auto-enable transaction-mode pooling so connections can be re-routed between transactions.

Bellhop mode

Bellhop mode is Gold Lapel's opt-in observe-only mode. Instantly disable all optimizations without removing Gold Lapel from the stack — useful for cautious rollouts, debugging, and the free tier.

Bellhop disables: matview creation, query rewriting, local/batch caching, N+1 batching, coalescing, prepared statement promotion, and all background optimization loops.

Bellhop preserves: connection pooling, failover, TLS, write detection, pin detection, query observation (capture, hashing, stats recording), and the dashboard.

Live-reloadable — flip mode in goldlapel.toml and it takes effect automatically. All observed patterns are preserved: Bellhop is "pause," not "reset."

# Observation only — proxies, logs, pools, but never modifies the database
goldlapel --mode bellhop --upstream 'postgresql://user:pass@localhost:5432/mydb'

Dashboard

A built-in web dashboard shows you everything Gold Lapel is doing — what it observed, what it optimized, and the measured impact of each decision.

The dashboard runs alongside the proxy, with zero configuration. It is a single HTML page embedded in the binary — no external assets required.

Overview tab

Stats cards (queries observed/rewritten, matviews, indexes), strategy counters with hit rates, connection pool stats, replica routing, failover status, matviews table with verified/pending badges, indexes table, top query patterns by impact, strategy config pills, and runtime configuration display. Conditional sections show/hide based on feature availability.

Show Your Work tab

A per-pattern decision timeline showing what Gold Lapel observed, what it did, and the measured impact of each autonomous decision. Events are enriched at response time with current pattern stats and matview hit counts so impact numbers stay current.

API endpoints

GET /api/stats returns the full proxy state as JSON. GET /api/audit?since=<epoch_ms> returns audit events for incremental polling. GET /api/export returns the full migration bundle.

Audit log

Every autonomous decision Gold Lapel makes is logged — what it observed, what action it took, and the measured impact. Full transparency into the proxy's reasoning.

Events are stored in a ring buffer and categorized with color-coded badges: observation, matview, index, verification, and cleanup. Each event captures three sections: what was OBSERVED, what ACTION was taken, and the measured IMPACT.

The audit log is accessible via the dashboard's Show Your Work tab, the GET /api/audit endpoint, the goldlapel audit CLI command, and the export bundle.

Export

Export Gold Lapel's full optimization state as a portable bundle — useful for auditing, sharing with your team, or migrating optimizations between environments.

The goldlapel export command produces a versioned JSON bundle capturing query patterns (with full SQL), materialized views, indexes, strategy counters, configuration, audit log, and a computed impact summary (total queries optimized, cache hit rate, top patterns, estimated time saved).

# Export full optimization state as a migration bundle
goldlapel export --output bundle.json

Also available via GET /api/export and the dashboard's download button.

License system

Gold Lapel includes a trial period. After that, a license key unlocks continued optimization. No license? No problem — Gold Lapel gracefully degrades to Bellhop mode and never blocks your traffic.

License validation ensures authorized usage. Enforcement is graceful — an expired or missing license degrades Gold Lapel to Bellhop mode (observe-only passthrough). It never blocks traffic or terminates connections.

Live reload

Live reloading — no connections disturbed. Edit goldlapel.toml, save, and every setting takes effect automatically.

Gold Lapel watches the config file for changes. When changes are detected, they are applied live — active connections finish their current work undisturbed, and service continues without a single connection lost.

Upgrades work the same way: goldlapel update downloads the latest binary and reloads automatically. If the new process fails to start, the old process resumes — automatic rollback, zero downtime.

Parse errors log a warning and keep the current configuration — a typo in the config file never takes down the proxy.

Smart extension diagnostics

At startup, Gold Lapel checks which PostgreSQL extensions are available and tells you exactly what to do if any are missing — with copy-paste CLI commands, not documentation links.

The startup summary logs installed vs. missing extensions with their optimization impact.

Management connection idle timeout

By default, Gold Lapel disconnects its management connection after 60 seconds of inactivity and reconnects transparently on the next query (~100ms). This keeps serverless Postgres hosts like Neon, Supabase, and Aurora Serverless from billing for idle connections.

For most deployments, we recommend setting mgmt_idle_timeout_secs = 0 to keep the connection always-on — it eliminates the brief reconnection overhead entirely. Only leave the timeout in place if your Postgres host charges for idle connections.

Table exclusion

Tell Gold Lapel to leave specific tables alone — useful for tables with sensitive data, high-churn tables, or anything you'd rather manage manually.

The --exclude-tables flag (also available as an env var and TOML setting) defines tables Gold Lapel should never optimize. Patterns touching any excluded table skip matview creation, index creation, and query rewriting entirely. Case-insensitive matching. Live-reloadable — add or remove tables in the config and changes take effect automatically.

Database objects

Everything Gold Lapel creates lives in its own schema — clean separation from your application's tables, easy to inspect, safe to drop.

_goldlapel.*   -- all Gold Lapel objects live in a dedicated schema

All objects are safe to drop — Gold Lapel recreates what it needs on startup from its persistent registry. The management connection user needs CREATE privileges on the target database.

Persistent state

Gold Lapel remembers what it learned between restarts — pattern statistics, strategy counters, and optimization decisions persist to disk so the proxy doesn't start from scratch.

State persists to disk. On restart, Gold Lapel seeds from the state file immediately — it can evaluate matviews without re-observing all patterns. Atomic writes prevent corruption. Missing or corrupt state files are warned and ignored.

Robustness

Gold Lapel is designed to never make things worse. If an optimization fails, the proxy falls back to the original query transparently — your application never sees an error that wouldn't have happened without Gold Lapel.

  • DDL circuit breaker — permanently invalid matview SQL stops retrying after consecutive database errors
  • Management connection auto-reconnect — automatic reconnection on connection loss
  • Transparent fallback — stale or missing matviews fall back to the original query
  • Rewrite error recovery — if a rewritten query fails, Gold Lapel falls back to the original SQL