Upgrading

v0.2 is a breaking redesign. Read the migration notes before upgrading.

Heads up — v0.2 is a breaking change from v0.1.

The wrappers were redesigned to be driver-agnostic: goldlapel.start(url) is now a factory that spawns the proxy and returns a GoldLapel instance. You bring your own Postgres driver and point it at gl.url. The old class-based GoldLapel(url).start() pattern no longer exists. See Migrating from v0.1 to v0.2 below for per-language before/after code.

The npm package was renamed from the scoped @goldlapel/goldlapel to the unscoped goldlapel.
JS install now expects you to install a Postgres driver peer (pg, postgres, or @vercel/postgres) alongside goldlapel.
Python dropped the [django] and [sqlalchemy] install extras — install those packages with regular pip; the glue always ships inside goldlapel.
Python and Ruby gained native async submodules (goldlapel.asyncio.start, GoldLapel::Async.start).

How to upgrade

Run the upgrade command for your language wrapper. The Rust binary ships inside the wrapper package, so a single command upgrades everything.

Python

pip install --upgrade goldlapel

JavaScript

npm install goldlapel@latest
# Plus your Postgres driver of choice:
# npm install pg       # or: postgres, @vercel/postgres

Ruby

gem update goldlapel

go get -u github.com/goldlapel/goldlapel-go

Java (pom.xml)

<!-- pom.xml — use the latest published v0.2 version -->
<dependency>
    <groupId>com.goldlapel</groupId>
    <artifactId>goldlapel</artifactId>
    <version>0.2.0</version>
</dependency>

PHP

composer require goldlapel/goldlapel:^0.2

.NET

dotnet add package GoldLapel --version latest

Standalone (Homebrew)

brew upgrade goldlapel

You can also download the latest binary directly from the platform pages.

Migrating from v0.1 to v0.2

The wrappers were redesigned around a factory API: goldlapel.start(url) spawns the proxy and returns a GoldLapel instance. You then connect your own Postgres driver to gl.url. The class-based GoldLapel(url).start() pattern, the bundled driver, and the framework-specific install extras are all gone.

Python

Replace the GoldLapel class with the goldlapel.start factory and bring your own driver (psycopg2, psycopg3, asyncpg — any Postgres driver works against gl.url):

Python

# v0.1 (old) — class constructor, start() returns a connection
import goldlapel
gl = goldlapel.GoldLapel("postgresql://...")
conn = gl.start()
conn.execute("SELECT 1")
gl.stop()

# v0.2 (new) — factory, bring your own driver, point it at gl.url
import goldlapel
import psycopg2

gl = goldlapel.start("postgresql://...")
conn = psycopg2.connect(gl.url)
conn.cursor().execute("SELECT 1")
gl.stop()

# v0.2 async — new goldlapel.asyncio submodule
from goldlapel.asyncio import start
gl = await start("postgresql://...")

If you were using pip install goldlapel[django] or pip install goldlapel[sqlalchemy], install the framework package separately — the integration glue always ships inside goldlapel:

Python install extras

# v0.1 (old) — install extras bundled framework glue
pip install goldlapel[django]
pip install goldlapel[sqlalchemy]

# v0.2 (new) — install the framework package separately; glue always ships
pip install goldlapel django
pip install goldlapel sqlalchemy

JavaScript / Node

The npm package was renamed from @goldlapel/goldlapel to plain goldlapel. Postgres drivers moved to peer dependencies — install pg (most common), postgres, or @vercel/postgres alongside goldlapel:

JavaScript

// v0.1 (old) — scoped package, class constructor + start()
import { GoldLapel } from '@goldlapel/goldlapel';
const gl = new GoldLapel(url);
await gl.start();
await gl.client.query('SELECT 1');
await gl.stop();

// v0.2 (new) — unscoped package, factory, bring your own driver
import * as goldlapel from 'goldlapel';
import pg from 'pg';

const gl = await goldlapel.start(url);
const client = new pg.Client({ connectionString: gl.url });
await client.connect();
await client.query('SELECT 1');
await gl.stop();

Ruby

Replace GoldLapel.new(url).start with the GoldLapel.start(url) factory. Sync code uses pg or any Ruby Postgres driver against gl.url; native async is available via GoldLapel::Async.start:

Ruby

# v0.1 (old) — class constructor, start returns a connection
gl = GoldLapel.new("postgresql://...")
conn = gl.start
conn.exec("SELECT 1")
gl.stop

# v0.2 (new) — factory, bring your own driver
require "pg"
gl = GoldLapel.start("postgresql://...")
conn = PG.connect(gl.url)
conn.exec("SELECT 1")
gl.stop

# v0.2 async — new GoldLapel::Async factory
gl = GoldLapel::Async.start("postgresql://...")

Java

The class constructor is replaced by the static GoldLapel.start(url, opts -> ...) factory. The returned instance implements AutoCloseable, so use try-with-resources. Build your JDBC Connection against gl.getJdbcUrl():

Java

// v0.1 (old) — constructor + start()/stop() returned a Connection
GoldLapel gl = new GoldLapel("postgresql://...");
Connection conn = gl.start();
conn.createStatement().executeQuery("SELECT 1");
gl.stop();

// v0.2 (new) — static factory, bring your own JDBC driver via gl.getJdbcUrl()
try (GoldLapel gl = GoldLapel.start("postgresql://...", opts -> opts.setPort(7932))) {
    Properties props = new Properties();
    props.setProperty("user", gl.getJdbcUser());
    props.setProperty("password", gl.getJdbcPassword());
    Connection conn = DriverManager.getConnection(gl.getJdbcUrl(), props);
    conn.createStatement().executeQuery("SELECT 1");
}

Go

The New + Start pair collapses into a single Start(ctx, url, opts...) factory that returns a *GoldLapel. Bring your own driver (pgx is recommended) and open a *sql.DB against gl.URL():

// v0.1 (old) — constructor + Start returned a *sql.DB
gl := goldlapel.New("postgresql://...")
db, err := gl.Start()
defer gl.Stop()
_, _ = db.Query("SELECT 1")

// v0.2 (new) — factory takes ctx + options, bring your own driver
import _ "github.com/jackc/pgx/v5/stdlib"

ctx := context.Background()
gl, err := goldlapel.Start(ctx, "postgresql://...",
    goldlapel.WithPort(7932),
)
defer gl.Close()

db, _ := sql.Open("pgx", gl.URL())
_, _ = db.QueryContext(ctx, "SELECT 1")

PHP

Replace the new GoldLapel($url)->start() pattern with the static GoldLapel::start($url) factory. Then connect pg_connect or any PHP Postgres driver to $gl->url:

PHP

// v0.1 (old) — class constructor + start()
$gl = new GoldLapel("postgresql://...");
$conn = $gl->start();
$conn->query("SELECT 1");
$gl->stop();

// v0.2 (new) — static factory, bring your own driver
$gl = GoldLapel::start("postgresql://...");
$conn = pg_connect($gl->url);
pg_query($conn, "SELECT 1");
$gl->stop();

.NET

The synchronous new GoldLapel(url).Start() constructor pair is replaced by the async GoldLapel.StartAsync(url, opts) factory. Build your NpgsqlConnection against gl.Url:

.NET

// v0.1 (old) — constructor + synchronous Start
using var gl = new GoldLapel("postgresql://...");
var conn = gl.Start();
using var cmd = new NpgsqlCommand("SELECT 1", conn);

// v0.2 (new) — async factory + bring-your-own Npgsql connection
await using var gl = await GoldLapel.StartAsync(
    "postgresql://...",
    opts => opts.Port = 7932);

await using var conn = new NpgsqlConnection(gl.Url);
await conn.OpenAsync();
await using var cmd = new NpgsqlCommand("SELECT 1", conn);
await cmd.ExecuteScalarAsync();

Document-store tables — v0.1 → v0.2 schema

If you used Gold Lapel's document-store wrapper methods (docInsert, docFind, etc.) in v0.1, the collection tables were created with id BIGSERIAL primary keys. v0.2 switched to _id UUID to make collections readable and writable across all language wrappers against the same Postgres. Run this one-shot migration per existing doc table:

SQL

-- Migrate a v0.1 document-store table to the v0.2 schema.
-- v0.1 used BIGSERIAL primary keys; v0.2 uses UUIDs for cross-wrapper interop.
-- Ensure pgcrypto is installed first for gen_random_uuid():
--     CREATE EXTENSION IF NOT EXISTS pgcrypto;
ALTER TABLE <table> ADD COLUMN _id UUID DEFAULT gen_random_uuid();
UPDATE <table> SET _id = gen_random_uuid() WHERE _id IS NULL;
ALTER TABLE <table> ALTER COLUMN _id SET NOT NULL;
ALTER TABLE <table> DROP CONSTRAINT <table>_pkey;
ALTER TABLE <table> ADD PRIMARY KEY (_id);
ALTER TABLE <table> DROP COLUMN id;

New tables created by any v0.2 wrapper use the UUID schema automatically — this migration is only needed for tables that already exist from v0.1.

What happens during an upgrade

Upgrading Gold Lapel is straightforward. Stop the old process, start the new one. There is no migration step and no downtime ceremony at the database layer.

No downtime required. Stop the old process, start the new one. Your application reconnects automatically.
Materialized views and indexes are preserved. They live in the _goldlapel schema inside PostgreSQL, not in the proxy. The new version picks them up on startup.
Configuration carries forward. Your goldlapel.toml is unchanged. New settings use sensible defaults until you choose to configure them.
The dashboard confirms the upgrade. The Overview tab shows the running version. If a newer version is available, an upgrade banner appears with the correct command for your package manager.
Application code may need updating (v0.1 → v0.2 only). See the migration section above.

Version history

Gold Lapel is in active development. The v0.2 line is the current supported series. We publish release candidates as the feature set stabilizes toward a 1.0 release.

A full changelog will be published alongside the 1.0 release. In the meantime, the dashboard's upgrade banner includes a summary of what changed in each new version.

Rolling back

If you need to return to a previous version, the process is the same in reverse: stop the current process and install the older version. If you roll back across the v0.1 ↔ v0.2 boundary, your application code needs to match the version you install — v0.1 used the class-based GoldLapel(url).start() pattern, v0.2 uses the goldlapel.start(url) factory.

Rolling back to v0.1 uses the original scoped npm name, since that is what v0.1 actually shipped as:

Python (to v0.1)

pip install goldlapel==0.1.0-rc16

JavaScript (to v0.1 — scoped name)

npm install @goldlapel/goldlapel@0.1.0-rc16

Standalone (Homebrew, to v0.1)

brew install goldlapel@0.1.0-rc16

There are no database migrations to reverse. Gold Lapel does not modify your schema. The materialized views and indexes it creates are additive, managed entirely within the _goldlapel schema, and compatible across versions.