Repository navigation
Trellis 0.2.0
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
ofLEFTandINNERjoins in a typical start pattern.MIN/MAXwork in plainGROUP BYaggregates, backed by a required
source index.SUM/AVGover anynumeric, 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
aKEY (…)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
andtrellis restorecommands, Rails and Ecto load hooks, and
ADOPT EXISTING TABLEto define into an empty table you already created. - Connection budget. The background pool needs one more connection than in
0.1.0:2N + 6with staging andNdrain threads (was2N + 5),2N + 5
with drain threads only, and2with 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 withTargetNotAdoptable,
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:
- 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_handovererror code.trellis statusprints aStanding by:
line, andtrellis runprintstrellis standing by: …. 0.1.0 keeps
running, and the capture triggers keep staging changes. - 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. - Run
migrate. 0.2.0 adds migrationsV9__worker_versions.sqlthrough
V20__definition_join_tables.sql.trellis runmigrates by itself once
0.1.0 has stopped. An embedded fleet runsmigrate
(bin/rails trellis:migrate, or a release task callingTrellis.migrate!)
in a deploy step after the old processes are gone. While a 0.1.0 process
is live,migraterefuses withversion_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"ororders.order. This covers every word
pg_get_keywords()marksRorT(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 xor1AS x.
Put a space between them. (Confirmed in the pre-#1816 battery run
20261109T071955-e-acceptance. v0.1.0 accepted1ASand refused0x1,
1e,1.5e3xand1_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
liveand 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,falseornullread 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 namednullstayliveand equal Postgres's reading of the
column through updates, inserts and deletes, withself_checkclean. 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)readstotal. 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 TRANSFORMstores 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.orderis fine), a reserved word as a
GROUP BYorKEY (…)column, and a reservedJOINqualifier; - 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")).
- names over 63 bytes after folding (
TRUE,FALSEandNULLare 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
INCLUDEcolumns (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 areNOT NULLorNULLS NOT DISTINCT), its
columns are written into the stored definition asKEY (…). The
definition keeps running, andstatus()and schema dumps show the new
text. For a 1-1 transform, plain orJOIN, 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; orDROP TRANSFORMand define it again with a validKEY (…).
- If that index qualifies as a key now (valid, not deferrable, not partial,
- 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 (…)), thenRESUME.
OrDROP TRANSFORMand define it again with aKEY (…)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.migraterestores the queued definitions, unbuilt,
and the worker builds them. - A
structure.sqlwritten by 0.1.0 still loads as it did. It carries
Trellis's schema and the catalog rows. The battery'sstructurestep
covers that format. v0.1.0 has noschema_dumpcall, 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
migrateafterdb:schema:load,
db:prepare,db:setupandmaintain_test_schema!. A file loaded another
way (psql -f) needsbin/rails trellis:migrateafterwards. - Elixir: add the load alias next to the dump alias:
["ecto.dump": "trellis.dump", "ecto.load": "trellis.load"]. Without it, a
database built bymix ecto.loadfrom a new-format file has its targets
but no transforms untilTrellis.migrate/1runs. - A dump that fails after
pg_dumphas 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 withversion_floor. - A definition above the running release is paused without being parsed,
and the rest keep running.DROPof it refuses. - Stored values a newer release wrote (statuses, kinds, cursor tags,
partition trees) pause the definition instead of being misread.
- A release below the catalog floor stands by, and its state-changing
- New page:
upgrading and rolling back.
Operations and observability
- A paused transform's
capture_failure:errorlists every reason it is paused for and whatRESUMEwould do
now, kept current by the staging worker's pass;reasonsandresume_outcomecarry 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_pathto Trellis's own schema only, so a
user function or operator inpublicor 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.
- Trellis sessions set
- A lock wait on a catalog statement now reports the retryable
timeout
code instead ofinternal. - CI tests PostgreSQL 15, 16, 17 and 18.
Breaking and changed API
Rust (trellis-pg)
-
Removed:
Trellis::pool(),Pool,PooledClientandTransactionBuilder.
Read targets and your own tables on your own connections,
schema-qualifying target names.trellis::migratenow takes only&Config.
-
Added:
Trellis::schema_dump,Trellis::filter_schema_dump(and the
BlockingTrellisandstart_*forms),Config::libpq_environment;SchemaDump,FanOutWarning,ExtremeIndexGap,OtherVersionLive,
OtherProcess,BelowCatalogFloor,OneToOneBuildStep;ErrorCodevariants forversion_handoverandversion_floor;CaptureFailureKind::Unknown;DefinitionStatusandCaptureFailurefields.
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) andversion_floor(Trellis::VersionFloorError,
:version_floor). A binding older than 0.2.0 maps them tounknown. - New status values:
floor,version_handover(VersionHandover,
OtherProcess),below_catalog_floor(BelowCatalogFloor),
extreme_index_gaps(ExtremeIndexGap),build_wait_xid, andjoin
(JoinStatus,HiddenTable,PartialsWarning,FanOutWarning,
JoinBuildStep). JoinStatuscarriesfan_out_warnings, a list (#1816) with one entry per joined position past the threshold, in
position order. EachFanOutWarninghasposition, andJoinBuildStep
hasposition. No released version has either field.- Schema dumps:
- Ruby
Trellis::Instance#schema_dumpand#filter_schema_dump; the
Rails hooks dump the new format and runmigrateon load. - Elixir
schema_dump/1,filter_schema_dump/2, andmix trellis.load.
mix trellis.dumprunspg_dumpitself. dump_definitions_sqlandTrellis.StructureDump.append/2still write
the older format.
- Ruby
CLI (trellis)
- New commands:
trellis dump,trellis restore. trellis statusoutput changes:- Each definition line gains
floor=<version>betweenstatus=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
RESUMEwould do. - New warning lines: a
MIN/MAXaggregate's missing source index, and a
1-1JOIN'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.
- Each definition line gains
trellis runprintstrellis standing by: …while it waits, and
… migrated, taking overwhen 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.
- fan-out: about +0.4 µs and +8 B of WAL per row, independent of the
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-benchand20261101T134746-a-bench.
Generative and conformance sweeps
- Expression conformance:
- 4 segments (
20261108T080641-g-sweepto20261108T123504-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).
- 4 segments (
- 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-sweepto
20261110T092237-b-sweep): test-only engine hooks and star-only generator
shapes now make everystar_*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.
- Reach (#1817; seven sweeps,
- Generative soak for the cut (#1820 to #1824): hours credited per area,
against the targets of 6, 6, 6, 4 and 3 h:expr7.79 h,star7.58 h,
one2one7.59 h,agg5.59 h,lifecycle4.67 h. The 0.99 h ofexpr
run before #1837 is not counted. The credit forstarandone2one
includes 0.83 h each from earlier single-area runs.- Segments
m1tom8(concurrent, 15:43 PT on 9 November to 23:30) ran
star,one2one,aggandlifecycleonupstream/main912de4f, and
expron the #1837 branch. - The final confirmation segment
final1(20261110T105232-g-sweep, 90
minutes, all five areas concurrently, ref 949240d) was ok in every area:
expr1,240,000 + 1,260,000 + 324,760,000 cases over its three
properties;star265 andone2one401 cases;agg154, 1,071 and 1,990
cases;lifecycle1,320, 1,406, 1,055 and 1,484 cases. - No failure marker occurred in any segment.
- Segments
- 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_conformancefound 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_checkfailed 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 outtwo_instance_noise(1 and 2 November),
self_check_cross_check(3 and 4 November) andclient_lifecycle(4
November). It was a test bug (#1641, fixed by #1659), and it alone ended
the 4 November run.concurrent_convergence(1 November) anddb_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.
- 2, 3, 5 and 8 November: