kite_sql 0.1.6

Introduction

KiteSQL is a lightweight embedded relational database for Rust, inspired by MyRocks and SQLite and fully written in Rust. It is designed to work not only as a SQL engine, but also as a Rust-native data API that can be embedded directly into applications without relying on external services or heavyweight infrastructure.

KiteSQL supports direct SQL execution, typed ORM models, schema migration, and builder-style queries, so you can combine relational power with an API surface that feels natural in Rust.

Key Features

• A lightweight embedded SQL database fully rewritten in Rust
• A Rust-native relational API alongside direct SQL execution
• Typed ORM models with migrations, CRUD helpers, and a lightweight query builder
• Higher write speed with an application-friendly embedding model
• All metadata and actual data in KV storage, with no intermediate stateful service layer
• Extensible storage integration for customized workloads
• Supports most of the SQL 2016 syntax
• Ships a WebAssembly build for JavaScript runtimes

👉check more

ORM

KiteSQL includes a built-in ORM behind the orm feature flag. With #[derive(Model)], you can define typed models and get tuple mapping, CRUD helpers, schema creation, migration support, and builder-style single-table queries.

Schema Migration

Model changes are part of the normal workflow. KiteSQL ORM can help evolve tables for common schema updates, including adding, dropping, renaming, and changing columns, so many migrations can stay close to the Rust model definition instead of being managed as hand-written SQL.

For the full ORM guide, see src/orm/README.md.

Examples

use kite_sql::db::DataBaseBuilder;
use kite_sql::errors::DatabaseError;
use kite_sql::Model;

#[derive(Default, Debug, PartialEq, Model)]
#[model(table = "users")]
#[model(index(name = "users_name_age_idx", columns = "name, age"))]
struct User {
    #[model(primary_key)]
    id: i32,
    #[model(unique, varchar = 128)]
    email: String,
    #[model(rename = "user_name", varchar = 64)]
    name: String,
    #[model(default = "18", index)]
    age: Option<i32>,
}

fn main() -> Result<(), DatabaseError> {
    let database = DataBaseBuilder::path("./data").build()?;

    database.migrate::<User>()?;

    database.insert(&User {
        id: 1,
        email: "alice@example.com".to_string(),
        name: "Alice".to_string(),
        age: Some(18),
    })?;
    database.insert(&User {
        id: 2,
        email: "bob@example.com".to_string(),
        name: "Bob".to_string(),
        age: Some(24),
    })?;

    let mut alice = database.get::<User>(&1)?.unwrap();
    alice.age = Some(19);
    database.update(&alice)?;

    let users = database
        .select::<User>()
        .filter(User::email().like("%@example.com"))
        .and_filter(User::age().gte(18))
        .order_by(User::name().asc())
        .limit(10)
        .fetch()?;

    for user in users {
        println!("{:?}", user?);
    }

    // ORM covers common model-centric workflows, while `run(...)` remains available
    // for more advanced SQL that is easier to express directly.
    let top_users = database.run(
        r#"
        select user_name, count(*) as total
        from users
        where age >= 18
        group by user_name
        having count(*) > 0
        order by total desc, user_name asc
        limit 5
        "#,
    )?;

    for row in top_users {
        println!("aggregated row: {:?}", row?);
    }

    Ok(())
}

👉more examples

• hello_word
• transaction

WebAssembly

• Build: wasm-pack build --release --target nodejs (outputs to ./pkg; use --target web or --target bundler for browser/bundler setups).
• Usage:

import { WasmDatabase } from "./pkg/kite_sql.js";

const db = new WasmDatabase();
await db.execute("create table demo(id int primary key, v int)");
await db.execute("insert into demo values (1, 2), (2, 4)");
const rows = db.run("select * from demo").rows();
console.log(rows.map((r) => r.values.map((v) => v.Int32 ?? v)));

• In Node.js, provide a small localStorage shim if you enable statistics-related features (see examples/wasm_index_usage.test.mjs).

Python (PyO3)

• Enable bindings with Cargo feature python.
• Constructor is explicit: Database(path); in-memory usage is Database.in_memory().
• Minimal usage:

import kite_sql

db = kite_sql.Database.in_memory()
db.execute("create table demo(id int primary key, v int)")
db.execute("insert into demo values (1, 2), (2, 4)")
for row in db.run("select * from demo"):
    print(row["values"])

TPC-C

Run make tpcc (or cargo run -p tpcc --release) to execute the benchmark against the default KiteSQL storage.
Run make tpcc-dual to mirror every TPCC statement to an in-memory SQLite database alongside KiteSQL and assert the two engines return identical results; this target runs for 60 seconds (--measure-time 60). Use cargo run -p tpcc --release -- --backend dual --measure-time <secs> for a custom duration.

• i9-13900HX
• 32.0 GB
• KIOXIA-EXCERIA PLUS G3 SSD
• Tips: TPC-C currently only supports single thread

All cases have been fully optimized.

<90th Percentile RT (MaxRT)>
   New-Order : 0.002  (0.005)
     Payment : 0.001  (0.013)
Order-Status : 0.002  (0.006)
    Delivery : 0.010  (0.023)
 Stock-Level : 0.002  (0.017)
<TpmC>
27226 Tpmc

👉check more

Roadmap

• Get SQL 2016 mostly supported
• LLVM JIT: Perf: TPCC

License

KiteSQL uses the Apache 2.0 license to strike a balance between open contributions and allowing you to use the software however you want.

Contributors