Skip to main content

Crate iridium_proto

Crate iridium_proto 

Source
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 resolved

Output 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_units becomes MemberUnits, and --name exists for the times that reads wrong.
output
Where generated source goes. Default is stdout — that is what makes :%!proto model shop.product work 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::introspect plus the options here, which is what makes the renderers testable on their own.
typemap
Postgres type -> Rust type.