Rails

Gold Lapel ships Rails support inside the Ruby wrapper — no separate plugin to install. Add the gem, require the Railtie, and the PostgreSQL adapter is patched on first connection.

Install

gem install goldlapel

Or add gem "goldlapel" to your Gemfile and bundle install. Rails support lives inside the goldlapel gem at goldlapel/rails.

Wire the Railtie

Drop a one-line initializer:

# config/initializers/goldlapel.rb
require "goldlapel/rails"

That is the entire setup. Your existing config/database.yml works unchanged. When Rails opens its first database connection, Gold Lapel starts and patches ActiveRecord's PostgreSQL adapter. The L1 native cache activates with it — repeated reads serve in microseconds. Models, scopes, includes, migrations, and raw connection.execute calls all flow through unchanged.

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 accepts the same keys as GoldLapel.start(config:) — see the configuration reference for every setting.

Multiple databases

Rails multi-database support carries straight through. Assign each database its own port:

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 carries its own Gold Lapel instance.

Tuning

extra_args passes any Gold Lapel CLI flag through to the proxy. GOLDLAPEL_* environment variables are honoured as well — 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)

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 against your database — Rails manages 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 pool reset), the proxy is already running — the connection rewires immediately with no startup cost.

For the underlying Ruby wrapper API — GoldLapel.start, async support, and the wrapper methods — see the Ruby guide.

GitHub · RubyGems