migrate

package
v0.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: AGPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package migrate applies a service's PostgreSQL schema migrations from an embedded fs.FS of .sql files (github.com/jackc/tern/v2/migrate's own file format and layout — see its docs for how to name and write them), coordinating concurrent instances via a PostgreSQL advisory lock.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run

func Run(ctx context.Context, pool *pgxpool.Pool, fsys fs.FS, versionTable string) error

Run applies every pending migration in fsys to the database reachable through pool, holding tern's session-level PostgreSQL advisory lock (see ternLockNum) for the duration.

That lock is the whole point: several instances of the same service can start simultaneously against a freshly created, empty database. Without coordination they would all see "no migrations applied yet" and race to apply the same one, which — depending on timing — either errors (a duplicate CREATE TABLE / duplicate version-row insert) or, worse, runs a migration's statements twice. With the lock, exactly one instance acquires it and actually migrates; every other instance polls pg_try_advisory_lock until the first releases, then runs Migrate itself, finds nothing pending, and returns immediately having applied nothing. An already-current schema behaves identically: Migrate is a no-op.

The lock is taken before tern is constructed and held until Run returns, so it covers everything Run does: reading the version, applying migrations and the invalid-index check. Because tern's lock number is global to the database, it already serialises every service sharing it; a second, per-service lock would add nothing, so Run takes none.

The lock is taken on a single dedicated connection acquired from pool (advisory locks are session-scoped: the exact same connection that took the lock must be the one that releases it, which a pool cannot guarantee across two separate calls) and is always released before Run returns, success or failure.

versionTable is tern's schema-version bookkeeping table (e.g. "public.auth_schema_version") and is REQUIRED: Run returns an error for "". There is deliberately no shared default. In the single-database topology every service migrates the same database, and a default table would be ONE version row shared by all of them, so the first service to migrate would make every other one believe its schema was already current (or fail on a version it has never heard of). Each service must name its own table.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL