Start here

Choose your path

All readers Three ways through these docs. Pick the one that matches the question you arrived with.

Trellara is a verification and operations layer above PostgreSQL logical replication. It is not a replacement for it. These docs are organised around three questions, because in practice everyone arrives with one of them.

Evaluator

Is this safe to point at my database?

You want to know what it touches, what it installs, and what the first command can do before you run anything. About twelve minutes, and it writes nothing.

trellara-check $POSTGRES_URL Developer

What may I assume about the stream?

You are building a flow or a consumer and need to know exactly what is guaranteed, what is configurable, and where the protocol fails closed.

docs/DESIGN.md Operator

What do I need before this runs on call?

The production configuration gate, the Kafka contract, secrets, the health endpoints and the metric names — then quarantine and reseed for when it breaks.

trellara status --view diagnostics

What exists today

Being direct about this up front saves you the click. Trellara is pre-1.0. Start here and Concepts are complete and current. Operations has three of its eight pages — production deployment, security and secrets, and monitoring and alerts — because those three describe contracts the code enforces today. The other five need operating experience that does not exist yet, and writing them from imagination would be worse than leaving them out. Build on Trellara has the protocol specification; the conformance suite it should sit beside has not been built. Reference is generated from the repository by tools/gen_reference.py — the CLI definitions, the config structs, the metric constants and the protobuf schema — so those six pages cannot drift from the code without the generator changing too. The error catalog is the one entry still missing, because it has no single source in the code to generate from yet. Everything unwritten is dimmed in the sidebar rather than stubbed with a placeholder page.

The honest inventory of what has and has not been established lives on the evidence table. Read it before you plan around anything here.

How the docs are shaped

Section	Form	Assumes
Start here	Tutorial — one managed path	Nothing. The author owns your success.
Concepts	Explanation — why it works this way	You have read a replication doc before.
Operations	How-to — branching, task-shaped	Competence. You know what you are trying to do.
Build on Trellara	Reference + explanation	You are writing code against the protocol.
Reference	Generated from the code, exhaustive, dry	You are looking up one specific thing.
Trust and evidence	Artifacts, not prose	You are being asked to justify a choice.

A tutorial and a how-to are never mixed. A tutorial has one path and no branches; a how-to assumes you can handle branches and shows you all of them. Mixing the two produces a document that fails both readers.

A note on one word

These docs never say “the Trellara operator.” That phrase collides with the Kubernetes sense of the word, and Trellara does not ship one. Operator here always means the person on call.