rok_sqlc/lib.rs
1//! Generate SQLx Rust database modules from SQL schema and query files.
2//!
3//! The stable library API is [`generate`] and the types it takes and
4//! returns ([`Config`], [`Report`], [`Error`]). It does exactly what the
5//! `rok-sqlc generate` command does, so a `build.rs` gets the same files and
6//! the same failures as the CLI:
7//!
8//! ```no_run
9//! // build.rs
10//! fn main() -> Result<(), Box<dyn std::error::Error>> {
11//! println!("cargo::rerun-if-changed=migrations");
12//! let mut config = rok_sqlc::Config::default();
13//! config.schema = vec!["migrations/0001_init.sql".into()];
14//! config.output = "src/db".into();
15//! rok_sqlc::generate(&config)?;
16//! Ok(())
17//! }
18//! ```
19//!
20//! Anything else reachable from this crate is an implementation detail with
21//! no stability promise (see ADR 0012).
22
23mod config;
24mod config_file;
25mod generate;
26mod generator;
27mod output;
28mod report;
29mod schema;
30
31// Implementation details, public only for the `rok-sqlc` binary (`cli`) and
32// this crate's own tests (`parser`, `queries`). Not part of the API; they
33// may change in any release.
34#[doc(hidden)]
35pub mod cli;
36#[doc(hidden)]
37pub mod parser;
38#[doc(hidden)]
39pub mod queries;
40
41pub use config::{Config, Conventions, Derive, Extractor, IdGeneration, RelationshipChange};
42pub use report::{Error, QueryFailure, RefusedFile, Report, Result, TableFailure};
43
44/// Generates database modules as described by `config`.
45///
46/// On success the [`Report`] lists the files written, the files already up
47/// to date, the refusals of a dry run, and the tables and queries skipped
48/// under [`Config::lenient`]. Unsupported tables or queries (unless lenient)
49/// and refused files fail the run before anything is written;
50/// [`Error::report`] then says what was known when the run stopped.
51///
52/// After a successful run, stale files (generated files no longer in the
53/// plan) are removed and listed in [`Report::stale`]. With
54/// [`Config::check`] nothing is written or removed; any drift (missing,
55/// changed, or stale files) fails the run, and the report lists it.
56pub fn generate(config: &Config) -> Result<Report> {
57 generate::generate(config)
58}