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

npm install @goldlapel/goldlapel

Quick Start

import goldlapel from '@goldlapel/goldlapel';

// Start the proxy — returns a database connection with L1 cache built in
const conn = goldlapel.start('postgresql://user:pass@localhost:5432/mydb');

// Use the connection directly — no driver setup needed
const result = conn.query('SELECT * FROM users WHERE id = $1', [42]);

After startup, Gold Lapel prints a one-line summary and serves a dashboard at http://127.0.0.1:7933 by default:

const dashUrl = goldlapel.dashboardUrl();
// => "http://127.0.0.1:7933" (or null if not running / dashboard disabled)

API

goldlapel.start(upstream, opts)

Starts the Gold Lapel proxy and returns a database connection with L1 cache.

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

goldlapel.stop()

Stops the proxy. Also called automatically on process exit.

goldlapel.proxyUrl()

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

goldlapel.dashboardUrl()

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

new goldlapel.GoldLapel(upstream, opts)

Class interface for managing multiple instances:

import { GoldLapel } from '@goldlapel/goldlapel';

const proxy = new GoldLapel('postgresql://user:pass@localhost:5432/mydb', { port: 7932 });
const conn = await proxy.start();
// ...
proxy.stop();

Configuration

Pass a config object to configure the proxy:

import goldlapel from '@goldlapel/goldlapel'

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

Keys use camelCase and map to CLI flags (poolSize → --pool-size). Boolean keys are flags — true enables them. Array keys produce repeated flags.

Unknown keys throw immediately. To see all valid keys:

import { configKeys } from '@goldlapel/goldlapel'
console.log(configKeys())

For the full configuration reference, see the main documentation.

Raw CLI flags

You can also pass raw CLI flags via extraArgs:

const conn = await goldlapel.start(
    'postgresql://user:pass@localhost:5432/mydb',
    { extraArgs: ['--threshold-duration-ms', '200', '--refresh-interval-secs', '30'] }
);

Or 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