Clorinde

Clorinde generates type-checked Rust interfaces from PostgreSQL queries, with an emphasis on compile-time safety and high performance. It works by preparing your queries against an actual database and then running an extensive validation suite on them. Rust code is then generated into a separate crate, which can be imported and used in your project.

The basic premise is thus to:

1. Write your PostgreSQL queries.
2. Use Clorinde to generate a crate with type-safe interfaces to those queries.
3. Import and use the generated code in your project.

You can learn more about Clorinde by reading the book, or you can get a quickstart by looking at the examples.

[!NOTE] Clorinde is a fork of Cornucopia which enhances the original with an improved architecture and expanded capabilities. Visit the migration guide if you are moving over an existing codebase with Cornucopia.

Key Features

• Type Safety - Catch SQL errors at compile time and get catch errors before runtime with powerful diagnostics.
• SQL-First - Write plain SQL queries, get generated Rust code. No ORMs or query builders, just the SQL you know and love.
• Fast - Performance close to hand-written rust-postgres code.
• Flexible - Works with sync/async code and connection pools.
• PostgreSQL Native - Full support for custom types, enums, and arrays. Leverage PostgreSQL's advanced features without compromise.
• Custom Types - Map database types to your own Rust structs.

Installation

Install with:

cargo install clorinde

Quick Example

Write your PostgreSQL queries with annotations and named parameters:

-- queries/authors.sql

--! insert_author
INSERT INTO authors
    (first_name, last_name, country)
VALUES
    (:first_name, :last_name, :country);

--! authors
SELECT first_name, last_name, country FROM authors;

Generate the crate with clorinde, then you can import it into your project after adding it to your Cargo.toml:

clorinde = { path = "./clorinde" }

And use the generated crate in your code:

use clorinde::queries::authors::{authors, insert_author};

insert_author.bind(&client, "Agatha", "Christie", "England");

let all_authors = authors().bind(&client).all();

for author in all_authors {
  println!("[{}] {}, {}",
    author.country,
    author.last_name.to_uppercase(),
    author.first_name
  )
}

For more examples go to the examples directory, or head over to the book to learn more.

MSRV

This crate uses Rust 2021 edition, which requires at least version 1.62.1.

Prior Art

• sqlc (Go) - Generate type-safe code from SQL
• Kanel (TypeScript) - Generate TypeScript types from Postgres
• jOOQ (Java) - Generate typesafe SQL from your database schema

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.