# Trellis v0.1.0-alpha - API Reference ## Modules - [Trellis](Trellis.md): Embedded Trellis for Elixir: define streaming transforms over Postgres tables from the BEAM, through the `trellis` Rust crate itself (`docs/decisions/0010-embeddable-clients.md`). - [Trellis.Applied](Trellis.Applied.md): What `Trellis.apply/2` did, one shape per statement form - [Trellis.BackfillFailure](Trellis.BackfillFailure.md): A build that keeps failing: how many attempts have failed, the latest error, and when it is tried again. It retries on its own, except that a build failing for a reason no row explains pauses the transform after a few attempts (`next_attempt_at` is then when it paused). Fix the cause, resume a paused transform, and the next attempt goes through. - [Trellis.CaptureFailure](Trellis.CaptureFailure.md): Why capture of `source_table` is broken, or why the drain (or a build's merge) halted on the transform: `kind` is `:capture`, `:halt` or `:disruption`, `error` is a sentence naming the cause, `columns` the columns it is about (empty when it isn't about a column, and for a halt), and `detected_at` when it was first found. - [Trellis.CaptureWait](Trellis.CaptureWait.md): What a transform's capture waits on: the staging worker's install, widen or uninstall (`operation`) of the capture triggers on `table` needs `lock_mode`, and another session holds or is queued for a conflicting lock. `blockers` has one line per such session. Nothing cancels them; the wait ends when they let go. - [Trellis.Config](Trellis.Config.md): The configuration a handle connected with, as `Trellis.config/1` returns it: `connect/1`'s `:schema` and `:target_schema`, and the connection pool's size cap and how long a call waits for a free connection. - [Trellis.CorrectingNode](Trellis.CorrectingNode.md): A partition of a partitioned source a transform is being corrected for, as `Trellis.status/2` reports it: the schema-qualified `node`, when the staging worker queued its correction (`since`), and the keys still to re-derive (`keys_remaining`, `nil` until the correction has counted them; an estimate while it reads the node's own rows). - [Trellis.DefinitionSummary](Trellis.DefinitionSummary.md): A registered transform definition, as `Trellis.definitions/1` lists it. - [Trellis.Divergence](Trellis.Divergence.md): One thing `Trellis.self_check/3` found out of step, by `kind` - [Trellis.DrainFailure](Trellis.DrainFailure.md): A drain page that keeps failing with nothing charged or paused, as `Trellis.status/2` and `Trellis.self_check/3` report it: the segment whose page fails (`seg_seq`), the qualified source tables it holds changes to (`tables`), the latest failure's `error` and its `sqlstate` (`nil` when it didn't come from Postgres), when a drain first and last failed on it (`since`, `last_seen`), and how many drain passes have (`attempts`). - [Trellis.HeldKeys](Trellis.HeldKeys.md): The keys a transform holds in quarantine, as `Trellis.status/2` and `Trellis.self_check/3` report them: how many (`count`), and when the one held longest was last poisoned (`oldest_poisoned_at`). - [Trellis.LogBridge](Trellis.LogBridge.md): Forwards the engine's log lines to `Logger`. - [Trellis.Metrics](Trellis.Metrics.md): The engine's metrics, in Prometheus text exposition format: the Rust crate's `trellis::Metrics::render_prometheus` (`docs/decisions/0009-observability-decisions.md`). - [Trellis.Migration](Trellis.Migration.md): Trellis statements in an Ecto migration, so a transform is defined, and dropped, the way the tables it reads are created. - [Trellis.PoisonEntry](Trellis.PoisonEntry.md): One source row the apply path gave up on, as `Trellis.poisoned_since/2` lists it: the `transform` it's held for (every other transform reading the row keeps applying it), its fully-qualified `src_table`, its `key` as Trellis renders it, the error that poisoned it, and when. - [Trellis.PoisonSample](Trellis.PoisonSample.md): One quarantined source row, as `Trellis.sample_quarantined/3` pages them: its fully-qualified `src_table`, its `key` as Trellis renders it, and the error it failed with. - [Trellis.QuarantineEntry](Trellis.QuarantineEntry.md): One target's quarantine state, as `Trellis.quarantined/1` lists it and `Trellis.quarantine_status/2` reports it. - [Trellis.SamplePage](Trellis.SamplePage.md): One page of `Trellis.sample_quarantined/3`, ordered by `(src_table, key)`. - [Trellis.SelfCheckJob](Trellis.SelfCheckJob.md): A background check of a target table, as `Trellis.self_check/3` starts it and `Trellis.self_check_job/2` reads it back. - [Trellis.SelfCheckReport](Trellis.SelfCheckReport.md): What a finished `Trellis.self_check/3` job found auditing the whole of a target table against a fresh recompute of its definition from the source. - [Trellis.SourceIndexGap](Trellis.SourceIndexGap.md): A source index a `GROUP BY` or `JOIN` target needs and lacks, as `Trellis.status/2` reports it: the qualified `table`, the `columns` the index should lead with, the part of the definition that needs it (`role`: `:group_by` for the `GROUP BY` columns, `:join_from` or `:join_joined` for a `JOIN`'s `ON` columns on its from or joined side), whether the transform opted out with `WITHOUT SOURCE INDEX` (`opted_out`), and a `create index` statement to run (`fix`). Trellis doesn't create indexes on your tables. - [Trellis.Status](Trellis.Status.md): Where a transform is in its lifecycle, as `Trellis.status/2` reports it. - [Trellis.StructureDump](Trellis.StructureDump.md): Appends Trellis's definitions to the structure file `mix ecto.dump` writes, so `mix ecto.load` builds a database that has its transforms. - [Trellis.TestSupport](Trellis.TestSupport.md): Helpers for a test suite that loads fixtures or bulk data into tables Trellis captures. Call them from test code only. - Exceptions - [Trellis.Error](Trellis.Error.md): An error from Trellis: a stable `code` and the engine's message, and nothing else (ADR-0010 decision 4). - [Trellis.TestSupport.ResumeRefused](Trellis.TestSupport.ResumeRefused.md): Raised by `Trellis.TestSupport.resume_capture_disruptions!/2` when a `RESUME` is refused or a resumed definition pauses again. `refused` maps each such target (`"schema.table"`) to the reason. Those definitions stay paused; every other disrupted definition was resumed, and waited for, before this is raised. ## Mix Tasks - [mix trellis.dump](Mix.Tasks.Trellis.Dump.md): Runs `mix ecto.dump` and appends the repo's Trellis definitions to the structure file it wrote, so `mix ecto.load` builds a database that has its transforms (see `Trellis.StructureDump`).