goldlapel 0.1.0rc25

Self-optimizing Postgres proxy — automatic materialized views and indexes

Gold Lapel

Self-optimizing Postgres proxy — automatic materialized views and indexes, with an L1 native cache that serves repeated reads in microseconds. Zero code changes required.

Gold Lapel sits between your app and Postgres, watches query patterns, and automatically creates materialized views and indexes to make your database faster. Port 7932 (79 = atomic number for gold, 32 from Postgres).

Install

pip install goldlapel
# or
uv pip install goldlapel

Quick Start

import goldlapel

# Create a proxy instance and start it
gl = goldlapel.GoldLapel("postgresql://user:pass@localhost:5432/mydb")
gl.start()

# Use the proxy connection directly — no driver setup needed
result = gl.execute("SELECT * FROM users WHERE id = $1", [42])

For async applications:

import goldlapel

gl = goldlapel.GoldLapel("postgresql://user:pass@localhost:5432/mydb")
await gl.start_async()

result = await gl.fetch("SELECT * FROM users WHERE id = $1", 42)

Gold Lapel prints the proxy and dashboard URLs on startup. Access the dashboard programmatically:

gl.dashboard_url()  # http://127.0.0.1:7933

API

goldlapel.GoldLapel(upstream, config=None, port=None, extra_args=None)

Creates a Gold Lapel proxy instance.

• upstream — your Postgres connection string (e.g. postgresql://user:pass@localhost:5432/mydb)
• config — dict of configuration options (see Configuration)
• port — proxy port (default: 7932)
• extra_args — additional CLI flags passed to the binary (e.g. ["--threshold-impact", "5000"])

gl.start()

Starts the proxy. Returns the instance for chaining.

gl.start_async()

Async version of start().

gl.stop()

Stops the proxy. Also called automatically on process exit.

gl.proxy_url()

Returns the current proxy URL, or None if not running.

gl.dashboard_url()

Returns the dashboard URL (e.g. http://127.0.0.1:7933), or None if the proxy is not running or the dashboard is disabled.

goldlapel.config_keys()

Returns the set of all valid config key names.

Configuration

Pass a config dict to the constructor to configure the proxy:

import goldlapel

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

Keys use snake_case and map directly to CLI flags (pool_size → --pool-size). Boolean keys like disable_matviews are flags — True enables them, False (or omitting) leaves them off. List keys like replica accept arrays and produce repeated flags.

Unknown keys raise ValueError immediately. To see all valid keys:

import goldlapel
print(goldlapel.config_keys())

For the full configuration reference, see the main documentation.

You can also set environment variables (GOLDLAPEL_PROXY_PORT, GOLDLAPEL_UPSTREAM, etc.) — the binary reads them automatically.

How It Works

This package bundles the Gold Lapel Rust binary for your platform. When you call start(), it:

1. Locates the binary (bundled in package, on PATH, or via GOLDLAPEL_BINARY env var)
2. Spawns it as a subprocess listening on localhost
3. Waits for the port to be ready
4. Returns a database connection with L1 native cache built in
5. Cleans up automatically on process exit

The binary does all the work — this wrapper just manages its lifecycle.

Links

• Website
• Documentation