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.

SweepReport

What a sweep did.

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.

SweepError

Why a sweep did not run or did not finish.

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.

Functions

sweep

Delete rows of table whose column is less than cutoff, at most batch per statement, for at most max_batches statements. Batches, concurrent writers, NULL and naming rules are in the header of this file (sweep.rs).