Quickstart Checklist

Most items below are gradual enhancements to get the most out of Gold Lapel and operate it as it was designed. We highlight a few settings at the top that deserve a moment of your review.

Before You Begin

Write detection. If anything writes to your database outside the proxy — migrations, cron jobs, direct psql sessions — set wal_level = logical in postgresql.conf (or run ALTER SYSTEM SET wal_level = 'logical' and restart). Without it, the cache won't know about those writes. You can always clear the cache manually from the dashboard.
Serverless users. GL auto-detects your provider and sets a connection timeout to avoid idle charges. If you've persisted the connection by setting mgmt_idle_timeout_secs = 0, always-on connections may incur charges with your provider.
Passthrough mode. Need to pause optimizations? Set mode = "bellhop" in goldlapel.toml or toggle it from the dashboard. Traffic flows through on monitor-only mode. Switch back anytime.

1. Extensions

Six extensions unlock additional optimization strategies. All ship with PostgreSQL or are widely available on managed providers.

Extension	What it enables	How to install
`pg_trgm`	LIKE/ILIKE index acceleration	Ships with PostgreSQL
`fuzzystrmatch`	Phonetic search (soundex, dmetaphone)	Ships with PostgreSQL
`pgvector`	Vector similarity search (HNSW indexes)	Install pgvector, then create extension
`pg_ivm`	Zero-staleness matview refresh	Build from source, add to `shared_preload_libraries`, restart
`pg_stat_statements`	Instant optimization from query history	Add to `shared_preload_libraries`, restart
`citus`	Distributed search across nodes	Install Citus, then create extension

pg_trgm

CREATE EXTENSION IF NOT EXISTS pg_trgm;

fuzzystrmatch

CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;

pgvector

-- Install pgvector on your server first, then:
CREATE EXTENSION IF NOT EXISTS vector;

pg_ivm

-- Build/install pg_ivm, add to shared_preload_libraries, restart, then:
CREATE EXTENSION IF NOT EXISTS pg_ivm;

pg_stat_statements

-- Add to shared_preload_libraries, restart, then:
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

citus

-- Install Citus, then:
CREATE EXTENSION IF NOT EXISTS citus;

GL auto-creates extensions on startup if it has sufficient permissions. If it cannot, it logs the command you would need to run yourself. Full details in the Extensions guide.

2. PostgreSQL Configuration

Two settings require changes to postgresql.conf. Both require a restart.

Setting	Value	Why	Restart?
`shared_preload_libraries`	`'pg_ivm, pg_stat_statements'`	Required for these extensions to load	Yes
`wal_level`	`logical`	WAL-based write detection catches all writes, not just those through GL	Yes

shared_preload_libraries

# postgresql.conf
shared_preload_libraries = 'pg_ivm, pg_stat_statements'

wal_level

# postgresql.conf
wal_level = logical

Without wal_level = logical, GL detects writes by parsing SQL at the proxy layer. This catches writes that flow through GL but cannot see writes from migration scripts, cron jobs, admin psql sessions, or PL/pgSQL functions that modify data internally. With logical WAL decoding, every write triggers cache invalidation regardless of source. See WAL Configuration for provider-specific notes.

3. Serverless Providers

Running on Neon, Supabase, Aurora Serverless, or another serverless Postgres provider? GL auto-detects the provider at startup and adjusts settings accordingly. No configuration required. If you've persisted the connection by setting mgmt_idle_timeout_secs = 0, always-on connections may incur charges with your provider.

What gets adjusted

Pool size — reduced to respect the provider's connection limits. Supabase Supavisor and Neon's pooler are recognized and GL disables its own pool to avoid stacking.
Refresh interval — increased slightly to reduce load on metered compute. Cold starts cost money on serverless, so GL spaces out matview refreshes.
Management connection — idle timeout enabled by default (disconnects after 60s of inactivity) so you are not paying for idle connections.

You can override any auto-adjusted setting explicitly. An explicit --pool-size flag or config value always wins over auto-detection. GL logs every adjustment and its reason at startup.

4. What's Optional

All of it.

Gold Lapel creates matviews, detects N+1 queries, manages connection pools, and caches results with nothing but a connection string. Every item on this page makes it better at a specific job — faster index creation, fresher matviews, broader write detection — but none of them are prerequisites.

Zero config Matviews, N+1 detection, connection pooling, result caching

+ pg_stat_statements Skip the warm-up period. GL optimizes your hottest queries on first startup.

+ pg_trgm LIKE '%search%' queries get trigram indexes instead of sequential scans.

+ fuzzystrmatch Phonetic searches (soundex, dmetaphone) get expression indexes.

+ pgvector Vector similarity queries get HNSW indexes for approximate nearest neighbor.

+ pg_ivm Matviews update on every write. Zero staleness, zero polling delay.

+ wal_level = logical Every write to the database triggers cache invalidation, even bypassing GL.

Start with nothing. Add extensions as you see fit. Each one lights up a new capability in your GL dashboard.