Skip to content

Trellis 0.2.0

Choose a tag to compare

@mmmries mmmries released this 11 Nov 00:20
f2afc74

Trellis 0.2.0

Highlights

0.2.0 is the first minor release after 0.1.0. The main changes:

  • A much broader subset of Postgres' expression language is now supported.
    more functions and operators, all follow postgres semantics.
  • JOINs are now supported in 1-1 transforms with up to 5 joins in a combination
    of LEFT and INNER joins in a typical start pattern.
  • MIN/MAX work in plain GROUP BY aggregates, backed by a required
    source index.
  • SUM/AVG over any numeric, including unconstrained columns,
    expressions and another transform's target columns, show exactly what
    Postgres shows.
  • Source keys are explicit. Trellis keys a table by its primary key or by
    a KEY (…) the definition names. It never picks a unique index on its own.
  • Upgrades and rollbacks are managed. Two versions never run side by side
    (version handover). The catalog and every definition record a
    compatibility floor, and a release below a floor stands by or pauses
    instead of misreading state.
  • Schema dumps carry definitions, not Trellis internals. New trellis dump
    and trellis restore commands, Rails and Ecto load hooks, and
    ADOPT EXISTING TABLE to define into an empty table you already created.
  • Connection budget. The background pool needs one more connection than in
    0.1.0: 2N + 6 with staging and N drain threads (was 2N + 5), 2N + 5
    with drain threads only, and 2 with staging only. The call-pool options
    (max_call_pool_size, call_pool_wait_timeout_ms) are unchanged.
  • TRANSFORM <target> ADOPT EXISTING TABLE FROM … builds into an existing
    empty table that is shaped exactly as define would create it. It may carry
    anything a user may add to a target (indexes, constraints, triggers,
    grants, policies, …). Anything else is refused with TargetNotAdoptable,
    naming the property.

Bugfixes

  • Name quoting is now supported and unquoted names are interpreted in lowercase
    to match how Postgres handles them in its own query parsing.

Validations

Validation beyond CI since v0.1.0 (2026-10-31), from the maintainers'
validation logbook: 214 recorded runs, 112.9 hours, and about 5.12 billion
source rows or cases. That breaks down as:

  • 114 generative sweeps (70.6 h, about 107 million source rows);
  • 7 expression-conformance sweeps that checked about 1.83 billion generated
    expressions against Postgres (6.9 h);
  • 13 soak runs, 12 of them segments of the 0.2.0 generative soak (12.0 h,
    about 2.03 billion rows or generated expressions);
  • 37 benchmark runs (9.0 h, about 1.10 billion rows);
  • 28 repro loops (9.5 h, about 46 million rows);
  • 15 acceptance runs, the upgrade battery among them (4.9 h, about 14.8 million
    rows).

Most row counts are the runs' own estimates. The Validation
section has the details. We also ran an Upgrade battery)
to test upgarde and downgrade cases.

Upgrading

Take a backup of the whole database before upgrading. Rolling back to 0.1.x
means restoring that backup (Rollback below).

Future versions will have strong support for rollbacks, where transforms will
continue to run as much as the older version can support.

Procedure

The steps are in
upgrading,
and the same steps apply to the CLI and to embedded applications:

  1. Start 0.2.0, beside 0.1.0 or after it. While a 0.1.0 process is live,
    every 0.2.0 process stands by. It stages, drains and builds nothing, and
    checks again every 5 seconds. Its state-changing calls refuse with the new
    version_handover error code. trellis status prints a Standing by:
    line, and trellis run prints trellis standing by: …. 0.1.0 keeps
    running, and the capture triggers keep staging changes.
  2. Stop every 0.1.0 process. 0.2.0 takes over at its next poll, or up to
    30 seconds later after a process was killed without a clean shutdown.
  3. Run migrate. 0.2.0 adds migrations V9__worker_versions.sql through
    V20__definition_join_tables.sql. trellis run migrates by itself once
    0.1.0 has stopped. An embedded fleet runs migrate
    (bin/rails trellis:migrate, or a release task calling Trellis.migrate!)
    in a deploy step after the old processes are gone. While a 0.1.0 process
    is live, migrate refuses with version_handover.

Definitions 0.2.0 refuses

0.2.0 refuses some definitions that 0.1.0 accepted. At the takeover, each
such definition pauses, with a capture_failure naming the refusal and the
remedy. The other definitions keep running. RESUME and ALTER TRANSFORM
refuse it, and DROP TRANSFORM works. Remedy: DROP TRANSFORM, then
define it again in the current grammar.

  • A bare reserved word as a column name, such as SELECT order AS o.
    Write "order" or orders.order. This covers every word
    pg_get_keywords() marks R or T (order, user, end, group,
    limit, …).
  • An expression nested more than 100 levels deep, as an operator chain or
    as nested parentheses. Split it into calculated fields.
  • A number directly followed by a letter, such as a+1AS x or 1AS x.
    Put a space between them. (Confirmed in the pre-#1816 battery run
    20261109T071955-e-acceptance. v0.1.0 accepted 1AS and refused 0x1,
    1e, 1.5e3x and 1_000. 0.2.0 pauses it with "trailing junk after
    numeric literal … drop the transform and define it again", and that remedy
    works.)
  • Definitions that parse but fail a define-time check keep the state they
    had (#1826, decided 2026-11-09).
    The takeover pauses only what the new
    grammar can't parse (the cases above). A stored definition that parses but
    that 0.2.0's define would refuse keeps the behaviour it had under the
    release that accepted it. For 0.2.0 this is a chain of calculated fields
    too long to inline (FieldExpansionTooLarge, 51 or more fields): it stays
    live and correct. A stored constant that Postgres can't evaluate
    (2147483647 + 1) is no longer a refusal at all (below): the takeover
    leaves its state and held keys as 0.1.x left them, and rows that fail
    after the upgrade are handled as described there, except that keys 0.1.x
    held count toward the whole-definition fuse.
  • A bare true, false or null read as a column or field name (#1825,
    fixed).
    A stored 0.1.x definition keeps reading the column or field, as
    0.1.x did. Confirmed from the final RC battery on 949240d from v0.1.0 and v0.1.1: null AS x,
    NULL AS x, COALESCE(null, a), false AS x, true AS x, true + 1
    and a field named null stay live and equal Postgres's reading of the
    column through updates, inserts and deletes, with self_check clean. The
    same text defined now reads the literal (grammar 2).

Names over 63 bytes. A definition 0.1.x stored with an AS label over 63
bytes keeps running. Postgres had truncated that target column at define.
Its text can't be written in grammar 2, so ALTER TRANSFORM refuses it
(NameTooLong). If the takeover has to write a KEY (…) into it (below),
the definition pauses instead. Remedy: DROP TRANSFORM and define it again
with a name of 63 bytes or fewer.

PostgreSQL 18 virtual generated columns. In 0.1.0, a definition that read
a GENERATED ALWAYS AS (…) VIRTUAL column made every insert into its source
fail. 0.2.0 refuses such a definition at define, ALTER TRANSFORM and
RESUME, and pauses its readers. Remedy: make the column STORED and
RESUME, or drop the transform and define it again with the expression
written in the definition. A definition 0.1.0 already built over such a
column pauses at the first staging pass after the takeover, with that reason
and remedy, and inserts into its source work again. (Confirmed on
PostgreSQL 18.6 in the pre-#1816 battery run 20261109T071955-e-acceptance:
a 1-1 transform and a SUM over the column paused, RESUME refused, and
after the column was dropped and added back STORED, RESUME brought both
back matching Postgres.)

What new text means differently (grammar 2)

Grammar 2 is the first grammar-version bump
(ADR-0018).
A stored definition keeps its meaning. Text written after the upgrade reads
the new way:

  • An unquoted name folds to lower case, and a quoted name is exact, as in
    Postgres. SUM(Total) reads total. A column, table or target created
    with upper-case letters must be written quoted: SUM("Total").
  • Scripts and migrations that address a target 0.1.x created with a
    mixed-case name must quote it:
    PAUSE TRANSFORM "OrderTotals",
    DROP TRANSFORM "OrderTotals". The unquoted spelling is refused with
    did you mean "OrderTotals"? and acts on nothing.
  • Stored 0.1.x definitions keep reading their names as written.
    ALTER TRANSFORM stores such a definition with its names quoted
    (SUM("Amount")). Text with no quoted name and no upper-case letter is
    stamped grammar 1 whichever release wrote it.
  • Refused in new text:
    • names over 63 bytes after folding (NameTooLong);
    • unquoted reserved table names (FROM user, FROM order,
      TRANSFORM order; public.order is fine), a reserved word as a
      GROUP BY or KEY (…) column, and a reserved JOIN qualifier;
    • the quoted forms "", U&"…", a quoted name holding . or a non-ASCII
      character, and a quoted function or type name ("lower"(x),
      CAST(x AS "int4")).
  • TRUE, FALSE and NULL are literals in new text.
  • Error messages spell function and construct names in canonical upper case.

Definitions that pause because 0.2.0 keys a table differently

Each case below has its remedy. The details are in
upgrading.

  • A source key with INCLUDE columns (primary key (id) include (x)).
    0.1.0 read the included columns as key columns. The definition pauses,
    naming the table and the columns, and so does a 1-1 transform that reads
    its 1-1 target. Remedy: RESUME, which re-keys and rebuilds it.
  • A source whose primary key was dropped after define. 0.1.0 keyed such a
    table by a unique index it chose. At the takeover:
    • If that index qualifies as a key now (valid, not deferrable, not partial,
      over plain columns that are NOT NULL or NULLS NOT DISTINCT), its
      columns are written into the stored definition as KEY (…). The
      definition keeps running, and status() and schema dumps show the new
      text. For a 1-1 transform, plain or JOIN, the index must also cover the
      columns of the primary key the source had at define.
    • Otherwise the definition pauses, naming the table and its unique indexes.
      Remedy: add a primary key (for a 1-1 transform, that same key) and
      RESUME; or DROP TRANSFORM and define it again with a valid KEY (…).
  • A deferrable primary key (DEFERRABLE, initially immediate or
    deferred) on a source or joined table pauses the definition. Remedy:
    recreate the key not deferrable in one statement
    (ALTER TABLE … DROP CONSTRAINT …, ADD PRIMARY KEY (…)), then RESUME.
    Or DROP TRANSFORM and define it again with a KEY (…) over a unique index
    that isn't deferrable.

After the upgrade, Trellis never keys a table by a unique index it picks.
When a table's primary key is redefined or dropped, the transforms keyed by
that key pause. RESUME of an aggregate or JOIN takes the table's current
primary key and refuses while it has none. RESUME of a 1-1 transform
re-keys its target in place. A table read with KEY (…) is unaffected by
anything its primary key does. It pauses when no valid index backs its key
any more
(the key row).
A paused transform's capture_failure now lists every reason it is paused
for, plus what RESUME would do.

Rolling back to 0.1.x

Rolling back means restoring a backup taken before the upgrade, which also
discards every write your application made since the upgrade. 0.1.0 can't
read the floors, and its migrate, trellis run and trellis apply
refuse a database that 0.2.0 has migrated. A 0.1.x worker started without
migrate runs unchecked on that database
(upgrading — to a release before 0.2.0).
The battery's rollback step (step 8) confirmed that v0.1.0's run and
apply refuse a 0.2.0 database (logbook 20261104T121139-a-acceptance).
The release candidate's step 8 (final RC battery on 949240d, logbook
20261110T100804-e-acceptance): v0.1.0's and v0.1.1's run and apply
refuse with "schema "trellis" was written by a newer Trellis (instance
format version 2)".

From 0.2.0 on, a later release can be rolled back to 0.2.0 without a
restore, within the floors
(upgrading — Rolling back).

Schema dumps (structure.sql)

  • The format changes
    (ADR-0025).
    A dump now holds your schema, the target tables and one restore-queue row
    per definition. It no longer holds Trellis's schema, the capture triggers
    or the 1-1 ledgers. migrate restores the queued definitions, unbuilt,
    and the worker builds them.
  • A structure.sql written by 0.1.0 still loads as it did. It carries
    Trellis's schema and the catalog rows. The battery's structure step
    covers that format. v0.1.0 has no schema_dump call, so no 0.1.0 file is
    in the new format. Regenerate the file under 0.2.0 to switch.
  • Rails: the Railtie's hooks run migrate after db:schema:load,
    db:prepare, db:setup and maintain_test_schema!. A file loaded another
    way (psql -f) needs bin/rails trellis:migrate afterwards.
  • Elixir: add the load alias next to the dump alias:
    ["ecto.dump": "trellis.dump", "ecto.load": "trellis.load"]. Without it, a
    database built by mix ecto.load from a new-format file has its targets
    but no transforms until Trellis.migrate/1 runs.
  • A dump that fails after pg_dump has written the file now removes the
    file, because what remained would load without the definitions.

Upgrades and rollback

  • Version handover
    (ADR-0023):
    a new version stands by while an old one is live, then takes over. Every
    write transaction of a state-changing call is fenced under the handover
    lock (#1637).
  • Compatibility floors
    (ADR-0024):
    • A release below the catalog floor stands by, and its state-changing
      calls refuse with version_floor.
    • A definition above the running release is paused without being parsed,
      and the rest keep running. DROP of it refuses.
    • Stored values a newer release wrote (statuses, kinds, cursor tags,
      partition trees) pause the definition instead of being misread.
  • New page:
    upgrading and rolling back.

Operations and observability

  • A paused transform's capture_failure:
    • error lists every reason it is paused for and what RESUME would do
      now, kept current by the staging worker's pass;
    • reasons and resume_outcome carry the two parts separately (Rust API).
  • New status() fields:
    • floor;
    • version_handover;
    • below_catalog_floor;
    • extreme_index_gaps;
    • build_wait_xid;
    • join, with hidden-table sizes, warnings and the build step, in the Ruby
      and Elixir bindings too.
  • New metrics:
    • ring_rows, ring_bytes, ring_oldest_undrained_age_seconds,
      ring_undrained_bytes{source_table};
    • page_transaction_seconds.
  • Connections:
    • Trellis sessions set search_path to Trellis's own schema only, so a
      user function or operator in public or the target schema can't shadow
      a built-in.
    • Pooled connections set TCP_USER_TIMEOUT, so a network partition with
      data in flight is noticed in about 25 s.
    • A refused connection's error includes the server's reason.
  • A lock wait on a catalog statement now reports the retryable timeout
    code instead of internal.
  • CI tests PostgreSQL 15, 16, 17 and 18.

Breaking and changed API

Rust (trellis-pg)

  • Removed:

    • Trellis::pool(), Pool, PooledClient and TransactionBuilder.
      Read targets and your own tables on your own connections,
      schema-qualifying target names.
    • trellis::migrate now takes only &Config.
  • Added:

    • Trellis::schema_dump, Trellis::filter_schema_dump (and the
      BlockingTrellis and start_* forms), Config::libpq_environment;
    • SchemaDump, FanOutWarning, ExtremeIndexGap, OtherVersionLive,
      OtherProcess, BelowCatalogFloor, OneToOneBuildStep;
    • ErrorCode variants for version_handover and version_floor;
    • CaptureFailureKind::Unknown;
    • DefinitionStatus and CaptureFailure fields.

    These structs and enums are #[non_exhaustive].

  • Removed validation errors: UnconstrainedNumericAggregate,
    ChainedNumericAggregate, StarJoinDisabled (#1816).

Ruby (trellis-pg) and Elixir (trellis_pg)

  • New error codes: version_handover (Trellis::VersionHandoverError,
    :version_handover) and version_floor (Trellis::VersionFloorError,
    :version_floor). A binding older than 0.2.0 maps them to unknown.
  • New status values: floor, version_handover (VersionHandover,
    OtherProcess), below_catalog_floor (BelowCatalogFloor),
    extreme_index_gaps (ExtremeIndexGap), build_wait_xid, and join
    (JoinStatus, HiddenTable, PartialsWarning, FanOutWarning,
    JoinBuildStep).
  • JoinStatus carries fan_out_warnings, a list (#1816) with one entry per joined position past the threshold, in
    position order. Each FanOutWarning has position, and JoinBuildStep
    has position. No released version has either field.
  • Schema dumps:
    • Ruby Trellis::Instance#schema_dump and #filter_schema_dump; the
      Rails hooks dump the new format and run migrate on load.
    • Elixir schema_dump/1, filter_schema_dump/2, and mix trellis.load.
      mix trellis.dump runs pg_dump itself.
    • dump_definitions_sql and Trellis.StructureDump.append/2 still write
      the older format.

CLI (trellis)

  • New commands: trellis dump, trellis restore.
  • trellis status output changes:
    • Each definition line gains floor=<version> between status= and
      created_at=. Scripts that parse the line by position need updating.
    • A Standing by: line appears above the definitions while another
      version is live or this binary is below the catalog floor.
    • A paused definition's message lists every pause reason and what
      RESUME would do.
    • New warning lines: a MIN/MAX aggregate's missing source index, and a
      1-1 JOIN's fan-out (… rows of the FROM table share join key …; with
      #1816 there is one line per position, at joined position N).
    • A 1-1 JOIN's build step is shown.
  • trellis run prints trellis standing by: … while it waits, and
    … migrated, taking over when it takes over.

Benchmarks

Star 1-1 JOIN (#1783). Logbook 20261108T232301-a-bench and
20261108T233402-a-bench. Run on tmpfs (CPU only), with 1,000,000-row
fan-outs and 200,000-row root passes, uncontended:

  • The R-entry lock, two-table JOIN (pre-star control vs main):
    • fan-out: 96.3k → 91.5k rows/s, +5.2% time;
    • WAL: 344 → 515 B per fanned-out row (+171 B);
    • root changes: unchanged (35.3k → 36.0k rows/s).
  • Each added table:
    • fan-out: about +0.4 µs and +8 B of WAL per row, independent of the
      fan-out position (91.3k rows/s at 2 tables, 81.3k at 5);
    • root change: about +4 µs per row and 240–370 B of WAL (35.4k rows/s at
      2 tables, 24.5k at 5), sublinear, with no cliff at 5 tables.

SUM/AVG over numeric (#1120) gate. Logbook
20261108T144709-b-bench, a clean ABBAAB against main 7e6ebf3, pinned to
cores 0–5 and 8–13. Every measure is within noise of main:

Measure main 0.2.0 change
Aggregate, 400 groups numeric(20,2), rows/s 177.2k / 180.9k / 205.0k 178.2k / 178.8k / 182.2k
Aggregate, 40,000 groups, rows/s 79.4k / 89.1k / 90.5k 73.9k / 80.8k / 90.6k
40,000 groups, uncontended runs 89.1k / 90.5k, 36.8 µs pg CPU/row 90.6k, 36.8 µs pg CPU/row
40,000 groups, WAL per row 796–811 B 790–808 B
JOIN --numeric, fact page apply median 0.509 / 0.588 / 0.631 s 0.605 / 0.608 / 0.676 s
JOIN --numeric, fresh build 5.12–5.18 s 5.03–5.28 s

Earlier rounds measured this JOIN fact page at +14% (20261108T115608-b-bench,
20261108T133535-b-bench). That was fixed before merge.

1-1 JOIN fan-out (#1580). A change of b cost 7 to 18 µs per fanned-out
row, because each batch hashed all of R. It now probes R by key:

  • 3.7–4.2 µs/row from 100k to 5M fanned-out rows;
  • 5.0 µs/row for a 10k fan-out beside 1M other rows (was 19.1);
  • logbook 20261101T122436-a-bench and 20261101T134746-a-bench.

Generative and conformance sweeps

  • Expression conformance:
    • 4 segments (20261108T080641-g-sweep to 20261108T123504-g-sweep) found
      divergences from Postgres in constant folding, fixed by #1786, #1797 and
      #1803 (define's folding mirror was then removed by #1837, so these
      constant cases are no longer refusals).
    • At 293c581e, 3 segments passed 811 million generated expressions with no
      divergence (20261108T134707-g-sweep, 20261108T150400-g-sweep,
      20261108T160447-g-sweep).
  • 1-1 JOIN tier (#1546, #1709): 19 planted bugs, with the in-run
    hidden-state invariant on and off.
  • Star tier (#1781): the reach sweep (20261108T190314-b-sweep) found
    #1814 on its first case. That bug is fixed in this release, and the
    sweep's baseline was then 96 of 96 clean. Five follow-up runs saw no
    failure: three passed and two stopped at their safety timeout.
    • Reach (#1817; seven sweeps, 20261109T110727-b-sweep to
      20261110T092237-b-sweep): test-only engine hooks and star-only generator
      shapes now make every star_* plant the tier runs fire. The 8 plants
      gated before stay gated, 2 more are gated (join1_m_before_j, caught in 11
      of 48 cases; join1_truncate_keeps_r, 17 of 48), and 11 remain known
      misses, each gated by its deterministic pin. The baseline stayed clean. A
      normal build is unchanged.
  • Generative soak for the cut (#1820 to #1824): hours credited per area,
    against the targets of 6, 6, 6, 4 and 3 h: expr 7.79 h, star 7.58 h,
    one2one 7.59 h, agg 5.59 h, lifecycle 4.67 h. The 0.99 h of expr
    run before #1837 is not counted. The credit for star and one2one
    includes 0.83 h each from earlier single-area runs.
    • Segments m1 to m8 (concurrent, 15:43 PT on 9 November to 23:30) ran
      star, one2one, agg and lifecycle on upstream/main 912de4f, and
      expr on the #1837 branch.
    • The final confirmation segment final1 (20261110T105232-g-sweep, 90
      minutes, all five areas concurrently, ref 949240d) was ok in every area:
      expr 1,240,000 + 1,260,000 + 324,760,000 cases over its three
      properties; star 265 and one2one 401 cases; agg 154, 1,071 and 1,990
      cases; lifecycle 1,320, 1,406, 1,055 and 1,484 cases.
    • No failure marker occurred in any segment.
  • 1-1 JOIN start gate for the star (#1462): a roughly 16-hour green
    generative exercise of the 1-1 JOIN tier, 42 runs and 16.3 h on 6–7
    November. One failure (20261106T103920-g-sweep) restarted the count after
    its fix.
  • Nightly generative runs: 9 since the tag: 3 clean and 6 that ended with
    status 1. None was a disk-quota or other infrastructure failure.
    • 2, 3, 5 and 8 November: expr_conformance found three cases where define
      admitted an expression that Postgres rejects at plan time (#1627, #1691,
      #1785). They are fixed by #1628, #1695 and #1786, all in this release
      (define's folding mirror was later removed by #1837).
    • 1 November: self_check_cross_check failed on a test bug, not a product
      bug (#1572, fixed by #1576).
    • 1 to 4 November: a generator bug drew end-to-end divisors that were zero
      for some row, and the failing property then shrank until the round cap.
      That timed out two_instance_noise (1 and 2 November),
      self_check_cross_check (3 and 4 November) and client_lifecycle (4
      November). It was a test bug (#1641, fixed by #1659), and it alone ended
      the 4 November run. concurrent_convergence (1 November) and db_admin
      (2 November) also hit the round cap with no output; their logs don't show
      why. No run since #1659 has timed out.
    • The GitHub nightly (nightly.yml) was red once on a scheduled run in
      that period, on 6 November: a flaky benchmark unit test (#1737, fixed the
      same day). Every other scheduled run succeeded.