Rails + ActiveRecord

Auto-patches ActiveRecord's PostgreSQL adapter. Add the gem — Gold Lapel starts on first connection with zero config.

Install

# Gemfile
gem "goldlapel"

# Rails support is built in — just require it from an initializer:
# config/initializers/goldlapel.rb
require "goldlapel/rails"

Then bundle install. That's it — your existing config/database.yml works unchanged and every ActiveRecord model, migration, and Active Record query routes through Gold Lapel.

Usage

There is no usage step. goldlapel/rails auto-patches ActiveRecord's PostgreSQL adapter at boot. When Rails opens its first database connection, Gold Lapel starts automatically and proxies all queries. The L1 native cache activates automatically — repeated reads serve in microseconds. Your existing ActiveRecord models, scopes, includes, migrations, and raw connection.execute calls stay exactly as they are.

Configuration

Optional — pass Gold Lapel options under a goldlapel key in config/database.yml:

# config/database.yml
production:
  adapter: postgresql
  host: db.example.com
  database: mydb
  username: user
  password: pass
  goldlapel:
    port: 9000
    config:
      mode: waiter
      pool_size: 50
    extra_args:
      - "--threshold-duration-ms"
      - "200"

The config hash takes the same keys as GoldLapel.start(config:) — see the configuration reference for every setting.

Multiple Databases

Rails multi-database support works out of the box. Each database gets its own proxy — just assign a unique port to each:

production:
  primary:
    adapter: postgresql
    host: primary-db.example.com
    database: myapp
    goldlapel:
      port: 7932
  analytics:
    adapter: postgresql
    host: analytics-db.example.com
    database: analytics
    goldlapel:
      port: 7942

Read replicas, multi-tenant shards, and the connected_to switching API all continue to work — each connection has its own Gold Lapel instance.

Advanced Tuning

Use extra_args to pass any Gold Lapel CLI flag. You can also set GOLDLAPEL_* environment variables — the proxy inherits the full process environment. The configuration reference covers every available setting.

Requirements

• Ruby 3.2+
• Rails 7.0+
• goldlapel gem 0.2+
• PostgreSQL (TCP connections only)

Upgrading from v0.1

The Rails integration is unchanged at the surface — install the gem, require "goldlapel/rails", and point database.yml at Postgres as before. The v0.2 changes are internal: the adapter now calls the new GoldLapel.start_proxy factory (a URL-only variant of GoldLapel.start, because Rails manages its own ActiveRecord connection pool and only needs the proxy).

# v0.1.x (old) — same install, same database.yml
gem "goldlapel"
require "goldlapel/rails"

# v0.2 (new) — identical from Rails' perspective
gem "goldlapel"
require "goldlapel/rails"
# Internally the adapter now calls the new GoldLapel.start_proxy factory

• Install command unchanged — gem "goldlapel" in your Gemfile.
• require "goldlapel/rails" unchanged.
• database.yml schema unchanged — existing port / extra_args keys still work. config: is the newly exposed full-config passthrough.
• If you also use GoldLapel.start directly outside Rails, see the Ruby guide for the v0.2 factory shape.

How It Works

On first connection, goldlapel/rails:

1. Reads your connection params from database.yml (host, port, user, password, database)
2. Calls GoldLapel.start_proxy pointed at your database — Rails owns its own pg connection pool, so only the proxy is spawned
3. Rewrites the adapter's host and port to 127.0.0.1:<proxy-port> and wraps the raw pg connection with the L1 native cache

On reconnect (after a timeout, deploy, or connection pool reset), the proxy is already running — the connection rewires immediately with no startup cost.

GitHub · RubyGems