Cornucopia

Generate type-checked Rust from your SQL

Note

Cornucopia 1.0 merged the Clorinde fork back into the original project, adopting its rewritten codegen, expanded capabilities, and accumulated fixes. Huge thanks to @beanpuppy and the Clorinde contributors for their work. If you are upgrading from Cornucopia 0.9.x, see the migration guide.

Cornucopia 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 Cornucopia 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 Cornucopia by reading the book, or you can get a quickstart by looking at the examples.

Key Features

• Type Safety - Catch SQL errors at compile time 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 cornucopia

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 cornucopia, then you can import it into your project after adding it to your Cargo.toml:

cornucopia = { path = "./cornucopia" }

And use the generated crate in your code:

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

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

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

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.

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.