Expand description
Generate Rust models and mappers from a live PostgreSQL schema.
iridium-proto reads the Postgres catalogs and writes the Rust you
would otherwise write by hand: a struct per table, the Rust enums
behind its enum types, and a repository that runs the queries. It is
primarily a command-line tool, proto, with the library exposed so the
same work can be done from a build script or a test.
§The command
proto model shop.product --pyo3 # one model, to stdout
proto mapper shop.product # its repository
proto schema shop --out-dir src/model
proto database --out-dir src/model --mapper-dir src/mapper --mappers
proto schema shop --mappers --operations \
--out-dir src/model --mapper-dir src/mapper --operation-dir src/operation
proto list [schema] # what is there
proto config # what proto resolvedOutput goes to stdout unless a destination is given, which is what
makes :%!proto model shop.product work from an editor buffer.
§Generated code you can live in
A regeneration corrects a file rather than replacing it. Proto renders what the file should say, parses both that and what is on disk, and edits only where they disagree — so a field whose type no longer matches its column is replaced, and the comment a developer wrote above it stays above it.
The database is right about the parts it owns: names, types,
nullability. Everything else in the file is yours, including the
order, since fields are matched by name. Mappers work the same way a
method at a time: proto owns the ones it derives from the catalog and
nothing else in the block. Nothing has to be marked to be spared,
because nothing is rewritten. See reconcile.
§What comes out
A table becomes a struct. NOT NULL columns get a bare type and
everything else gets Option; column comments become doc comments.
#[derive(sqlx::FromRow, Debug, Clone, Serialize, Deserialize)]
pub struct Product {
pub id: Uuid,
pub slug: String,
pub status: ProductStatus,
pub price: Option<Decimal>,
}Its mapper owns the SQL:
let products = ProductMapper::new(&pool);
let one = products.find_by_slug("dovetail-saw").await?;
let all = products.find_by_org_id(org).await?;§Two places for the SQL
render::Strategy decides where the statements live. Under
Embedded they are in the Rust source.
Under Server they are LANGUAGE sql
functions in a migration render::sql writes, and the mapper only
calls them. Both produce the same Rust API, so the choice is about
where the logic should live, not about how the code is used.
§Using it as a library
introspect reads a table, render turns it into source. Nothing
in render touches a database, so the emitters are testable on their
own.
use iridium_proto::config::Generate;
use iridium_proto::{introspect, render};
use sqlx::PgPool;
let model = introspect::model(pool, "shop", "product").await?;
let generate = Generate::default();
let opts = render::Opts {
generate: &generate,
pyo3: false,
inputs: true,
model_path: "crate::model".to_string(),
strategy: render::Strategy::Embedded,
target: "dev",
command: "proto model shop.product".to_string(),
name_override: None,
bridge_path: "super::python".to_string(),
query_path: "super::query".to_string(),
mapper_path: "crate::mapper".to_string(),
};
print!("{}", render::model::model_file(&model, &opts, None).code);
print!("{}", render::mapper::mapper_file(&model, &opts).code);§Configuration
Database targets and generation defaults come from a TOML file, read
from $PROTO_CONFIG, else $XDG_CONFIG_HOME/proto/proto.toml, else
~/.config/proto/proto.toml. See config for the shape of it.
§Reading on
The README is the pitch and the workflow; the reference is a page per
subject in the repository’s docs/ directory — configuration and
commands, models, mappers, children, operations, type mapping,
keeping in step, editing generated code, safety, and pyo3:
https://github.com/iridiumdesign/iridium-proto/tree/main/docs.
Modules§
- config
- XDG-style configuration.
- error
- What can go wrong, and what proto says about it.
- inspect
- Reading generated code back as structure rather than as text.
- introspect
- Reads the Postgres catalogs. Everything proto knows about a table comes from here: columns in ordinal order, nullability, comments, the primary key, and the enum and composite types the columns reference.
- manifest
- The consuming crate’s
Cargo.toml, and what the generated code needs from it. - naming
- Identifier conversions. Deliberately dumb and predictable: a table name
is not singularized, it is only re-cased.
member_unitsbecomesMemberUnits, and--nameexists for the times that reads wrong. - output
- Where generated source goes. Default is stdout — that is what makes
:%!proto model shop.productwork from inside an editor. Writing to a path refuses to clobber a file proto did not write. - quoting
- Quoting for generated SQL.
- reconcile
- Bringing an existing file into line with the database, one line at a time.
- render
- Source emission. Nothing in this module talks to a database — output is
a pure function of the catalog data in
crate::introspectplus the options here, which is what makes the renderers testable on their own. - typemap
- Postgres type -> Rust type.