Skip to content

Pin moonlink 0.3.0 (0e38b43) - #202

Merged
zhousun merged 2 commits into
v0.3-devfrom
v0.3/13-final-pin
Nov 17, 2026
Merged

zhousun merged 2 commits into
v0.3-devfrom
v0.3/13-final-pin

Conversation

@zhousun

@zhousun zhousun commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What and why

This moves the moonlink submodule to 0e38b435, the v0.3-dev commit that pg_mooncake 0.3.0 ships with. Since the previous pin (977dc549), moonlink has four more fixes:

moonlink PR Fix
2371 The initial copy stored a text value of backslash-N (\N) as NULL. It also stored a copied row with fewer columns than the table with its values in the wrong columns; such rows are now rejected.
2372 mooncake.create_snapshot waited forever on an idle mirror after a streamed transaction aborted.
2373 mooncake.create_table now returns only once the initial copy is persisted in Iceberg. Before, a moonlink restart within about half a second after it returned lost the copied rows, with no error.
2374 If the disk fills up while the copy is being persisted, create_table fails with an error. Dropping the mirror from another session while create_table runs makes the call fail and leaves nothing behind.

Changes

  • moonlink submodule: 977dc549 → 0e38b435.
  • CHANGELOG, "Fixed in moonlink":
    • one line each for PRs 2371 and 2372, and one for PRs 2373 and 2374 together, in place of the release marker that held them;
    • the 2373 line gives the slowdown as measured: roughly 0.4 s more per million narrow rows in a local test;
    • it also says what a failed create_table leaves behind. If only the moonlink worker restarts, nothing is left and the call can be retried. After a server restart or crash, the empty mirror table has to be dropped first.
  • PR 2373 makes three things obsolete, so they are removed:
    • the CHANGELOG known limitation about a restart right after create_table, with its release marker;
    • the matching AGENTS.md section 7 entry;
    • the caveat "once a mirror's initial copy has been persisted" on the PR 2364 restart line.
  • New known limitation, in the CHANGELOG and AGENTS.md section 7: if the server stops or crashes while create_table runs, the empty USING mooncake table stays, and a retry fails until it is dropped. The table is created on a separate, autocommitted connection, and its cleanup DROP never runs when that connection dies.
  • docs/ARCHITECTURE.md, step 4 [pins]: moonlink answers CreateTable only once the copy is persisted to Iceberg and the mirror is recorded in its sqlite metadata store.
  • [pins] in AGENTS.md and docs/ARCHITECTURE.md, and the header of scripts/e2e-known-bugs.txt: 0e38b435. No known-bugs entry changes; none covered the restart loss.
  • tests/pg_regress/partitioned_existing: removes the workaround that persisted the copy before the first read (an extra row, create_snapshot, then a delete). The expected results are the same.
  • tests/mirror_diff/expected.txt:
    • the header names the current pins (it named moonlink c1a99ef and pg_duckdb 7daa8e5);
    • nine bugs that a full PostgreSQL 17 run on these pins reports fixed are dropped, with their rules (see "Tests run");
    • the header says the rules don't cover moonlink 0.3's create_table refusals and errored state yet.

Release markers still open

scripts/check-release-markers.sh still lists these five, and the v* tag check keeps failing until they are resolved:

  • CHANGELOG.md:1: the release date.
  • CHANGELOG.md:119: the Performance numbers from the release benchmark.
  • README.md:28: the Docker image's moving pgduckdb/pgduckdb:18-main base.
  • README.md:44: the PostgreSQL versions, to check against the release test matrix.
  • README.md:175: src_uri, which the release tests don't cover.

Tests run

All on PostgreSQL 17 unless noted. The review commit changes only docs and the mirror_diff rules, so the build checks ran on the first commit.

Check Result
clippy -D warnings, PG17 and PG18 clean
make test, PG17 and PG18 9/9 each
e2e gate (scripts/e2e-smoke.sh) GATE PASS: 390 pass, 0 fail, 15 known limitations, 0 XPASS
SIGTERM to the moonlink worker 0 ms after create_table returns (100 rows, 5 trials; 100,000 rows, 3 trials) 0 lost, and the mirror keeps replicating afterwards
Fast stop and restart 0 ms after create_table returns (3 trials) 0 lost
SIGTERM to the worker 0.4 s into create_table on a 1M-row table (3 trials) create_table fails, no mirror is left in Postgres or moonlink, and a retry mirrors all 1M rows
pg_ctl stop -m fast 0.4 s into create_table on 1M rows, then start (2 trials) The empty USING mooncake table stays and moonlink has no mirror. The retry fails with error creating table: public.s_mc; after DROP TABLE it mirrors all 1M rows
pg_ctl stop -m immediate (as a crash) at the same point (2 trials) Same as the fast stop
DROP TABLE of the mirror from another session 0.5 s into create_table on 1M rows (3 trials) The drop succeeds and create_table fails (Table ... (dropped while it was being created) not found). Nothing is left in Postgres or moonlink, and a retry mirrors all 1M rows
tests/mirror_diff, full run (data, cdc and query layers) No moonlink panics and no backend crashes. 1328 pass, 10 XPASS, 211 fail, 27 XFAIL, 158 XFAIL as limitations, 370 skip
tests/mirror_diff unit tests 38 pass; the edited expected.txt parses (22 bugs)

With the previous pin, the first two restart checks lost the copied rows in every trial.

In the mirror_diff run, every check of these nine bugs passed (XPASS), so they are dropped:

  • date-out-of-range
  • unchanged-toast-overwritten
  • inheritance-children-ignored
  • inheritance-recovery-crash-loop
  • partition-update-panics
  • relation-schema-assert
  • snapshot-hangs-after-xidless-wal
  • duckdb-timezone-commit-abort
  • duckdb-multiassign-abort

The tenth XPASS, json-text-normalised, stays: only jsonb was covered, not json. Bugs that were not seen are kept too, because not seeing a bug doesn't show it is fixed.

The 211 failures are behavior that 0.3 documents and that has no rule yet:

  • create_table refusing, by name: inheritance parents, partitioned tables without a primary key, unsupported types, and infinite timestamps;
  • mirrors entering the errored state.

So mirror_diff's own gate fails on these pins until rules for them are added.

This pull request and its description were written by Isaac.

Point the moonlink submodule at v0.3-dev 0e38b43, the commit pg_mooncake 0.3.0 ships with. Since 977dc54 it has
moonlink PR 2371 (a text value of backslash-N was read as NULL by the initial copy, and short copied rows were
stored with their values in the wrong columns), PR 2372 (create_snapshot waited forever on an idle mirror after a
streamed transaction aborted), PR 2373 (create_table returns only once the initial copy is persisted, so a restart
right after it no longer loses the copy) and PR 2374 (a full disk during the initial copy fails create_table
promptly, and dropping a mirror while it is being created is safe).

The CHANGELOG lists the four in place of their release marker, and the known limitation for a restart right after
create_table goes, with its marker, its AGENTS.md entry and the caveat on the restart fix. The partitioned_existing
test no longer needs to persist the copy itself before reading it. The docs' and the known-bugs file's moonlink pin
follow.

Co-authored-by: Isaac <no-reply@databricks.com>
The CHANGELOG line for moonlink PRs 2373 and 2374 is now one bullet. A failed create_table leaves no mirror
behind only when the moonlink worker restarts during it: after a server stop, restart or crash, the helper
connection is gone before its cleanup DROP runs, so the empty mirror table stays and a retry fails until it is
dropped. The line says so, and the case is a known limitation in the CHANGELOG and AGENTS.md. The slowdown is
given as measured (roughly 0.4 s more per million narrow rows in a local test), and the full-disk sentence says
what happens instead of comparing with a wait no release had. ARCHITECTURE.md says that CreateTable answers only
once the copy is persisted to Iceberg and the mirror is recorded in sqlite.

tests/mirror_diff/expected.txt names the current pins, and drops nine bugs that a full PostgreSQL 17 run on them
reports fixed, with their rules. Its header says that the rules do not cover moonlink 0.3's create_table refusals
and errored state yet.

Co-authored-by: Isaac <no-reply@databricks.com>
@zhousun
zhousun merged commit 84e9096 into v0.3-dev Nov 17, 2026
9 checks passed
@zhousun
zhousun deleted the v0.3/13-final-pin branch November 17, 2026 05:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant