Crate persistant_relational 

PersistAnt’s relational kind: a deliberately small trait, no driver.

docs/DESIGN-KINDS.md §3 rule 4 and D1 (C+): the trait runs a statement with parameters, begins a transaction, and reports the dialect and server version. It is not a query builder or a row mapper; a program that wants its own SQL checked at compile time (Humboldt’s sqlx::query!) uses the concrete driver handle the driver crate hands out, not this trait. The trait exists so the key-value adapter, the capability matrix and migrations have one thing to call.

Growth toward statement construction would turn this into Option B (§4.2) and carry its leaks; resist it.

Modules

choose

Stage 4 of backend benchmarking for the relational kind: “best backend for X”, as a ranked list with its evidence. The logic is kind-agnostic and lives in persistant_core::choose; this module supplies what is specific to relational databases: the table of what each backend declares about its durability, the typed way to name a need, and the contract check that makes a candidate.

conformance

Contract tests for the relational kind: what RelationalBackend promises, decided against a real database. Each leaf produces a matrix row, on only when the controls held.

contract

Stage 1 of backend benchmarking for the relational kind: eligibility, pass or fail, nothing else.

migrate_conformance

Contract tests for the migration ledger (Migrates): what it promises, decided against a real database. Each leaf produces a matrix row, on only when the controls held.

speed

Stage 3 of backend benchmarking for the relational kind: speed, as data, with the environment recorded. The rules and the data types are the kind-agnostic ones in persistant_core::bench (only a backend that passes the contract leaf a workload depends on is timed; the rest are listed as excluded, never ranked; a figure carries its environment and the command that re-runs it). This module owns the relational workloads and how they are timed: wall-clock, one statement at a time, from the caller’s side of the trait. A network database includes its round trip.

Structs

MigrateReport

What a successful run did.

Migration

One migration: a version, a description and the SQL text. The text is hashed; changing a migration that has been applied is an error, never a silent re-run.

Redacted

A string that prints as <redacted>; its text comes out only through Redacted::expose.

Row

One result row, columns in select order.

Enums

ConnectionSecret

A connection string that never appears in a Debug print, a log line or an error.

Dialect

The SQL dialect a backend speaks, which decides how a statement is written.

Isolation

The isolation level a transaction asks for. A backend gives the level asked for or a stronger one; which it can actually show is what the rel.isolation.* leaves certify.

MigrateError

Why a migration run stopped.

RelError

Why a relational operation failed, classified so a caller can branch without parsing driver text (Humboldt hand-maps constraint names in at least seven places today). Plain data.

Value

A portable parameter or column value. Deliberately narrow: what a key-value or migration statement needs. A program with richer types uses the driver’s own handle.

Traits

Migrates

A relational backend that keeps a migration ledger.

RelationalBackend

A relational database, as small as it can be.

RelationalTx

A transaction. Statements run inside it are committed or rolled back together.