razeri_plugin_contract/
lib.rs

1// Copyright (C) 2026 Gabriel Shea
2// Licensed under either of the Apache License, Version 2.0 or the MIT
3// license, at your option.
4
5#![warn(missing_docs)]
6
7//! # razeri-plugin-contract
8//!
9//! **The contract a Razeri dialect plugin is written against.**
10//!
11//! This crate and `razeri-plugin-api` are the two open crates in Razeri's
12//! workspace. Everything a plugin author needs in order to *describe* and
13//! *render* a database platform lives here; nothing else does. It depends on
14//! `serde` and on nothing else at all, which is what lets a plugin be built,
15//! published and consumed outside this repository.
16//!
17//! ## What is in here
18//!
19//! **The rendering hierarchy** — ten traits, layered so that a new dialect
20//! implements four required methods and inherits ANSI-standard behaviour for
21//! the rest:
22//!
23//! 1. [`SqlRenderer`] — core SQL rendering (the four required methods)
24//! 2. [`ExpressionRenderer`] — expressions, with ANSI defaults
25//! 3. [`DdlRenderer`] — DDL, with ANSI defaults
26//! 4. [`DmlRenderer`] — DML, with ANSI defaults
27//! 5. [`ProcedureRenderer`] — stored procedures and functions
28//! 6. [`FormulaRenderer`] — formulas, with ANSI defaults
29//! 7. [`TaskRenderer`] — scheduled tasks
30//! 8. [`ReplicationRenderer`] — data extraction, loading and key-function deployment
31//! 9. [`StorageRenderer`] — partitioning, compression and index strategy
32//! 10. [`DialectCapabilities`] — what the platform's SQL can and cannot do
33//!
34//! **The vocabulary those traits speak**: [`DataType`] and [`DataTypeRef`], the
35//! [`storage_strategy::StoragePlan`] a [`StorageRenderer`] translates, the
36//! [`StoragePlatform`] a storage plugin names, and [`DialectFamily`], the
37//! platform's own identity.
38//!
39//! **The decisions a dialect states rather than a core crate deciding for it**,
40//! starting with [`SidSpelling`] — how this engine spells a surrogate key —
41//! and continuing with [`ProcedureForm`] and [`ScalarFunctionForm`], the
42//! routine grammars it speaks, [`MergeShape`], how it upserts, and
43//! [`EvolutionAnswers`], what it keeps when a table that already holds rows
44//! changes shape.
45//!
46//! **The surrogate key's composition** — [`sid`] turns a [`SidSpelling`] into
47//! the key expression an engine runs. It is here rather than in the product
48//! because a dialect author who cannot render their own key expression cannot
49//! run it either, and *"the same key on every engine"* is then a claim nobody
50//! outside this repository can check.
51//!
52//! **The named routine grammars, spelled** — [`routine_render`]. A dialect
53//! whose engine has stored procedures in a grammar of its own renders the whole
54//! `CREATE` itself, and *"PL/pgSQL with one tweak"* used to mean writing the
55//! whole thing from nothing. These three functions write out the grammar a
56//! dialect is nearly the same as, so it can start there and say what differs.
57//!
58//! ## What is deliberately not in here
59//!
60//! Razeri's design model, and the renderers that turn it into Razeri's own
61//! output. A plugin says what its engine spells; Razeri composes. That division
62//! is why one contract crate can be open while the product is not.
63//!
64//! The routine grammars are the one thing on both sides of that line, and they
65//! are here because they belong to the engines rather than to Razeri's design: a
66//! plugin author who cannot read the grammar next to theirs has to guess at it.
67
68pub mod agnostic;
69pub mod capabilities;
70pub mod constraint_enforcement;
71pub mod data_type;
72pub mod dialect_family;
73pub mod evolution;
74pub mod formula_renderer;
75pub mod merge_shape;
76pub mod procedure_log_level;
77pub mod renderer;
78pub mod replication;
79pub mod routine_form;
80pub mod routine_render;
81pub mod routine_spec;
82pub mod sid;
83pub mod sid_spelling;
84pub mod storage_platform;
85pub mod storage_renderer;
86pub mod storage_strategy;
87pub mod task_renderer;
88
89pub use agnostic::*;
90pub use capabilities::*;
91pub use constraint_enforcement::*;
92pub use data_type::{DataType, DataTypeRef};
93pub use dialect_family::DialectFamily;
94pub use evolution::*;
95pub use formula_renderer::*;
96pub use merge_shape::*;
97pub use procedure_log_level::ProcedureLogLevel;
98pub use renderer::*;
99pub use replication::*;
100pub use routine_form::*;
101pub use routine_render::{
102    render_procedure_as, render_scalar_function_as, render_table_function_as,
103};
104pub use routine_spec::*;
105pub use sid::sid_expression;
106pub use sid_spelling::*;
107pub use storage_platform::StoragePlatform;
108pub use storage_renderer::*;
109pub use task_renderer::*;
razeri_plugin_contract/lib.rs

razeri_plugin_contract/
lib.rs
