Supabase and PostgresMigrations and upgradesreference
pgmig, logical-replication migration scope and gates
pgmig is a Postgres-to-Postgres migrator built on native logical
replication1, published at
github.com/erfianugrah/pgmig.2
It creates a publication on the source, a subscription on the target, streams the
initial copy and the ongoing changes, checksums the two sides, and stops the world
for the few seconds it takes to drain lag, resync sequences, and drop the
subscription.3 This page is the reference for the tool’s own
decisions: what the replication carries, what the schema pre-step has to restore
first, where the cutover gates sit, how the reconcile proves the copy, and what
the separate pg_upgrade rehearsal lab does.
The two task-sequenced guides are the implementation of this page: moving a project to another region runs the pipeline cross-region,4 and upgrading to a new Postgres major version runs it into a new PG 17 project or rehearses the upgrade in the lab.5
Naming: the tool is pgmig now, was sbshift until 2026-09-28, and was pgshift
before the 2026-07-03 rename recorded in CHANGELOG.md. Older notes that say
either name are the same program.
Provenance: this page describes documented behaviour - the repository’s README.md,
docs/RUNBOOK.md, docs/MIGRATION-SCOPE.md, CHANGELOG.md and src/cli.ts at
commit ba5f88c - plus the
live cross-region measurements published in the two companion guides and their
supabase-lab modules (W05, W09, W14, W15). The Supabase statement_timeout caution
and the Postgres 15 to 17 section come
from pgmig’s live runs on 2026-11-09 and the fix that followed them, at a later
commit than ba5f88c.6 The sections on
several new projects subscribing to one source,
a source with network restrictions on
and a source with the IPv4 add-on
come from supabase-lab replica-routing RR10 to RR13 (2026-11-10 and 2026-11-11),
which created subscriptions with plain SQL rather than through pgmig. Nothing else here
was re-run for this page; the evidence table at the end splits documented from
measured.
TL;DR
- Logical replication carries table rows and nothing else. No DDL, no roles,
no extensions, no sequences, no
auth/storageschemas. The schema pre-step (bootstrap) restores the first three; the rest is a documented hand-off (RUNBOOK section 6). - An FK into
auth.usersdoes not block the copy. Replicated rows skip FK checks on the subscriber (the apply and initial-copy workers run withsession_replication_role = replica). The app needs the referenced auth rows before it writes to the target, socutover --with-auth-datareloads them from the source inside the write stop. cutover --with-auth-datareloads the auth rows inside the write stop. After the lag drain and sequence resync it dumps the source’sauthrows (auth.schema_migrationsexcluded), empties the target’s auth tables and loads them in one transaction undersession_replication_role = replica. A failed reload commits nothing and leaves the subscription for a re-run. Auth rows written betweenbootstrapand cutover were lost in earlier versions.- Sequences do not replicate, so
cutoversetval()s every owned sequence from the write-stopped source. Without it the next serial or IDENTITY insert collides with a replicated primary key. It is a no-op on uuid and text keys. - The gates are a lag drain to zero and a clean chunked checksum, both on a
quiescent source.
watchaborts on WAL bloat or a lost slot on its own; the lag gate refuses to close if writes are still arriving. - From a Supabase source, the subscription connection needs
statement_timeout=0. Thepostgresrole is capped at 2 min, the target’s tablesync worker runs the initial COPY outside pgmig’s pinned settings, and a table whose copy takes longer restarts forever. pgmig has added the option itself since 2026-11-09; any other subscriber needs it added by hand. - At 3.65 GB from Postgres 15 to 17, pgmig’s cutover took 1.6 s with no writer running (measured 2026-11-09). The copy took 196.9 s and reconciled identical. The in-place upgrade at the same size lost 52 of 691 acknowledged probe writes sent during it, so writes have to stop for its whole run.
- New Postgres 17 projects subscribing to one source at the same time can
collide on a table-sync slot name. 24 of 26 new 17.11 projects shared one
system_identifier, and 3 of 3 concurrent pairs with matching slot names left one target’s table infat the end of its wait bound (40 minutes in RR10, 10 in RR11) with the source’s row count while every call succeeded (supabase-lab RR10 and RR11, 2026-11-10). Subscribe new targets one at a time, each after every earlier target has every tabler, and readpg_subscription_relon each rather than row counts. - Repointing the app is the point of no return; cutover can be rolled back. Before
it,
teardownplus re-enabled source writes is lossless. After it, rollback loses every write the target took unless reverse replication was set up first. pg_upgraderehearsal is a separate workflow. It needs nomigrate.config.yamland no billable project: it captures the source, times a realpg_upgrade --linkin Docker, and proves the result identical with the same checksum enginereconcileuses.
Topology
Section titled “Topology”Text fallback, the same pipeline in order:
bootstraprestores roles, extensions and schema onto the target, and with--with-auth-dataa testing snapshot of theauthrows (cutover --with-auth-datareloads them inside the write stop).replicatecreates the publication, the slot and the subscription (copy_data=true), so the initial copy starts against a schema that already exists.watchpolls until every table issrsubstate='r'and aborts if the slot or the WAL watchdog trips.- The app stops writing to the source.
reconcilechecksums both sides;cutoverdrains lag, resyncs sequences and, with--with-auth-data, reloads the auth rows, then drops the subscription.- The app is repointed at the target. The source is never written to again.
Which move is this
Section titled “Which move is this”| Move | Downtime | Reconfiguration after | Pick when |
|---|---|---|---|
| Logical replication (pgmig) | the lag drain, seconds | new project: new ref, new API keys, new JWT secret, the whole non-data surface | the downtime budget is smaller than a dump-and-restore window, or the move doubles as a region change |
| Dump and restore | the copy time | same new-project list | the database is small, or the pipeline is not worth rehearsing |
| Supabase clone (Restore to a new project) | the restore window | same new-project list, minus storage bytes | rehearsal, not a migration - the clone is a copy of a backup |
pg_upgrade rehearsal lab | n/a - rehearsal only | n/a | you want the blocker audit and a downtime estimate without creating a billable project |
Logical replication is the only one of the four that needs the target to exist with a loadable schema before the copy starts, which is why the pre-step is a first-class command rather than a suggestion.
What replicates, and what the pre-step carries
Section titled “What replicates, and what the pre-step carries”| Artifact | Carrier | Note |
|---|---|---|
| Table rows and the changes to them | replicate + watch | the only thing logical replication carries |
| Schema: tables, views, functions, triggers, RLS policies | bootstrap | pre-step; for a Supabase source it excludes the roughly 27 managed schemas and filters the cluster-level objects a plain dump still emits |
| Roles and permissions | bootstrap | pg_dumpall --roles-only --no-role-passwords, so custom LOGIN roles arrive without passwords |
| Extensions | bootstrap | enabled on the target before the schema load; doctor diffs the two sides and prints the CREATE EXTENSION statements still missing |
auth row data | cutover --with-auth-data (inside the write stop), or a manual dump/restore | bootstrap --with-auth-data copies a snapshot for testing only; cutover --with-auth-data reloads the source’s final auth state. auth.schema_migrations is excluded because the target carries its own ledger |
| Sequences | schema DDL for the object, cutover for the value | values do not replicate; a no-op for uuid and text primary keys |
Generated columns (for example a STORED tsvector) | recomputed on the subscriber | excluded from the reconcile hash, because hashing them reports a mismatch that is not one |
| Project config, integration secrets, billable infra, Edge Functions, storage objects | config-sync, provision, functions, storage | a separate surface from the data plane; the JWT signing secret and API keys are never copied |
| Org settings, org members and roles, entitlements | nothing | read-only on the Management API; the only org-level action is claiming a project into another org |
| Read replicas, custom domains, realtime publications, custom role passwords | hand work | no clean API path; recreate or re-enter after cutover |
The exhaustive version of this table, including every dashboard surface and its
API endpoint, is the repository’s MIGRATION-SCOPE.md.7
The pipeline
Section titled “The pipeline”| Command | What it does | Gate behaviour |
|---|---|---|
doctor | Readiness report: connection shape, versions, wal_level, replica identity, extension diff, cross-schema FKs, foreign slots, SQL-level GUC overrides, and (Supabase source, valid access token) the source’s network restrictions against the target’s outbound address | read-only; --source-only for before the target exists |
bootstrap | Target preparation: extensions, roles, schema, optionally auth rows | preview by default; --confirm mutates |
preflight | Hard-gate checks: CREATE SUBSCRIPTION grant, replication capacity, a replica identity on every published table | fails closed |
replicate | Empty publication plus ADD TABLE (never FOR ALL TABLES, which needs superuser), slot, subscription with copy_data=true. Refuses service-owned tables (auth, storage, realtime, supabase_functions, supabase_migrations, vault) and refuses to start while another subscription’s initial-copy slot is on the source | re-running issues REFRESH PUBLICATION for a newly added table |
watch | Polls pg_subscription_rel until every table is r, with live copy percentage | aborts on retained WAL over the watchdog threshold or slot wal_status='lost'; rising apply or sync error counts only log a warning, and the sync timeout (watchdog.syncTimeoutMin, 240 min by default) ends the wait |
reconcile | Chunked checksum, 256 buckets by default: one scan per side, bucket by primary-key hash, drill only the mismatched buckets | authoritative only after writes stop |
cutover | Samples WAL LSN twice, drains lag, setval()s every owned sequence. With --with-auth-data: dumps the source’s auth rows, empties and reloads the target’s auth tables in one transaction under session_replication_role = replica, then drops the subscription | refuses without the writes-stopped assertion on the autonomous path |
teardown | Drops subscription, slot, publication in that order | idempotent |
verify | Post-migration advisor health gate on the target | fails closed if the advisors are unreachable |
run chains the phases for automation: run --through reconcile --json exits 0
only if preflight, replicate, watch and reconcile all passed, and status --require-synced is the wait loop for a script that needs the copy ready.
The schema pre-step
Section titled “The schema pre-step”bootstrap is the answer to “logical replication carries rows only”.11
In order:
- Enable the non-default extensions the source has and the target lacks.
- Restore roles from a roles-only dump. Supabase’s reserved roles are filtered
out the same way
supabase db dump --role-onlyfilters them, so only your application roles are created - and they arrive with no passwords. - Restore the schema: DDL, RLS policies, functions, triggers.
- With
--with-auth-data, dump and restore theauthschema rows withsession_replication_role = replica. This is a testing snapshot: Auth keeps writing rows on the source afterwards (sign-ups, password changes, sessions and refresh tokens), andcutover --with-auth-dataempties the target’s auth tables and reloads them from the source’s final state inside the write stop, so the snapshot is replaced.auth.schema_migrationsis excluded: the managed target grants thepostgresrole SELECT only on it, and it has its own migration history.
The manual equivalent for a non-Supabase pair is a pg_dumpall --roles-only
plus a pg_dump --schema-only, restored with ON_ERROR_STOP=1, with any
cross-schema reference data loaded under session_replication_role = replica.
doctor gives you the same diff either way.
A part-way bootstrap can be recovered by running the auth-data dump and restore
commands it printed rather than re-applying the whole schema, because a re-run
re-plans the schema restore against tables that now exist. And any custom LOGIN
role reaches the target with rolpassword NULL, so every service using one needs
ALTER ROLE <name> WITH PASSWORD '...' before it is repointed.
Sequences, and why cutover resyncs them
Section titled “Sequences, and why cutover resyncs them”A sequence is schema, so the pre-step creates it on the target and carries the
value it held at dump time. Rows inserted on the source between bootstrap and
the write stop replicate with their explicit primary keys, which the sequence on
the target never sees. The first insert after cutover then picks a value the
sequence has already handed out, and the primary-key unique index rejects it.
cutover closes that gap by resynchronising every sequence owned by a replicated
column, using the write-stopped source as the authority. Serial and IDENTITY
columns are covered; uuid and text primary keys have no sequence to resync, so
the step is a no-op for them. The companion upgrade guide records the check that
proves it - an insert after cutover returns the next id rather than colliding.
The cutover gates
Section titled “The cutover gates”The tool owns the data-plane gates; your dashboards own the app-tier ones. Decide the app-tier numbers before the window, from a baseline.
| Phase | Data plane (the tool) | App tier (your dashboards) |
|---|---|---|
| Initial copy | retained WAL under watchdog.maxRetainedWalMb, slot active, wal_status still reserved or extended, apply and sync error counts flat | source CPU, disk IOPS and latency headroom; connections not near saturation |
| Reconcile | zero mismatched buckets | - |
| Lag drain | lag reaches 0 inside --max-lag-wait (300 s by default), the source WAL reads as quiescent | the app is confirmed read-only or down; no write retries still hitting the source |
| After the repoint | the cutover log shows a setval per sequence | target p95 and p99 within your margin of the baseline, error rate flat, pool not spiking on retries |
The hard stops, in the tool’s own words: watch aborts on retained WAL over the
threshold and immediately on wal_status='lost'; a lag drain that times out
means writes were not actually stopped, so do not proceed; any reconcile mismatch
means the cutover is not finished, whatever the lag says. Those are not advisory.
Never re-enable writes on the source after the repoint. Two databases accepting writes is split-brain, and nothing in the pipeline reconciles it.
Reconcile, and why the hash is comparable cross-region
Section titled “Reconcile, and why the hash is comparable cross-region”reconcile scans each side once, buckets rows by a hash of the primary key,
and compares bucket checksums. Only the buckets that differ are drilled, and the
report names the rows as missing_on_target, extra_on_target or hash_diff.
Full-table mode is available for small tables and is not the default because a
single aggregate scan of a real database is both slower and less specific about
where the difference is.
The comparison only works if both sides render the same row values the same way.
The row hash is taken over the row’s text form, which depends on TimeZone,
DateStyle, IntervalStyle, extra_float_digits and bytea_output. Every
connection in both pools therefore pins those settings identically and sets
statement_timeout = 0, so a cross-region run compares values and not two
machines’ display conventions.12 The subscription’s CONNECTION is
dialled by the target and belongs to neither pool, which is why it carries its own
statement_timeout=0 from a Supabase source (the caution under
the pipeline).
timestamptz comparisons are stable across regions, and a STORED generated column has to be excluded from the hash - the subscriber recomputes it, and hashing it would report a mismatch on every row that has one.
The pg_upgrade rehearsal lab
Section titled “The pg_upgrade rehearsal lab”This is a separate workflow from the migration pipeline. It needs no
migrate.config.yaml and no Supabase project, and it exists to put a number on
the in-place upgrade window before you take one. The underlying step is
pg_upgrade --link.13
| Step | Command | What it produces |
|---|---|---|
| Audit | upgrade doctor --to <version> | read-only readiness report: extensions deprecated on the target major, reg* columns referencing system OIDs, foreign replication slots, roles on md5 password storage, and a downtime estimate from the database size. Exit 1 on a hard blocker |
| Capture | upgrade capture --out-dir capture --max-gb <n> | roles, schema and data dumped locally with a manifest.json; refuses to capture past the size limit unless forced; --with-auth-data for a Supabase source |
| Lab | upgrade lab --capture-dir capture --runs 3 --keep | starts an old-version and a new-version container, snapshots the old data directory, runs pg_upgrade --link N times with a fresh snapshot per run, then ANALYZE, and prints the timings. --keep leaves both containers up for the verify step; --seed-gib inserts fixture data instead of real data; --prod-bytes extrapolates the production window |
| Verify | upgrade verify | pre-upgrade copy at SOURCE_DB_URL against the upgraded cluster at TARGET_DB_URL, through the same chunked-checksum reconcile, plus extension versions, auth schema sanity and md5-role status. Exit 0 only when the data is identical |
The lab is the only phase that needs Docker; the audit and the capture run
anywhere psql does. Because verify is the reconcile engine, a pass there means
the same thing a pass before cutover means - the two sides checksum identical
under the same GUC pinning.
Rollback, by phase
Section titled “Rollback, by phase”| Phase | Position | What rollback costs |
|---|---|---|
| A: before writes stop | the source has served continuously, the target is a throwaway | free: teardown removes the replication objects and the source is untouched |
| B: writes stopped, app not repointed | the target has taken no application writes | still lossless: teardown, then re-enable writes on the source and bring the app up unchanged |
| C: app repointed | the target is authoritative and nothing streams back | roll forward, accept the loss window and re-apply it by hand, or use the reverse path below. Re-enabling writes on both sides is split-brain |
Reverse replication keeps phase C lossless. It is a second config with the source
and target swapped, distinct slot, publication and subscription names, and
copyData: false - the data already matches, so only new changes stream back.
Set it up after reconcile passes and before the repoint; roll back inside the
window by stopping writes on the target, draining the reverse lag, repointing at
the source, and tearing down both directions. It is not active-active: only one
side ever takes application writes.
Postgres 15 to 17 live runs, 2026-11-09
Section titled “Postgres 15 to 17 live runs, 2026-11-09”pgmig’s research note records a move from Postgres 15 to 17 at two sizes, and
the platform’s in-place upgrade at the same sizes for comparison.6
Shape: throwaway projects on a Team-plan organisation, ap-southeast-1, Small
compute. The source and the in-place subject were created with
postgres_engine: "15" (PostgreSQL 15.19); the pgmig target took the platform
default (PostgreSQL 17.11). The seed puts a STORED tsvector on documents, the
copy bottleneck the evidence table names. One run per size, so every figure
below is n = 1 (a first 3.65 GB in-place attempt reached ACTIVE_HEALTHY at
695.5 s and lost its survival check to getaddrinfo ENOTFOUND).
pgmig, 15.19 to 17.11, with no writer running and no app repoint in the harness:
| Step | 50,000 documents (0.06 GB) | 4,000,000 documents (source 3.65 GB) |
|---|---|---|
| Seed | not recorded | 643.1 s |
Initial copy (replicate + watch) | 5.4 s | 196.9 s; 4 of 4 tables r, WAL retained 10MB at the end |
| Reconcile, 256 buckets | 0.8 s, identical (4 tables) | 62.6 s, identical: users 50000, documents 4000000, events 4000000, audit 400000 |
| Cutover (the write-stop window before the app repoint) | 1.6 s | 1.6 s; lag drained to 0.0 KB |
| Insert after cutover | id 50001: the sequence resync prevented a collision | id 4000001 |
The 50,000-document run predates the statement_timeout fix; its 5.4 s copy
stayed under the 2 min cap. The 4,000,000-document column is the re-run with the
fix, 09:16 to 09:40 UTC on 20 GB disks. Before it, on the default disk the seed failed
after about 6 minutes with cannot execute INSERT in a read-only transaction
(SQLSTATE 25006), the platform making the database read-only as the volume
filled; two runs on 20 GB disks without the fix never finished documents
(the caution under the pipeline). In the 50,000-document run,
doctor warned on the Small 17 target: max_worker_processes=6 (asks for 16 or more),
max_logical_replication_workers=4 for 4 tables (asks for 5 or more), and
pg_stat_statements 1.10 on the source against 1.11 on the target.
The in-place runs upgraded 15.19 to 17.11 (target image
supabase-postgres-17.11.0.018). Eligibility answered eligible: true,
duration_estimate_hours: 1 at both sizes. A 1 s probe writer inserted numbered
rows through the session pooler throughout, and a 2 s sampler opened a fresh
pooler connection each time. At 3.65 GB the project reached ACTIVE_HEALTHY
633.1 s after the POST (337.4 s at 0.06 GB). 53 of 458 acknowledged probe writes
at 0.06 GB and 52 of 691 at 3.65 GB were absent on 17, every one acknowledged by
the last 15.19 restart before 17.11 answered, which matches supabase-lab
upgrade-integrity UI03 on Micro (2026-10-23 and 10-26,
RUNLOG).
The time from 9_completed_upgrade to ACTIVE_HEALTHY grew from 20.4 s at
0.06 GB to 296 s at 3.65 GB while 17.11 was already answering; what that tail
is was not separated.
Side by side at 3.65 GB, one run each:
| pgmig | In-place upgrade | |
|---|---|---|
| Writes must stop for | 1.6 s of cutover, plus the app repoint | the whole upgrade, from before the POST: the first lost write was acknowledged at +272.9 s and 17.11 first answered at +344.6 s |
| Client-visible outage in the run | none measured (no writer, no repoint in the harness) | longest failed sample run 35.1 s (+235.3 s to +270.4 s) |
| Acknowledged writes lost | none possible after a drained cutover (reconcile identical) | 52 of 691 |
| What changes for the app | new project URL, keys and connection strings | nothing |
Not measured:
- An app writing through the pgmig cutover, a repoint, or a source with Auth users or Storage objects to carry.
- Any compute larger than Small, any region but ap-southeast-1, more than one completed run per size, databases larger than 3.65 GB.
- Whether the in-place tail scales linearly past 3.65 GB, and what the Data API does during it.
Every project was deleted by its harness’s teardown; cost was not metered.
Several new projects subscribing to one source (RR10, RR11)
Section titled “Several new projects subscribing to one source (RR10, RR11)”Two supabase-lab modules in the replica-routing experiment subscribed several new
Postgres 17 projects to one Postgres 15 source per run on 2026-11-10. Each
subscription was created with plain SQL, through the Management API query endpoint
or a session-pooler session, over the source’s direct connection with
options='-c statement_timeout=0'; pgmig was not used. Every source and target
was a throwaway on one Team-plan organisation in ap-southeast-1, the source on
postgres_engine: "15" (PostgreSQL 15.19) and the targets on the default
(PostgreSQL 17.11). RR10 was one run on Small compute with pitr_7 and 24 GB
disks: two targets subscribed at the same time to rr10_t, 4,000,000 rows and
3.9 GiB (RUNLOG at f5bd16b,
facts).
RR11 was four runs at the default compute size, up to seven targets per run, and
500,000 rows in rr11_t, loaded in 18 s, in runs 2 to 4
(RUNLOG;
facts for run 1,
run 2,
run 3
and run 4).
Every RR11 artifact names lab commit f5bd16b, which predates the module: each
run used an uncommitted version, the module changed between runs, and the
committed module is the run 4 version.
Postgres names each table-sync slot
pg_<subscription oid>_sync_<table oid>_<system identifier>, and all three
values are read on the subscriber, while the slot itself is created on the source.
The code appends the system identifier “to avoid slot_name collision with
subscriptions in other clusters”.14 Two subscribers whose three
values match therefore compute the same slot name on one source, as RR10’s two
targets did: pg_17650_sync_17643_7703759698107299042. The names come from
Postgres, so any tool that subscribes with copy_data=true, pgmig’s replicate
included, gets the same names; that is reasoned from the code, not run with pgmig.
On new 17.11 projects the identifier repeated. 24 of 26 reported 7703759698107299042 and 2 reported 7703760980994770283, so every project read shared its identifier with at least one other (RR10’s two targets and a fourth project, all read by hand; RR11a in runs 1 to 4). That holds for one region and one organisation: RR11’s projects and RR10’s two targets were in ap-southeast-1 on one Team-plan organisation, at the default size (RR11) or Small (RR10), and the fourth project’s size, region and organisation were not recorded. The 15.19 sources reported 7703759990361338896 (RR10, RR11 runs 1 to 3) and 7703761001322865815 (RR11 run 4).
The OIDs have to match as well. After the same setup steps, 10 of the 16 subscribed targets (RR10’s two, RR11 runs 2 to 4) had subscription/table OIDs 17650/17643 and five other combinations came up, so which targets would match was not known until each target’s table existed. On all 16 the subscription OID was the table OID plus 7.
Every target in these pairs had the same system_identifier; the slot values
column gives the subscription/table OIDs.
| Concurrent pair | Slot values | At the end of the wait bound | 30 s after 1,000 more rows on the source |
|---|---|---|---|
| RR10: A and B | both 17650/17643 | B every table r by the 108 s sample; A f at the 40-minute bound, 4,000,000 rows, the source’s count | A 4,000,000, B 4,001,000 |
| RR11 run 2: T1 and T2 | 17525/17518 and 17650/17643 | both r by the 16 s check, 500,000 rows | T1 and T2 501,000 |
| RR11 run 3: T1 and T4, with T2 alongside | T1 and T4 17650/17643, T2 17527/17520 | T1 and T2 r by the 16 s check; T4 f at the 10-minute bound, 500,000 rows | T1 and T2 501,000; T4 500,000, f |
| RR11 run 4: T2 and T3, with T1 alongside | T2 and T3 17650/17643, T1 17531/17524 | T2 and T1 r at 16 s; T3 f at the 10-minute bound, 500,000 rows | T1, T2 and T3 501,000, r; read after the run’s one-at-a-time pair (below) |
Three of three concurrent pairs with matching names left one target’s table in
f at the end of its wait bound, with its row count equal to the source’s. In
RR10 and RR11 run 3 that target still missed the rows written afterwards at the
30 s read; in run 4 that target (T3) was r with 501,000 rows by then, and the
target missing rows at the 30 s read was T5, from the one-at-a-time pair. No call
failed: every CREATE SUBSCRIPTION answered HTTP 201 through the query endpoint
or ran without error in a session. RR10 has log evidence of the collision: at
09:33:03 UTC the source’s walsender logged replication slot "pg_17650_sync_17643_7703759698107299042" already exists, from 09:34:54 every
attempt logged does not exist, about every 5 s to the end of the read window at
09:38:37 UTC, and at 10:18 UTC A’s tablesync
worker was still starting and exiting with code 1 about every 5 s while its apply
worker stayed up
(manual reads).
That B’s cleanup dropped the slot is inference from the timing. RR11 searched no
log for slot errors, so its two collisions are inferred from the states and
counts. Concurrent pairs whose OIDs differed did not collide (RR11 run 2, and the
controls in runs 3 and 4).
Postgres drops a table-sync slot when that table reaches sync-done (“Cleanup the
tablesync slot”, in the sync-done branch15), so a target
started after every earlier target has every table r cannot meet an earlier
target’s sync slot. That rests on the Postgres code and one incidental case: in
RR11 run 2, T3 (17650/17643) subscribed after T2 (17650/17643, the same
system_identifier) had every table r, and T3 was r by the 16 s check and
held 501,000 rows at the 30 s read. The pairs RR11 ran as one-at-a-time in runs 2
and 3 had different OIDs, and run 4’s matching pair started while an earlier
matching target was stuck.
Run 4’s states read as slot stealing. This is a reading of states; no log was
searched for slot errors. T3, stuck in f after the concurrent pair, was r with
501,000 rows by the 30 s read. T4, which subscribed while T3 was stuck, never
reached r in its 10-minute bound but was r by the 30 s read. T5 started at
T4’s bound, was the last subscribed target with the same values (T6 had the same
system_identifier and table OID but was not subscribed), and ended in f with
500,000 rows. The reading is that a
stuck target keeps retrying, takes the next same-named slot when it is created,
finishes, drops it and strands the newer target. One at a time therefore holds
only while no earlier target with the same values is stuck. A target that
recovers this way would start from the newer slot’s point and miss writes made in
between; that is inference as well, and nothing was written on the source in that
window.
A stuck target’s row count matched the source’s in all three collisions, so read the state on each target instead:
-- no rows once every table on this target is readyselect srrelid::regclass, srsubstate from pg_subscription_rel where srsubstate <> 'r';Then write a marker row on the source after the last subscription and read it back on every target.
The same RR11 runs counted whether CREATE SUBSCRIPTION, connection string and
password included, reached the target’s Postgres log. log_statement was read
on 7 of the 14 subscribed targets in runs 2 to 4 (one each in runs 2 and 3, all
five in run 4) and was ddl on all 7. Every target that did not set log_statement logged the
statement with the password, 11 of 11; set log_statement = 'none' in the same
session first kept it out on 3 of 3. Runs 2 and 3 do not separate the setting from
the connection path, because their targets that ran the set were also the only
ones in a session-pooler session. Run 4’s T4 is the like-for-like control: the
same session-pooler path without the set, and it was logged. Run 4’s T5, with
the set, had 422 Postgres log rows in the hour, so its logs were readable. The
module counted rows and printed no log text. RR10’s A logged the same statement
with the password in plain text (hand read; log_statement was not read there).
pgmig’s replicate since e82168e (2026-11-13) runs CREATE SUBSCRIPTION on one
reserved session after SET log_statement = 'none', so on a target with
log_statement ddl its statement is no longer logged; that is read from
src/steps/replicate.ts.
-- one session on the target (RR11 used a session-pooler session), both statements in itset log_statement = 'none';create subscription my_sub connection 'postgresql://postgres:<password>@db.<source-ref>.supabase.co:5432/postgres?options=-c%20statement_timeout%3D0' publication my_pub;Not settled by RR10 and RR11: recovering a stuck table on purpose
(refresh publication, or dropping and recreating the subscription); one at a
time with matching names and no stuck target beyond run 2’s T2 then T3, one
instance; writes during a slot-steal window; set log_statement from the SQL
Editor or the query endpoint; alter subscription ... connection; more than two
concurrent targets with matching slot names; table sizes other than RR11’s 500,000
rows (about 0.5 GiB, scaled from RR10’s 3.9 GiB for 4,000,000 rows; not read in
RR11) and RR10’s 4,000,000 rows.
A source with network restrictions on (RR12)
Section titled “A source with network restrictions on (RR12)”Network restrictions apply to all connection routes, pooled or direct,16
and the IPv4 address page says that when a database makes outbound connections,
the outbound address “is not static and cannot be guaranteed”.17 RR12
(replica-routing, 2026-11-11, two runs) asked which address a source sees when
another project’s subscription connects to its direct host, and what a
restriction does to a subscription already streaming. It used three throwaway
projects on the Team-plan organisation at the default compute size in
ap-southeast-1, a source S on postgres_engine: "15" (15.19) and targets T and T2
on the default (17.11). S held rr12_t with 1,000 rows, published; T subscribed
over S’s direct host on port 5432. Restrictions were applied with
POST /v1/projects/{ref}/network-restrictions/apply, and the documentation ranges
192.0.2.0/24 and 2001:db8::/32 stood for every other address. Both artifacts name
lab commit f5bd16b, which predates the module; run 1 used an earlier version and
ended with The operation timed out. before RR12g (by elimination, during RR12f’s
call), and the committed module is run 2’s with the RR12g query fixed after it
(RUNLOG;
facts for run 1
and run 2).
Each project’s database host had one AAAA record and no A record. With S open,
T’s CREATE SUBSCRIPTION returned 201 and T held 1,000 rows at the first check;
on S, pg_stat_replication listed rr12_sub_t streaming, with client_addr the
address T’s own database host, db.<target ref>.supabase.co, resolves to (the
text cast renders it as a /128). The subscriber connected from its own IPv6
address, and that is the address the source’s restriction judged.
| Step (both runs unless stated) | Source allows | Result |
|---|---|---|
| RR12c | every address | T subscribed and held 1,000 rows at the first check; S’s pg_stat_replication listed the walsender serving T with client_addr T’s own address |
| RR12d | 192.0.2.0/24 and 2001:db8::/32 | 20 s later T’s walsender was still on S, streaming, and 100 rows inserted on S were on T at the first check. T then ran alter subscription ... disable, waited 5 s and enabled it: 100 more rows inserted on S had not arrived 60 s later (T held 1,100), S listed no walsender, and T’s subscription worker had a pid in pg_stat_subscription |
| RR12e | 192.0.2.0/24 and T’s address as a /128 | GET network-restrictions read applied with one entry in each list; T held all 1,200 rows after 10 s (run 1) and 5 s (run 2), and S listed rr12_sub_t from T’s /128 again |
| RR12f | as RR12e | T2’s CREATE SUBSCRIPTION with connect_timeout=10 in the connection string: in run 1 the call had not returned when the client gave up at 120 s; in run 2 (240 s client budget) HTTP 400 after 120 s, 57014: canceling statement due to statement timeout. T2’s AAAA differed from T’s in run 2; run 1 recorded no comparison |
A walsender that was already streaming was still on S 20 s after the
restriction’s apply call, in two runs; RR12d did not read whether the restriction
was in force at that read. After T disabled and re-enabled its subscription it had
not reconnected 60 s later; once its own /128 was allowed it held every row by the
10 s (run 1) and 5 s (run 2) checks. No error source was read for the missing
reconnect: RR12g, the step meant to read the subscribers’ Postgres log lines,
returned no data (run 1 ended before it, and run 2’s query named postgres_logs
as a table). T2’s CREATE SUBSCRIPTION hung instead of failing at
connect_timeout, and in run 2 a statement timeout ended it at 120 s.
Why connect_timeout did not apply was not checked, and that the restriction
blocked T2 at all is inference, as T2 was not tried with S open; RR13 run 1 later
saw a second target’s CREATE SUBSCRIPTION, with no connect_timeout in its
connection string, end in the same 57014 statement timeout with the source open
(below).
The address to allow is the AAAA record of the target’s own database host, as a /128 in the IPv6 list. On the source, while the subscription streams, RR12c’s read shows it:
select client_addr::text, application_name, state from pg_stat_replication;Resolving the AAAA record of db.<target ref>.supabase.co gives the same address
(RR12c compared the two). No run changed the target’s instance, so whether that
address moves on a restart, resize, pause and restore or upgrade is open, and
re-checking it after any of those is a design choice taken from the docs’
outbound-address line rather than a result.
Not measured in RR12: a source with the IPv4 add-on (the restrictions page says only IPv4 CIDRs are needed then; RR13 below ran a source with the add-on but kept 2001:db8::/32 in the IPv6 list); whether a target’s address changes on restart, resize, pause and restore or upgrade; a subscription through the session pooler; a walsender’s survival under a restriction beyond 20 s; the subscriber’s log lines for the blocked connection (RR12g); a target in another region.
A source with the IPv4 add-on (RR13)
Section titled “A source with the IPv4 add-on (RR13)”With the IPv4 add-on, a project’s database host resolved to an A record only
(RR13a, all three runs), so another project’s subscription reached it over IPv4,
from the outbound address the IPv4 page calls not static.17 RR13 (replica-routing, 2026-11-11, three runs)
repeated RR12’s shape (three throwaway projects on the Team-plan organisation at the
default compute size in ap-southeast-1, S on postgres_engine: "15" (15.19), T and
T2 on the default (17.11), 1,000 rows published on S) with the add-on enabled on S
through PATCH /v1/projects/{ref}/billing/addons, and S’s records polled with
dig until it had an A and no AAAA, which held by the poll 10 s after the call. T
subscribed first and T2 once T had every table r. All three artifacts name lab
commit f557be9, which predates the module; the module changed between runs: run 2
added RR13c2 (S’s walsenders and xid holders sampled during each create, then a
logical slot created directly on S), and run 3, the committed version, added a
pg_net probe (RR13c3) and a restart (RR13f)
(RUNLOG; facts for
run 1,
run 2 and
run 3).
| Step | Runs | Result |
|---|---|---|
| RR13a | 1, 2, 3 | S had an A record and no AAAA by the poll 10 s after the add-on PATCH; T’s and T2’s own database hosts had an AAAA record and no A record |
| RR13c | 2, 3 | Both creates returned 201 and every table was r after 5 s on each target; S’s pg_stat_replication listed T and T2 from two different addresses (T2’s checked as dotted IPv4 in run 3) |
| RR13c | 1 | T subscribed (every table r after 6 s); T2’s CREATE SUBSCRIPTION, with S open, ended with HTTP 400 57014: canceling statement due to statement timeout and T2 held 0 rows |
| RR13c3 | 3 | Each target’s pg_net request to https://api.ipify.org left from the address S’s pg_stat_replication showed for it |
| RR13d | 1, 2, 3 | S allowed only T’s address as a /32 beside 2001:db8::/32; after both targets disabled and re-enabled their subscriptions (run 1’s T2 had none, its create having failed in RR13c), T held the 100 new rows at the first check, and in runs 2 and 3 T2 had not got them 120 s later |
| RR13f | 3 | POST /v1/projects/{ref}/restart on T (ACTIVE_HEALTHY at 40 s at the earliest, the step ending 66 s after the call; whether Postgres restarted was not read): T caught up under the /32 rule at the first check, from the same address, and its pg_net request still left from it |
| RR13e | 1, 2, 3 | S restricted to 192.0.2.0/24 and 2001:db8::/32: after a reconnect T got none of 100 new rows in 60 s and S listed no walsender |
On a source with the add-on, the address to allow is the target’s outbound IPv4, which its database host’s DNS does not show. The target can read it itself, which RR13c3 matched against the source’s view in run 3:
create extension if not exists pg_net;select net.http_get('https://api.ipify.org'); -- returns a request idselect content from net._http_response where id = <id>; -- a few seconds laterAllow it as a /32 in the source’s IPv4 list, one entry per target: the two targets
presented different addresses, and with only T’s /32 allowed T2 did not reconnect
(runs 2 and 3; T2’s own /32 was not tried). Run 1’s T2
hang, with no restriction in force, had no cause found (it ran before RR13c2’s
source-side probe existed; runs 2 and 3 created both subscriptions in 5 s and a logical slot created
directly on S took at most 1 s), so a hung CREATE SUBSCRIPTION alone does not show
a block.
Not measured in RR13: the cause of run 1’s hang; more than two targets or a target in another region; the address after a restore, pause and restore, upgrade or compute change; how long an address holds over days; whether Postgres restarted in RR13f; an empty IPv6 allow list (RR13d and RR13e kept 2001:db8::/32 in it).
What to do about it
Section titled “What to do about it”The pipeline’s own practices are the gates and the rollback table above. The first three rows come from the 2026-11-09 runs; the last six from the supabase-lab runs of 2026-11-10 and 2026-11-11, which subscribed with plain SQL rather than through pgmig.
| Practice | Evidence | Rests on |
|---|---|---|
Put statement_timeout=0 on the subscription CONNECTION from a Supabase source | The postgres role is capped at the 2 min global timeout. Without the option the initial COPY of 4,000,000 documents was cancelled every 120 s and restarted 16 times; with it the copy finished in 196.9 s. That any subscriber meets the cap is reasoned from the mechanism; only pgmig’s subscription was run | 2026-11-09 run, 4,000,000 documents (research note); withNoStatementTimeout(); Supabase timeouts page |
| Grow the disk before a multi-GB seed or copy on a small project | On the default disk the 4,000,000-document seed failed after about 6 minutes with cannot execute INSERT in a read-only transaction (SQLSTATE 25006) as the volume filled; on 20 GB disks the seed took 643.1 s to 3.65 GB. Only the seed failed on the default disk; a target receiving the same copy was not run on one | 2026-11-09 run, default disk, then both disks grown to 20 GB (research note) |
| Stop writers before an in-place major upgrade | 52 of 691 acknowledged probe writes (3.65 GB) and 53 of 458 (0.06 GB) were absent on 17.11, all acknowledged by the last 15.19 restart; the first lost write was acknowledged +272.9 s after the POST. The procedure is in the upgrade guide | 2026-11-09 in-place runs, both sizes (research note); supabase-lab upgrade-integrity UI03, Micro, 2026-10-23 and 10-26 (RUNLOG) |
Subscribe new targets one at a time, each after every earlier target has every table r; then check a marker row | Postgres names a table-sync slot from the subscription OID, the table OID and the system_identifier, all read on the subscriber. 24 of 26 new 17.11 projects shared one identifier and 10 of 16 subscribed targets had OIDs 17650/17643. 3 of 3 concurrent pairs with matching names left one target’s table in f at the end of its wait bound (40 minutes in RR10, 10 in RR11) with its count equal to the source’s, and no call failed. Postgres drops the slot at sync-done, so a target started after every table of the earlier ones is r cannot meet it: the Postgres code, and one incidental case (RR11 run 2, T2 then T3). Read pg_subscription_rel and a row written after the last subscription, not counts | replica-routing RR10 (RUNLOG, manual reads); RR11a (runs 1 to 4), RR11c to RR11e (runs 2 to 4) (RUNLOG); tablesync.c, the slot name and the sync-done drop |
Do not start a target while an earlier one with the same slot values is stuck in f | Same values means the same system_identifier, subscription OID and table OID. In RR11 run 4, T4 subscribed while T3 was stuck in f and did not reach r in its own 10-minute bound; by the 30 s read T3 and T4 were r with 501,000 rows, and T5, the next target with the same values, was f with 500,000. That a stuck target takes the next same-named slot is a reading of states; no log was searched. Recovering a stuck table on purpose was not run | replica-routing RR11c to RR11e, run 4 (facts) |
Run set log_statement = 'none' in the same session before CREATE SUBSCRIPTION | log_statement was ddl on all 7 of the 14 subscribed targets where it was read; the statement and its password reached the target’s Postgres log on 11 of 11 targets without the set and on 0 of 3 with it; run 4’s T4, the same session-pooler path without the set, was logged. Counts only. The set was not tried through the query endpoint or the SQL Editor. pgmig’s replicate since e82168e (2026-11-13) sets SET log_statement = 'none' in the same session before CREATE SUBSCRIPTION (src/steps/replicate.ts) | replica-routing RR11f, runs 2 to 4 (run 2, run 3, run 4) |
| On a restricted source, allow the target’s database host IPv6 as a /128; re-check it | The source’s pg_stat_replication showed client_addr equal to the AAAA record of db.<target ref>.supabase.co, two runs. An already-streaming walsender was still on S 20 s after the restriction’s apply call (whether it was in force by then was not read), but after a disable and enable the subscription had not reconnected 60 s later; allowing only the target’s /128 let it catch up by the 10 s and 5 s checks, so allow it before the restriction goes on. The re-check after a restart, resize, pause and restore or upgrade of the target is a design choice: the docs say an outbound address “is not static and cannot be guaranteed”, and no run changed the target’s instance | replica-routing RR12c to RR12e, two runs (run 1, run 2); IPv4 address page |
Do not wait for CREATE SUBSCRIPTION to return an error; read the source’s pg_stat_replication and a marker row | Under RR12e’s restriction T2’s call with connect_timeout=10 had not returned when run 1’s client gave up at 120 s, and in run 2 ended with HTTP 400 after 120 s, 57014: canceling statement due to statement timeout; RR13 run 1’s T2 call, with the source open and no connect_timeout, also ended in 57014, cause not found. No call returned a connection error. What showed a subscription was not connected was the source listing no walsender for it while 100 rows inserted on the source did not arrive (RR12d both runs, RR13e all runs); the target’s pg_stat_subscription still showed a worker pid in RR12d (5319 and 5976), so a pid there does not show a connection | replica-routing RR12d and RR12f (run 1 facts, run 2 facts), RR13c run 1 and RR13e (facts) |
| On a source with the IPv4 add-on, allow each target’s outbound IPv4 as a /32, read with the target’s own pg_net request | The target arrived over IPv4 from an address its own database host’s DNS does not show; its pg_net request to an IP echo service left from the address the source saw (run 3, both targets); two targets had different addresses and with only one target’s /32 allowed the other did not reconnect (runs 2 and 3; its own /32 was not tried); the address held across a reconnect (all runs) and a restart through the API (run 3; whether Postgres restarted was not read). A restore, upgrade or compute change was not tested, so re-reading it after any of those is a design choice | replica-routing RR13c to RR13f (run 3 facts, RUNLOG) |
Decision guide
Section titled “Decision guide”Text fallback:
- A Postgres major-version change in place, no new project - the
pg_upgraderehearsal lab, then the upgrade itself. - A whole project to another region or a new major version as a new project -
bootstrapfirst, then the replication pipeline; this is the region guide. - Data only, into a schema you already created and control -
replicateonward, with the pre-step done by your own tooling. - Small database, downtime acceptable - dump and restore, and skip the pipeline.
Evidence
Section titled “Evidence”| Claim | How it was checked |
|---|---|
| Logical replication carries rows, not DDL, roles, extensions or sequences | Postgres logical replication documentation, and pgmig’s own scope document (MIGRATION-SCOPE.md, commit ba5f88c) |
bootstrap --with-auth-data copies a snapshot of the auth rows (FK triggers deferred) for testing; cutover --with-auth-data reloads them from the source’s final state inside the write stop | pgmig CHANGELOG.md, README.md step 6 and docs/RUNBOOK.md section 6 at commit 26feb0b (2026-11-13); bootstrap exercised live on 2026-07-30 per the region guide’s measured run, cutover integration-tested in test/cutover-auth.integration.test.ts |
auth.schema_migrations is SELECT-only for the postgres role on a managed target | RUNBOOK section 6, recorded as verified 2026-07-30; reproduced in the upgrade guide’s gotchas |
cutover --with-auth-data dumps the source’s auth rows, empties the target’s auth tables and loads them in one transaction under session_replication_role = replica; a failed reload commits nothing and leaves the subscription | pgmig CHANGELOG.md and README.md steps 6-7 at commit 26feb0b (2026-11-13); implementation at src/steps/cutover.ts commit e82168e; integration-tested in test/cutover-auth.integration.test.ts |
Replicated rows skip FK checks on the subscriber (apply and initial-copy workers run with session_replication_role = replica), so an FK into auth.users does not block the copy | pgmig CHANGELOG and RUNBOOK at commit 26feb0b (2026-11-13); integration tier, plain 15.19 -> 17.11, 2026-11-13; test/cutover-auth.integration.test.ts |
A sequence collision follows a skipped resync, and cutover closes it | The companion upgrade guide’s sequence check (an insert after cutover returns the next id after 300 seeded rows) |
watch aborts on the WAL watchdog and on wal_status='lost' | pgmig README.md command table and the scale harness’s WATCHDOG_FIRE=1 negative mode, which exits non-zero if the abort does not fire |
| A write that continues through cutover makes the lag gate fail | The scale harness’s WRITE_THROUGH_CUTOVER=1 mode, which asserts the lag did not drain failure |
| A STORED generated column is the initial-copy bottleneck | pgmig’s large-scale rehearsal, reported in README.md and repeated in the companion upgrade guide (about 7x slower copy) |
| Cross-region row hashes match only because the GUCs are pinned | pgmig skills/pgmig/SKILL.md and the reconcile implementation; the cross-region pass itself is the region guide’s measured run |
| DDL on the source stalls the stream until the same DDL is applied on the target | supabase-lab W15, cited in both companion guides (about 6.1 s to resume with backfill) |
watch warns on rising apply or sync error counts and does not abort on them | src/steps/watch.ts at ba5f88c (a log.warn, then the sync timeout); measured 2026-11-09, when watch warned through sync_error_count 16 until the harness’s 30 min limit (research note) |
From a Supabase source, a subscription without statement_timeout=0 cancels an initial COPY longer than 2 min and restarts it | Measured 2026-11-09, 4,000,000 documents, two runs on 20 GB disks that never synced documents; the second read the logs: the target and source log lines every 120 s, sync_error_count 16; the re-run with withNoStatementTimeout() synced in 196.9 s (research note). The 2 min cap is documented on the Supabase timeouts page; that it hits any subscriber is reasoned from the mechanism |
| pgmig’s write-stop window from 15.19 to 17.11 was 1.6 s at 0.06 GB and at 3.65 GB, reconcile identical | Measured 2026-11-09, one run per size, Team-plan organisation, Small, ap-southeast-1, no writer running and no app repoint (research note) |
| The in-place upgrade loses writes acknowledged by the last 15.19 restart | Measured 2026-11-09, 2 of 2 runs with a completed survival check, one per size (53 of 458 at 0.06 GB, 52 of 691 at 3.65 GB); agrees with supabase-lab upgrade-integrity UI03 (RUNLOG) |
| A multi-GB seed on a default-size disk turns the database read-only (SQLSTATE 25006) | Measured 2026-11-09, the 4,000,000-document seed, failed after about 6 minutes (research note) |
New 17.11 projects share a system_identifier, so two targets whose OIDs also match compute the same table-sync slot name on one source | Measured 2026-11-10: 24 of 26 projects one value and 2 of 26 another (RR10 hand read, RR11a runs 1 to 4), 25 of them in ap-southeast-1 on one Team-plan organisation and RR10’s fourth project’s size, region and organisation not recorded; subscription/table OIDs 17650/17643 on 10 of 16 subscribed targets (RR10 RUNLOG, RR11 RUNLOG). The name format is ReplicationSlotNameForTablesync in Postgres 17’s tablesync.c |
Concurrent targets with matching slot names leave one table in f at the end of the wait bound with its count equal to the source’s, and no call fails | Measured, 3 of 3 pairs: RR10 (one run, 3.9 GiB, 40-minute bound) and RR11 runs 3 and 4 (500,000 rows, 10-minute bound). Log evidence only in RR10 (manual reads); RR11’s two are inferred from states and counts (run 3, run 4) |
| Subscribing one target at a time avoids the collision while no earlier target with the same values is stuck | The Postgres code drops the slot at sync-done (tablesync.c); one incidental measured case, RR11 run 2’s T2 then T3 (facts). Run 4’s states at the 30 s read (T3 recovered, T5 in f) are measured; reading them as slot stealing is inference, as no log was searched |
set log_statement = 'none' in the same session keeps the CREATE SUBSCRIPTION password out of the target’s Postgres log | Measured 2026-11-10, RR11f runs 2 to 4: 11 of 11 targets without the set logged it, 0 of 3 with it; run 4’s T4 is the same session-pooler path without the set. Counts only, no log text printed. pgmig’s replicate since e82168e (2026-11-13) does this automatically (src/steps/replicate.ts) (RR11 RUNLOG) |
| A subscriber connects from its own database host’s IPv6 address, and a restricted source admits it once that /128 is allowed | Measured 2026-11-11, RR12c to RR12e, two runs, ap-southeast-1, one Team-plan organisation (run 1, run 2). That restrictions cover every route is documented on the network restrictions page |
A CREATE SUBSCRIPTION that did not complete ran until a statement timeout: under a restriction with connect_timeout=10 (RR12f), and once with the source open and no connect_timeout (RR13 run 1) | Measured 2026-11-11, RR12f: HTTP 400 after 120 s, 57014, in run 2; run 1’s client gave up at 120 s (run 2 facts). Why connect_timeout did not apply was not checked; that the restriction caused the hang is inference, as T2 was not tried with the source open; RR13 run 1 saw a 57014 statement timeout with the source open, duration not recorded (facts). |
| With the IPv4 add-on on the source, a subscriber arrived over IPv4 from an outbound address that differed between the two targets and that its own pg_net request reported (run 3) | Measured 2026-11-11, RR13, three runs, ap-southeast-1, one Team-plan organisation: different addresses for two targets (runs 2 and 3), pg_net egress equal to the source’s view (run 3), the same address after a reconnect (all runs) and a restart (run 3; whether Postgres restarted was not read) (RUNLOG) |
The rollout mechanics that vary by environment - how long a paused source stays
useful, the watchdog threshold, whether to match target compute with provision -
are operator decisions in the RUNBOOK. No run set them.
References
Section titled “References”-
PostgreSQL Global Development Group, “Logical replication,” PostgreSQL 17 Documentation. https://www.postgresql.org/docs/current/logical-replication.html ↩
-
pgmig, “Postgres-to-Postgres logical-replication migrator,” GitHub. https://github.com/erfianugrah/pgmig ↩
-
pgmig, “README,” GitHub, commit
ba5f88c. https://github.com/erfianugrah/pgmig/blob/ba5f88c/README.md ↩ -
Anugrah, “Migrate a Supabase project to another region, end to end.” https://erfi.dev/guides/supabase-region-migration-e2e/ ↩
-
Anugrah, “Upgrade a Supabase project to a new Postgres major version, end to end.” https://erfi.dev/guides/supabase-postgres-major-upgrade-e2e/ ↩
-
pgmig, “docs/research/2026-11-09-pg15-to-17-live.md,” GitHub, commit
cd29532. https://github.com/erfianugrah/pgmig/blob/cd29532/docs/research/2026-11-09-pg15-to-17-live.md ↩ ↩2 ↩3 -
pgmig, “docs/MIGRATION-SCOPE.md,” GitHub, commit
ba5f88c. https://github.com/erfianugrah/pgmig/blob/ba5f88c/docs/MIGRATION-SCOPE.md ↩ -
Supabase, “Timeouts,” Supabase Docs. https://supabase.com/docs/guides/database/postgres/timeouts ↩
-
pgmig, “src/steps/replicate.ts,” GitHub, commit
cd29532. https://github.com/erfianugrah/pgmig/blob/cd29532/src/steps/replicate.ts ↩ -
pgmig, “src/db.ts (withNoStatementTimeout),” GitHub, commit
cd29532. https://github.com/erfianugrah/pgmig/blob/cd29532/src/db.ts ↩ -
pgmig, “docs/RUNBOOK.md,” GitHub, commit
ba5f88c. https://github.com/erfianugrah/pgmig/blob/ba5f88c/docs/RUNBOOK.md ↩ -
pgmig, “skills/pgmig/SKILL.md,” GitHub, commit
ba5f88c. https://github.com/erfianugrah/pgmig/blob/ba5f88c/skills/pgmig/SKILL.md ↩ -
PostgreSQL Global Development Group, “pg_upgrade,” PostgreSQL 17 Documentation. https://www.postgresql.org/docs/current/pgupgrade.html ↩
-
PostgreSQL Global Development Group, “src/backend/replication/logical/tablesync.c (ReplicationSlotNameForTablesync),” GitHub, REL_17_STABLE at commit
f2acab5. https://github.com/postgres/postgres/blob/f2acab53482cfd444c8ac23d317f90ad6f6b1a7f/src/backend/replication/logical/tablesync.c#L1276-L1299 ↩ -
PostgreSQL Global Development Group, “src/backend/replication/logical/tablesync.c (the sync-done branch),” GitHub, REL_17_STABLE at commit
f2acab5. https://github.com/postgres/postgres/blob/f2acab53482cfd444c8ac23d317f90ad6f6b1a7f/src/backend/replication/logical/tablesync.c#L306-L345 ↩ -
Supabase, “Network Restrictions,” Supabase Docs. https://supabase.com/docs/guides/platform/network-restrictions ↩
-
Supabase, “Dedicated IPv4 Address for Ingress,” Supabase Docs. https://supabase.com/docs/guides/platform/ipv4-address ↩ ↩2
Linked from
- Migrate a Supabase project to another region, end to end
- Multigres OSS failover: what a client sees
- Supabase Pipelines (public alpha): what a PAT reaches and how the engine replicates
- Supabase read replicas: how requests reach them and what they cost
- Upgrade a Supabase project to a new Postgres major version, end to end