69 posts tagged with "news"

sea-clickhouse is a ClickHouse client that integrates with the SeaQL ecosystem. It is a soft fork of clickhouse-rs: 100% compatible with all upstream features, with SeaQL's dynamic type and Arrow support added on top. The fork is continually rebased on upstream.

In this blog post we cover:

• Dynamic rows with try_get: fetch query results without defining any schema struct
• Arrow RecordBatch streaming: stream query results as RecordBatches and insert them back into ClickHouse
• SeaORM to ClickHouse: convert SeaORM entities to Arrow and insert into ClickHouse
• Arrow Schema to ClickHouse DDL: derive CREATE TABLE DDL from an Arrow schema, no hand-written SQL

Quick Install​

[dependencies]
# a drop-in replacement of clickhouse
sea-clickhouse = { version = "0.14", features = ["arrow", "chrono", "rust_decimal"] }

Ergonomic dynamic column type with try_get​

The native clickhouse-rs client requires you to define a #[derive(Row)] struct whose field types match the query output exactly:

#[derive(Row, Deserialize)]
struct Reading {
    #[serde(with = "special_deserializer")] // or use a custom deserializer?
    temperature: f64, // f32? f64? depends on the SQL expression
}

let mut cursor = client.query("SELECT ...").fetch::<Reading>()?;

If the struct says f32 but the server returns Float64, you get a runtime deserialization error. For computed columns, ad-hoc queries, or SELECT * on evolving tables, maintaining these structs is fragile.

sea-clickhouse reads the column types from the response metadata and maps them to sea_query::Value automatically:

let mut cursor = client.query("SELECT 1::UInt32 + 1::Float32 AS value").fetch_rows()?;
let row = cursor.next().await?.expect("one row");

// UInt32 + Float32 -> Float64
assert_eq!(row.try_get::<f64, _>(0)?, 2.0);           // by index
assert_eq!(row.try_get::<f32, _>(0)?, 2.0);           // narrower type also works
assert_eq!(row.try_get::<Decimal, _>("value")?, 2.into()); // by column name

try_get coerces at runtime: access by index or column name, request the type you need, and it converts where possible.

Arrow RecordBatch Streaming​

next_arrow_batch(chunk_size) streams query results as Arrow RecordBatches, ready for DataFusion, Polars, Parquet export, or any Arrow consumer.

use clickhouse::Client;
use sea_orm_arrow::arrow::{array::RecordBatch, util::pretty};

let client = Client::default().with_url("http://localhost:18123");

let sql = r#"
    SELECT
        toUInt64(id)                   AS id,
        toDateTime64(recorded_at, 6)   AS recorded_at,
        toInt32(sensor_id)             AS sensor_id,
        toFloat64(temperature)         AS temperature,
        toDecimal128(voltage, 4)       AS voltage
    FROM sensor_data
    LIMIT 1000
"#;

let mut cursor = client.query(sql).fetch_rows()?;
let mut batches: Vec<RecordBatch> = Vec::new();
while let Some(batch) = cursor.next_arrow_batch(100).await? {
    batches.push(batch);
}
pretty::print_batches(&batches).unwrap();

+----+-------------------------+-----------+----------------------+---------+
| id | recorded_at             | sensor_id | temperature          | voltage |
+----+-------------------------+-----------+----------------------+---------+
| 1  | 2026-01-01T13:35:36.736 | 106       | 36.345616831016436   | 3.2736  |
| 2  | 2026-01-01T10:07:38.458 | 108       | 10.122001773336567   | 3.3458  |
| 3  | 2026-01-01T01:15:18.518 | 108       | 35.21406789966149    | 3.1518  |
| 4  | 2026-01-01T05:36:57.017 | 107       | 22.92828141235666    | 3.2016  |
| 5  | 2026-01-01T13:17:36.056 | 106       | -2.082591477369223   | 3.0056  |
| ...                                                                       |
+----+-------------------------+-----------+----------------------+---------+

Those batches can be inserted back into ClickHouse directly:

let mut insert = client.insert_arrow("sensor_data_processed", &batches[0].schema()).await?;
for batch in &batches {
    insert.write_batch(batch).await?;
}
insert.end().await?;

No #[derive(Row)] macros. The Arrow schema carries the type information end-to-end.

SeaORM to ClickHouse​

SeaORM started as an OLTP toolkit, but with Arrow and now ClickHouse support, SeaQL bridges data engineering with data science: your OLTP entities become the source of truth for OLAP pipelines too.

use sea_orm::entity::prelude::*;

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "measurement", arrow_schema)]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub recorded_at: ChronoDateTime,
    pub sensor_id: i32,
    pub temperature: f64,
    #[sea_orm(column_type = "Decimal(Some((38, 4)))")]
    pub voltage: Decimal,
}

Build models, convert to a RecordBatch, and insert:

use sea_orm::ArrowSchema;

let models: Vec<measurement::ActiveModel> = vec![..];

let schema = measurement::Entity::arrow_schema();
let batch = measurement::ActiveModel::to_arrow(&models, &schema)?;

let mut insert = client.insert_arrow("measurement", &schema).await?;
insert.write_batch(&batch).await?;
insert.end().await?;

arrow_schema on the entity derives the Arrow schema at compile time. to_arrow converts a slice of ActiveModels into a RecordBatch. From there, insert_arrow streams the batch into ClickHouse over HTTP. See the full working example.

Arrow Schema to ClickHouse DDL​

ClickHouseSchema::from_arrow derives a full CREATE TABLE statement from any Arrow schema, and exposes a SeaQuery-like fluent API to configure ClickHouse-specific attributes:

use clickhouse::schema::{ClickHouseSchema, Engine};

let mut schema = ClickHouseSchema::from_arrow(&batch.schema());
schema
    .table_name("sensor_readings")
    .engine(Engine::ReplacingMergeTree)
    .primary_key(["recorded_at", "device"]);
schema.find_column_mut("device").set_low_cardinality(true);

let ddl = schema.to_string();
client.query(&ddl).execute().await?;

Generated DDL:

CREATE TABLE sensor_readings (
    id UInt64,
    recorded_at DateTime64(6),
    device LowCardinality(String),
    temperature Nullable(Float64),
    voltage Decimal(38, 4)
) ENGINE = ReplacingMergeTree()
PRIMARY KEY (recorded_at, device)

The full workflow: Arrow -> derive DDL -> create table -> insert batches. Zero hand-written ClickHouse SQL. All examples shown here are available as runnable examples in the repository.

🦀 Rustacean Sticker Pack​

The Rustacean Sticker Pack is the perfect way to express your passion for Rust. Our stickers are made with a premium water-resistant vinyl with a unique matte finish.

Sticker Pack Contents:

• Logo of SeaQL projects: SeaQL, SeaORM, SeaQuery, Seaography
• Mascots: Ferris the Crab x 3, Terres the Hermit Crab
• The Rustacean wordmark

Support SeaQL and get a Sticker Pack!

The Problem: Durability​

Long-running programs crash. When they do, you start over from zero. The fix is checkpointing: periodically save state to a database so the program can resume where it left off. In this tutorial we wire up checkpointing with SeaORM Sync and rusqlite. No async runtime, no handwritten SQL.

The Workload: Pi Spigot​

We need a computation that takes a long time and produces results incrementally. Here we use the Rabinowitz–Wagon pi spigot algorithm¹ as demonstration.

The algorithm computes decimal digits of pi one at a time, using only integer arithmetic. Each iteration mutates the internal state, and may or may not produce a digit. So "I completed iteration N, therefore I have N digits" is not true.

This makes it a good test case for checkpointing. You can't just save the digit count and recompute from there: you need the full internal state.

The State Machine Pattern​

Any computation that can be modeled as a state machine can be made resumable. The recipe:

new()        → initialize fresh state
step()       → advance one iteration, mutating &mut self
finalize()   → flush any buffered output
to_state()   → serialize self into a database row
from_state() → deserialize a database row back into self

step() is the core loop body. Call it repeatedly to drive the computation forward. to_state() and from_state() handle persistence: save the internal state and resume from it later.

The checkpoint frequency is a param you control. Checkpoint every step and you lose almost no work on crash, but pay the IO cost every iteration. Checkpoint every 1000 steps and crashes cost you up to 1000 steps of rework, but the overhead is negligible.

Integrating with SeaORM + rusqlite​

Now let's wire this pattern into a real database. SeaORM 2.0 ships a sync API (crate sea-orm-sync) backed by rusqlite. The API surface is compatible with sea-orm, just without any async.

Step 1: Define the State Entity​

Map every mutable field of the computation to a column:

use sea_orm::entity::prelude::*;
use serde::{Deserialize, Serialize};

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "state")]
pub struct Model {
    #[sea_orm(primary_key, auto_increment = false)]
    pub digits: u32,
    pub boxes: JsonVec,
    pub i: u32,
    pub nines: u32,
    pub predigit: u8,
    pub have_predigit: bool,
    pub count: u32,
    pub result: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, FromJsonQueryResult)]
pub struct JsonVec(pub Vec<u32>);

impl ActiveModelBehavior for ActiveModel {}

digits is the primary key: it identifies which computation this checkpoint belongs to (i.e. "compute 10000 digits of pi"). boxes holds the algorithm's working array as a JSON column via FromJsonQueryResult, since SQLite has no native array type. The rest are scalars: iteration counter, buffered-nine count, the held predigit, and the digits emitted so far.

Step 2: Serialize and Deserialize​

The computation struct itself has no dependency on SeaORM: it uses plain Vec<u32>, u32, String. Two glue functions convert between this struct and the entity model. This keeps the core algorithm pure and testable; the entire persistence layer can be gated behind a feature flag so that the library can work without sea-orm.

The conversion functions:

fn from_state(s: state::Model) -> Self {
    Self {
        digits: s.digits,
        boxes: s.boxes.0,
        nines: s.nines,
        predigit: s.predigit,
        have_predigit: s.have_predigit,
        count: s.count,
        result: s.result,
        start_i: s.i,
    }
}

fn to_state(&self, i: u32) -> state::Model {
    state::Model {
        digits: self.digits,
        boxes: state::JsonVec(self.boxes.clone()),
        i,
        nines: self.nines,
        predigit: self.predigit,
        have_predigit: self.have_predigit,
        count: self.count,
        result: self.result.clone(),
    }
}

Step 3: Checkpoint in a Transaction​

Inside the main loop, periodically save state. The delete-then-insert is wrapped in a transaction so the checkpoint is atomic: either the full state is written or nothing changes.

fn persist_state(&self, db: &DatabaseConnection, i: u32) -> Result<(), DbErr> {
    let txn = db.begin()?;
    state::Entity::delete_by_id(self.digits).exec(&txn)?;
    self.to_state(i + 1).into_active_model().insert(&txn)?;
    txn.commit()?;
    Ok(())
}

Note the i + 1: we save the next iteration index, not the current one. The state has already been mutated by step(), so when the program resumes it should continue from the next iteration, not re-execute the one it just completed.

If the process dies at any point before commit(), SQLite rolls back the transaction automatically. The previous checkpoint remains intact. This is more resilient than writing to a plain JSON file, where a crash mid-write can leave you with a truncated or corrupted file and no valid checkpoint at all.

Step 4: Resume on Startup​

On startup, check for an existing checkpoint. get_schema_builder().sync() creates the table from the entity definition if it doesn't already exist, so there is no need to write CREATE TABLE SQL:

pub fn resume(db: &DatabaseConnection, digits: u32) -> Result<Self, DbErr> {
    db.get_schema_builder()
        .register(state::Entity)
        .sync(db)?;

    match state::Entity::find_by_id(digits).one(db)? {
        Some(state) => Ok(Self::from_state(state)),
        None => Ok(Self::new(digits)),
    }
}

First run: creates the table, starts fresh. Subsequent runs: finds the checkpoint row, reconstructs the computation mid-flight. The calling code doesn't need to distinguish between the two cases.

Putting It Together​

The main loop looks like this:

// initialize states in self

for i in self.start_i..=self.digits {
    self.step();

    if self.count > 0 && self.count % checkpoint_interval == 0 {
        self.persist_state(db, i)?;
    }
}

self.finalize();

The full example including tests is in the SeaORM repository.

Conclusion​

SeaORM Sync with rusqlite is a lightweight combination: a single-file database, no server, no async runtime. You define your state as an entity, and SeaORM handles the SQL. No hand-written queries, no migration files. You stay focused on the core program logic.

The patterns here are reusable. State machine + serialization round-trip + transactional checkpoint: apply them to batch jobs, simulations, data pipelines, or any long-running process that shouldn't have to start over after a crash.

🦀 Rustacean Sticker Pack​

The Rustacean Sticker Pack is the perfect way to express your passion for Rust. Our stickers are made with a premium water-resistant vinyl with a unique matte finish.

Sticker Pack Contents:

• Logo of SeaQL projects: SeaQL, SeaORM, SeaQuery, Seaography
• Mascots: Ferris the Crab x 3, Terres the Hermit Crab
• The Rustacean wordmark

Support SeaQL and get a Sticker Pack!

SeaORM X is a proprietary extension of SeaORM with first-class Microsoft SQL Server support. It covers the same API surface, with the full test suite and examples ported to MSSQL. With SeaORM 2.0, SeaORM X has been rebuilt on top of it: every improvement in the open-source release ships to MSSQL users too.

If you are building enterprise software on SQL Server, you can request commercial access.

What's in SeaORM X​

1. Native MSSQL Driver via SQLz with Connection Pooling​

SeaORM X ships a full ConnectionPool driver for SQL Server (mssql:// URI scheme) built on top of the SQLz/TDS stack. You get the same Database::connect(url) ergonomics as MySQL, PostgreSQL, and SQLite: no separate client setup required.

let db = Database::connect("mssql://user:pass@localhost:1433?trustCertificate=true").await?;

The underlying SQLz pool is a parallel implementation of SQLx's pool architecture applied to SQL Server. It supports the same lifecycle hooks as SQLx:

• after_connect: initialize a freshly opened connection
• before_acquire: validate an idle connection before handing it out
• after_release: clean up before returning a connection to the pool

All standard PoolOptions settings are supported: max_connections, min_connections, acquire_timeout, max_lifetime, idle_timeout, test_before_acquire, etc.

2. Nested Transactions via Savepoints​

SQLz tracks transaction depth as a counter on the connection and maps it to MSSQL's savepoint syntax transparently:

db.transaction(|tx| tx.transaction(|tx2| ...)) gives correct nested rollback semantics: rolling back an inner block unwinds only to the savepoint, leaving the outer transaction intact.

let txn = db.begin().await?;

{
    let txn = txn.begin().await?;
    let _ = bakery::ActiveModel { name: Set("Nested Bakery".to_owned()), .. }.save(&txn).await?;
    assert_eq!(Bakery::find().all(&txn).await?.len(), 3);

    {
        let txn = txn.begin().await?;
        let _ = bakery::ActiveModel { name: Set("Rock n Roll Bakery".to_owned()), .. }.save(&txn).await?;
        assert_eq!(Bakery::find().all(&txn).await?.len(), 4);
        // txn dropped here without commit: rolls back to savepoint
    }
    assert_eq!(Bakery::find().all(&txn).await?.len(), 3);

    {
        let txn = txn.begin().await?;
        let _ = bakery::ActiveModel { name: Set("Rock n Roll Bakery".to_owned()), .. }.save(&txn).await?;
        txn.commit().await?;
    }
    txn.commit().await?;
}

assert_eq!(Bakery::find().all(&txn).await?.len(), 4);
txn.commit().await?;

BEGIN TRAN
  SAVE TRAN _sqlz_savepoint_1
    SAVE TRAN _sqlz_savepoint_2
    ROLLBACK TRAN _sqlz_savepoint_2   -- drop without commit
    SAVE TRAN _sqlz_savepoint_2
    -- (savepoint 2 released implicitly on commit)
  -- (savepoint 1 released implicitly on commit)
COMMIT TRAN

When a Transaction is dropped without an explicit commit, SQLz spawns a local async task to execute ROLLBACK immediately and marks the connection as RollingBack. Any subsequent use of that connection awaits the rollback task before proceeding, making cleanup deterministic rather than deferred to an arbitrary future await point.

3. Automatic Schema Rewriting​

ConnectionTrait gains a get_schema() hook. When a connection is configured with a non-default schema (e.g. dbo, sales), SeaORM X automatically prefixes every outgoing statement with that schema. No manual [schema].[table] boilerplate in application code.

The rewriting is backed by the OverrideTableSchema trait, implemented for every sea-query statement type. Schema rewriting propagates recursively into subqueries, JOINs, and CTE branches.

// specify schema other than dbo
let db = Database::connect(
    "mssql://user:pass@localhost:1433/my_db?currentSchema=my_schema").await?;

let related = cake::Entity::find()
    .has_related(filling::Entity, filling::Column::Name.eq("Marmalade"))
    .all(db)
    .await?;

SELECT [cake].[id], [cake].[name] FROM [my_schema].[cake]
WHERE EXISTS(SELECT 1 FROM [my_schema].[filling]
  INNER JOIN [my_schema].[cake_filling] ON [cake_filling].[filling_id] = [filling].[id]
  WHERE [filling].[name] = 'Marmalade'
  AND [cake].[id] = [cake_filling].[cake_id])

4. OUTPUT Clause for RETURNING​

SeaORM X maps SeaORM's RETURNING semantics to MSSQL's OUTPUT syntax:

• INSERT → OUTPUT INSERTED.*
• DELETE → OUTPUT DELETED.*

Constraint violations (UniqueConstraintViolation, ForeignKeyConstraintViolation) surfacing through the OUTPUT path are caught and returned as typed DbErr variants, not raw driver errors.

5. Automatic IDENTITY_INSERT Handling​

When inserting a model with an explicit primary-key value on an auto-increment column, SeaORM X automatically wraps the statement in SET IDENTITY_INSERT ON/OFF: no manual SQL required.

// From tests/empty_insert_tests.rs
let seaside_bakery = bakery::ActiveModel {
    name: Set("SeaSide Bakery".to_owned()),
    profit_margin: Set(10.4),
    ..Default::default() // id not set: normal insert
};
Bakery::insert(seaside_bakery).exec(db).await?;

let double_seaside_bakery = bakery::ActiveModel {
    id: Set(1), // explicit PK: triggers IDENTITY_INSERT automatically
    name: Set("SeaSide Bakery".to_owned()),
    profit_margin: Set(10.4),
    ..Default::default()
};
let res = Bakery::insert_many([double_seaside_bakery])
    .on_conflict_do_nothing()
    .exec(db)
    .await;
assert!(matches!(res, Ok(TryInsertResult::Conflicted)));

-- Normal insert: no IDENTITY_INSERT
INSERT INTO [bakery] ([name], [profit_margin]) OUTPUT [INSERTED].[id] VALUES ('SeaSide Bakery', 10.4)

-- Explicit PK insert: wrapped automatically
SET IDENTITY_INSERT [bakery] ON;
INSERT INTO [bakery] ([id], [name], [profit_margin]) OUTPUT [INSERTED].[id] VALUES (1, 'SeaSide Bakery', 10.4);
SET IDENTITY_INSERT [bakery] OFF
-- PK conflict → returned as TryInsertResult::Conflicted, not a panic

6. Tuple IN Fallback for MSSQL​

MSSQL does not support tuple value syntax ((c1, c2) IN ((v1, v2), ...)). SeaORM X adds EntityTrait::column_tuple_in(), which expands to (c1 = v1 AND c2 = v2) OR ... when targeting MSSQL.

cake::Entity::find()
    .filter(cake::Entity::column_tuple_in(
        [cake::Column::Id, cake::Column::Name],
        &[(1i32, "a").into_value_tuple(), (2i32, "b").into_value_tuple()],
        DbBackend::MySql,
    ).unwrap())
    .build(DbBackend::MySql)
    .to_string();

-- MySQL: native tuple syntax:
SELECT `cake`.`id`, `cake`.`name` FROM `cake`
WHERE (`cake`.`id`, `cake`.`name`) IN ((1, 'a'), (2, 'b'))

cake::Entity::find()
    .filter(cake::Entity::column_tuple_in(
        [cake::Column::Id, cake::Column::Name],
        &[(1i32, "a").into_value_tuple(), (2i32, "b").into_value_tuple()],
        DbBackend::MsSql,
    ).unwrap())
    .build(DbBackend::MsSql)
    .to_string();

-- MSSQL: automatically expands to AND/OR:
SELECT [cake].[id], [cake].[name] FROM [cake]
WHERE ([cake].[id] = 1 AND [cake].[name] = 'a') OR ([cake].[id] = 2 AND [cake].[name] = 'b')

7. i64 / i32 Type Coercion​

MSSQL returns INT columns as i32 at the wire level. SeaORM X handles the coercion transparently: no schema changes or manual casting required.

8. Schema-First and Entity-First Workflows​

Schema-first: point sea-orm-cli generate entity at an existing MSSQL database and get ready-to-compile Rust entity files.

sea-orm-cli generate entity \
  --database-url "mssql://sa:pass@localhost/AdventureWorksLT2016" \
  --database-schema "SalesLT"

// Generated address.rs
#[sea_orm(schema_name = "SalesLT", table_name = "Address")]
pub struct Model {
    #[sea_orm(column_name = "AddressID", primary_key)]
    pub address_id: i32,
    #[sea_orm(column_name = "AddressLine1")]
    pub address_line1: String,
    pub rowguid: Uuid,
    // ...
}

Entity-first: define entities in Rust and let SeaORM sync the schema to the database. Tables, columns, unique keys, and foreign keys are created in topological order: no manual migration file needed.

// Requires the `schema-sync` feature flag
db.get_schema_builder()
    .register(order::Entity)
    .register(store::Entity)
    .sync(db)
    .await?;

9. execute_unprepared via Raw TDS Batch​

For DDL and migration scenarios, execute_unprepared uses the raw TDS execute_batch path rather than prepared statements. This preserves temp-table visibility across statement batches: a common requirement for MSSQL migration and stored-procedure patterns that break under prepared statement isolation.

10. Built on SeaORM 2.0​

Because SeaORM X tracks the open-source release, all SeaORM 2.0 improvements are available to MSSQL users. Highlights:

New entity format: a dense, readable layout with relations declared inline on the model struct, generated with --entity-format dense:

#[sea_orm::model]
#[sea_orm(table_name = "post")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub user_id: i32,
    #[sea_orm(belongs_to, from = "user_id", to = "id")]
    pub author: HasOne<super::user::Entity>,
    #[sea_orm(has_many, via = "post_tag")]
    pub tags: HasMany<super::tag::Entity>,
}

Smart Entity Loader: automatically chooses JOIN for 1-1 and the data-loader pattern for 1-N, eliminating the N+1 problem in nested queries.

Nested ActiveModel persistence: insert an entire object graph (user → profile 1-1, posts 1-N, tags M-N) in a single .save(db).await? call.

Strongly-typed columns: Cake::COLUMN.name.contains("chocolate") with methods specific to the column type.

Injection-safe raw_sql! macro: use {param} interpolation and {..array} expansion in raw SQL without opening the door to SQL injection.

DerivePartialModel with #[sea_orm(nested)]: select only the fields you need across joins and map them into typed partial structs, preventing overfetching.

Limitations​

SQLz is a purpose-built SQL Server driver, not a full SQLx port. Known gaps:

• No compile-time query checking. SQLx's sqlx::query! macro verifies SQL against a live database at compile time. SQLz has no equivalent; queries are checked at runtime only.
• No custom type encoding/decoding. SQLx supports user-defined Encode/Decode implementations for arbitrary Rust types. SQLz ships a fixed set of supported types (primitives, uuid, Decimal, BigDecimal, chrono, time, serde_json) behind feature flags. Adding a new wire type requires changes inside SQLz itself.

Getting Access​

SeaORM X is a commercial offering for teams that need SQL Server support in Rust without leaving the SeaORM ecosystem. It has been tested against complex schemas including Sakila and AdventureWorks, and is used in production by companies today.

The practical upside for teams already on SeaORM: there is no second API to learn or maintain. Queries, relations, transactions all carry over unchanged. Developers can be productive on day one, and adding SQL Server to an existing multi-database project does not require parallel ORM maintenance or separate migration tooling.

For greenfield projects on legacy MSSQL schemas, the CLI codegen eliminates the mechanical work of writing entity files by hand.

SeaORM X is distributed under a commercial license. To evaluate it or discuss access for your team, request access here.

SeaORM 2.0 adds native Apache Arrow and Parquet support. Derive an Arrow schema directly from your SeaORM entity: no redundant schema definitions, no drift.

Motivation​

Traditional ORMs are built for OLTP. But Rust backends increasingly need to:

• Export data snapshots to object storage (S3, GCS)
• Feed analytical pipelines (DataFusion, Polars, DuckDB)
• Archive time-series rows efficiently in columnar format
• Seed or replicate databases from Parquet files

Arrow is the lingua franca of in-memory columnar data. Parquet is its on-disk counterpart. Both are supported by the entire modern data stack.

The problem: you've already defined your schema as SeaORM entities. Redefining it as an Arrow schema is redundant and error-prone. SeaORM now comes with Arrow support out-of-the-box!

Getting Started​

Enable Arrow support with the with-arrow feature flag:

[dependencies]
sea-orm = { version = "2.0.0-rc", features = ["with-arrow"] }
parquet = { version = "57", features = ["arrow"] }

Suppose you have a sensor data pipeline. You want to archive today's rows to Parquet for downstream analytics.

Arrow Schema Derivation​

Add arrow_schema to the #[sea_orm(..)] attribute on your entity:

use sea_orm::entity::prelude::*;

#[sea_orm::model] // <- new Entity
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "measurement", arrow_schema)] // <- enable Arrow
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub recorded_at: ChronoDateTimeUtc,
    pub sensor_id: i32,
    pub temperature: f64,
    #[sea_orm(column_type = "Decimal(Some((10, 4)))")]
    pub voltage: Decimal,
}

(for compact entity)

#[derive(DeriveEntityModel, DeriveArrowSchema, ..)] // <- extra derive
#[sea_orm(table_name = "measurement")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    ..
}

This derives the ArrowSchema trait on Entity and ActiveModel, exposing three methods:

use sea_orm::ArrowSchema;

// Get the Arrow Schema matching your entity
let schema = measurement::Entity::arrow_schema();

// Serialize a slice of ActiveModels into an Arrow RecordBatch
let batch = measurement::ActiveModel::to_arrow(&models, &schema)?;

// Deserialize an Arrow RecordBatch back into ActiveModels
let models = measurement::ActiveModel::from_arrow(&batch)?;

Exporting to Parquet​

Step 1: convert your ActiveModel slice into a RecordBatch:

use sea_orm::ArrowSchema;

let schema = measurement::Entity::arrow_schema();

let models: Vec<measurement::ActiveModel> = vec![..];
let batch = measurement::ActiveModel::to_arrow(&models, &schema)?;

Step 2: write to Parquet using the parquet crate:

let file = std::fs::File::create("measurements.parquet")?;
let mut writer = parquet::arrow::ArrowWriter::try_new(file, schema.into(), None)?;
writer.write(&batch)?; // write many more batches
writer.close()?;

The resulting file is readable by any Parquet-compatible tool: DuckDB, Polars, Spark, BigQuery, pandas.

Importing from Parquet​

Read a Parquet file back into ActiveModels and insert into any SeaORM-supported database:

use parquet::arrow::arrow_reader::ParquetRecordBatchReaderBuilder;

let file = std::fs::File::open("measurements.parquet")?;
let reader = ParquetRecordBatchReaderBuilder::try_new(file)?.build()?;

let batches: Vec<_> = reader.collect::<Result<_, _>>()?;
let restored = measurement::ActiveModel::from_arrow(&batches[0])?;

measurement::Entity::insert_many(restored).exec(&db).await?;

from_arrow reconstructs full ActiveModel values: Arrow nulls become Set(None), absent columns become NotSet.

Full Example​

A complete working example: generate sensor readings, write to Parquet, verify the roundtrip, then insert into SQLite is available in the SeaORM repository: examples/parquet_example.

As a bonus, you can also use sea-orm-sync and avoid the async runtime entirely if your application is synchronous!

Type Mapping​

SeaORM maps Rust/SQL types to Arrow data types as follows:

Key behaviors:

• String length: String(StringLen::N(n)) with n ≤ 32767 maps to Utf8; Text and unbounded strings map to LargeUtf8.
• Timestamp resolution: microseconds by default. Override per-field with arrow_timestamp_unit.
• Timezone annotation: timezone-aware Rust types (DateTime<Utc>, DateTime<FixedOffset>) always produce a Timestamp with timezone. Naive types (NaiveDateTime) produce no annotation. Override with arrow_timezone.
• Decimal: precision and scale are derived from column_type. If not specified, defaults are Decimal128(38, 10). Override per-field with arrow_precision and arrow_scale.

Timestamp Types​

Timezone and Resolution​

Arrow distinguishes timezone-aware and timezone-naive timestamps at the schema level. SeaORM maps them accordingly:

• ChronoDateTime / NaiveDateTime / PrimitiveDateTime → Timestamp(Microsecond, None): no timezone annotation
• ChronoDateTimeUtc / DateTime<Utc>/ OffsetDateTime → Timestamp(Microsecond, Some("UTC")): UTC annotated

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "test_chrono", arrow_schema)]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub created_date: ChronoDate,        // -> Date32
    pub created_time: ChronoTime,        // -> Time64(Microsecond)
    pub created_at: ChronoDateTime,      // -> Timestamp(Microsecond, None)
    pub updated_at: ChronoDateTimeUtc,   // -> Timestamp(Microsecond, Some("UTC"))
    pub nullable_ts: Option<ChronoDateTimeUtc>,
}

let models = vec![..];

let batch = ActiveModel::to_arrow(&models, &schema)?;
let restored = ActiveModel::from_arrow(&batch)?;

assert_eq!(restored, models);

The default resolution is microseconds. Both the time unit and timezone can be overridden per-field using arrow_timestamp_unit and arrow_timezone:

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "event", arrow_schema)]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    #[sea_orm(column_type = "DateTime", arrow_timestamp_unit = "Nanosecond")]
    pub nano_ts: ChronoDateTime,      // -> Timestamp(Nanosecond, None)
    #[sea_orm(column_type = "DateTime", arrow_timestamp_unit = "Second")]
    pub second_ts: ChronoDateTime,    // -> Timestamp(Second, None)
    #[sea_orm(
        column_type = "DateTime",
        arrow_timestamp_unit = "Nanosecond",
        arrow_timezone = "America/New_York"
    )]
    pub nano_with_tz: ChronoDateTime, // -> Timestamp(Nanosecond, Some("America/New_York"))
}

Valid values for arrow_timestamp_unit: "Second", "Millisecond", "Microsecond", "Nanosecond".

Decimal Types​

Each Decimal column is stored as Decimal128 in Arrow, preserving the exact precision and scale declared in column_type. Columns with different precision/scale are handled independently. Values are scaled to fit Arrow's internal i128 representation (value × 10^scale).

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "test_rust_decimal", arrow_schema)]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    #[sea_orm(column_type = "Decimal(Some((10, 2)))")]
    pub price: Decimal,   // -> Decimal128(10, 2)
    #[sea_orm(
        column_type = "Decimal(Some((20, 4)))",
        arrow_precision = 20,
        arrow_scale = 4
    )]
    pub amount: Decimal,  // -> Decimal128(20, 4)
}

let price = Decimal::new(1234567, 2); // 12345.67
let amount = Decimal::new(98765432109, 4); // 9876543.2109

let models = vec![
    decimal_entity::ActiveModel {
        id: Set(1),
        price: Set(price),
        amount: Set(amount),
        nullable_decimal: Set(Some(price)),
    },
];

let batch = ActiveModel::to_arrow(&models, &schema)?;

// Arrow column carries the declared precision and scale
let price_arr = batch.column_by_name("price").unwrap()
    .as_any().downcast_ref::<Decimal128Array>().unwrap();
assert_eq!(price_arr.value(0), 1234567); // 12345.67 stored as 1234567 (× 10^-2)
assert_eq!(price_arr.precision(), 10);
assert_eq!(price_arr.scale(), 2);

// Full roundtrip
assert_eq!(ActiveModel::from_arrow(&batch)?, models);

BigDecimal is also supported with Decimal256 but not illustrated here.

SeaORM 2.0​

SeaORM 2.0 is shaping up to be our most significant release yet - with a few breaking changes, plenty of enhancements, and a clear focus on developer experience.

SeaORM 2.0 has reached its release candidate phase. We'd love for you to try it out and help shape the final release by sharing your feedback.

🌟 Sponsors​

Gold Sponsor​

QDX pioneers quantum dynamics-powered drug discovery, leveraging AI and supercomputing to accelerate molecular modeling. We're grateful to QDX for sponsoring the development of SeaORM, the SQL toolkit that powers their data intensive applications.

GitHub Sponsors​

If you feel generous, a small donation will be greatly appreciated, and goes a long way towards sustaining the organization.

A big shout out to our GitHub sponsors:

Godwin Effiong

Ryan Swart

OteroRafael

Yuta Hinokuma

wh7f

MS

Numeus

Caido Community

Marcus Buffett

MasakiMiyazaki

KallyDev

Manfred Lee

Afonso Barracha

Dean Sheather

🦀 Rustacean Sticker Pack​

The Rustacean Sticker Pack is the perfect way to express your passion for Rust. Our stickers are made with a premium water-resistant vinyl with a unique matte finish.

Sticker Pack Contents:

• Logo of SeaQL projects: SeaQL, SeaORM, SeaQuery, Seaography
• Mascots: Ferris the Crab x 3, Terres the Hermit Crab
• The Rustacean wordmark

Support SeaQL and get a Sticker Pack!

SeaORM Pro now supports sending notifications to Slack and Microsoft Teams via webhooks. Once configured, applications can send notifications based on triggers: for example, when a new order is created or an order item is updated.

The Design​

1. Application wide​

Notifications are not personalized; any user with select permission on the sea_orm_notification table can view them in the notification panel. Users who have visibility of the designated Slack channel or Teams channel will receive these messages.

Design: application level notification center.

2. Queue based​

When an event is triggered in application code (for example, when a table or row is updated), a notification request is enqueued.

Design: the event queue is intended to avoid adding latency to API requests.

3. Application defined​

Notifications can be sent to one (unicast) or many webhooks (multicast). The application has full control over when and what to send.

Design: application-defined logic tailored to business needs.

4. Background worker​

A background worker picks up pending notifications from the queue and delivers them sequentially.

Design: Notifications are delivered asynchronously by the background worker, avoiding bursts while preserving the order of events.

Configuring Webhooks​

Schema​

A webhook has the following fields:

#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "sea_orm_webhook")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: WebhookId, // uniquely identify the webhook
    pub platform: WebhookPlatform, // can be Slack / MsTeams
    pub url: String, // webhook URL
}

Config Webhook in Admin Panel​

Login to the admin dashboard. If you have read & update permission of the sea_orm_webhook table, you should able to see the "Webhook Settings" page appear on the left:

You can perform quick update of webhook URL here.

Double check the webhook URL is correct.

Config Webhook programatically​

You can also create new webhooks using database migration, such as m20260101_000001_webhook.rs:

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        let db = manager.get_connection();
        sea_orm_notify::create_tables(db).await?;

        webhook::ActiveModel {
            id: NotSet,
            platform: Set(WebhookPlatform::MsTeams),
            url: Set("https://teams.microsoft.com/12345678".to_owned()),
        }
        .insert(db)
        .await?;

        webhook::ActiveModel {
            id: NotSet,
            platform: Set(WebhookPlatform::Slack),
            url: Set("https://hooks.slack.com/12345678".to_owned()),
        }
        .insert(db)
        .await?;

        // ...
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        // ...
    }
}

Setup Slack Webhook​

The step-by-step walkthrough is available here.

Setup Microsoft Teams Webhook​

The step-by-step walkthrough is available here.

Sending Notifications​

Define after_save Trigger​

A common place to trigger notification is right after a database row being inserted or updated. For example in address.rs, we will trigger a notification after every successful insert or update:

#[async_trait::async_trait]
impl ActiveModelBehavior for ActiveModel {
    async fn after_save<C>(model: Model, db: &C, insert: bool) -> Result<Model, DbErr>
    where
        C: ConnectionTrait,
    {
        let action = if insert { "Inserted" } else { "Updated" };
        let message = format!("{action} Address Model ID: {}", model.address_id);
        sea_orm_notify::notify_all(db, &message).await?;
        tracing::info!("{message}");
        Ok(model)
    }
}

Of course these triggers can also be defined at individual API endpoints, where access to DatabaseConnection is provided.

Unicast / Multicast​

There are two methods to send notification, they are defined in sea-orm-notify/src/lib.rs:

// Send the notification to all webhook
sea_orm_notify::notify_all(db, message).await?;

// Send the notification to a specific webhook only
sea_orm_notify::notify(db, WebhookId(1), message).await?;

Formatting Messages​

You can format the notification messages with basic markdown.

Note that Slack has their own dialect. On MS Teams, a subset of HTML is supported. SeaORM Pro automatically compiles markdown to HTML when sending via Teams.

Notification Queue and Background Worker​

Notification will be stored in the sea_orm_notification table and with a column named sent to indicate the notification has been sent or not. A background task will send all pending notification in sequence from old to new, the source code is available at sea-orm-notify/src/lib.rs.

The background task should be spawned during the initialization of the Loco app in app.rs:

pub struct App;
#[async_trait]
impl Hooks for App {
    // ...

    async fn initializers(ctx: &AppContext) -> Result<Vec<Box<dyn Initializer>>> {
        let initializers: Vec<Box<dyn Initializer>> =
            vec![Box::new(initializers::graphql::GraphQLInitializer)];

        sea_orm_notify::run_background_task(ctx.db.clone());

        Ok(initializers)
    }

    // ...
}

Notification Status​

The ✅ checkmark indicates that the notification was sent successfully.

You can click the ⟳ (Resend) button to resend the notification immediately.

SeaORM Pro Plus​

SeaORM Pro Plus unlocks Role Based Access Control (RBAC), notifications, and the frontend source code. We prioritize answering questions and feature requests from sponsors. You can access the repository as a Pro tier Sponsor.

What's Next?​

There's really a lot we want to build, to make SeaORM Pro suit the needs of every project. Please consider being a sponsor and take part in shaping its future!

Here's what we have in mind:

• Single Sign On: To be able to sign-in with Google Workspace or Microsoft Business email.
• Audit Log: And so, we'd want to keep a record of users' action and being able to audit them.
• Tasks: To be able to visualize and control scheduled tasks, and kick start once off tasks in ad-hoc way.

Over the past few months, we've rolled out a series of SeaORM 2.0 releases packed with new capabilities that reshape how you'd use SeaORM. We've stablized our API surface now. Other than dependency upgrades (sqlx 0.9), there won't be more major breaking changes.

If you're eager to upgrade, let's walk through the changes you're likely to encounter, full list of changes can be found here.

SeaORM 2.0 is designed as a seamless step forward: all existing features are preserved, no rewrites are required, and it remains functionally backward-compatible. Most migrations are straightforward and mechanical, with many changes amounting to simple find-and-replace operations.

SeaQuery Type System​

Full details can be found here.

ExprTrait is needed​

#890 For many methods on Expr, e.g. add, eq, ExprTrait is required.

Possible compile errors​

error[E0599]: no method named `like` found for enum `sea_query::Expr` in the current scope
    |
    |         Expr::col((self.entity_name(), *self)).like(s)
    |
    |     fn like<L>(self, like: L) -> Expr
    |        ---- the method is available for `sea_query::Expr` here
    |
    = help: items from traits can only be used if the trait is in scope
help: trait `ExprTrait` which provides `like` is implemented but not in scope; perhaps you want to import it
    |
 -> + use sea_orm::ExprTrait;

error[E0308]: mismatched types
  --> src/sqlite/discovery.rs:27:57
   |
   |             .and_where(Expr::col(Alias::new("type")).eq("table"))
   |                                                      -- ^^^^^^^ expected `&Expr`, found `&str`
   |                                                      |
   |                                                      arguments to this method are incorrect
   |
   = note: expected reference `&sea_query::Expr`
              found reference `&'static str`

error[E0308]: mismatched types
    |
390 |             Some(Expr::col(Name).eq(PgFunc::any(query.symbol)))
    |                                  -- ^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `&Expr`, found `FunctionCall`
    |                                  |
    |                                  arguments to this method are incorrect
    |
note: method defined here
   --> /rustc/6b00bc3880198600130e1cf62b8f8a93494488cc/library/core/src/cmp.rs:254:8

IntoCondition is no longer needed​

Can simply use .into

.on_condition(|_left, right| Expr::col((right, super::users::Column::IsSuperAdmin)).eq(true).into_condition())

Replace with:

.on_condition(|_left, right| Expr::col((right, super::users::Column::IsSuperAdmin)).eq(true).into())

ConditionExpression has been removed. Instead, just convert between Condition and Expr using From/Into:

Cond::all().add(Expr::new(..))

Possible compile errors​

error[E0603]: enum `ConditionExpression` is private
   --> tests/mysql/query.rs:734:20
    |
 >  |     use sea_query::ConditionExpression;
    |                    ^^^^^^^^^^^^^^^^^^^ private enum
 >  |     Cond::all().add(ConditionExpression::Expr(Expr::new(
    |                     ^^^^^^^^^^^^^^^^^^^ use of undeclared type `ConditionExpression`

Change of Iden trait​

#909 The method signature of Iden::unquoted is changed. If you're implementing Iden manually, you can modify it like below:

impl Iden for Glyph {
  - fn unquoted(&self, s: &mut dyn fmt::Write) {
  + fn unquoted(&self) -> &str {
  -     write!(
  -         s,
  -         "{}",
            match self {
                Self::Table => "glyph",
                Self::Id => "id",
                Self::Tokens => "tokens",
            }
  -     )
  -     .unwrap();
    }
}

Possible compile errors​

error[E0050]: method `unquoted` has 2 parameters but the declaration in trait `types::Iden::unquoted` has 1
  --> src/tests_cfg.rs:31:17
   |
   |     fn unquoted(&self, s: &mut dyn std::fmt::Write) {
   |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected 1 parameter, found 2
   |
  ::: src/types.rs:63:17
   |
   |     fn unquoted(&self) -> &str;
   |                 ----- trait requires 1 parameter

Alias is no longer needed for &'static str​

You can use the string "name" in place of all Alias::new("name").

Expr::col(Alias::new("my_col"))

Replace with:

Expr::col("my_col")

SeaORM API​

DeriveValueType changes​

DeriveValueType now implements NotU8, IntoActiveValue, TryFromU64.

You can remove these manual implementation. As a side effects, you can use custom wrapper types as primary keys.

#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "my_value_type")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: MyInteger,
}

#[derive(Clone, Debug, PartialEq, Eq, DeriveValueType)]
pub struct MyInteger(pub i32);
// only for i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64

execute -> execute_raw​

#2657 Overhauled ConnectionTrait API: execute, query_one, query_all, stream now takes in SeaQuery statement instead of raw SQL statement, and methods accepting Statement has been moved to *_raw.

// old
db.execute(Statement::from_sql_and_values(..)).await?;

// new
db.execute_raw(Statement::from_sql_and_values(..)).await?;

You no longer have to build SeaQuery statements manually:

// old
let query: SelectStatement = Entity::find().filter(..).into_query();
let backend = self.db.get_database_backend();
let stmt = backend.build(&query);
let rows = self.db.query_all(stmt).await?;

// new
let query: SelectStatement = Entity::find().filter(..).into_query();
let rows = self.db.query_all(&query).await?;

Possible compile errors​

  --> src/executor/paginator.rs:53:38
   |
>  |         let rows = self.db.query_all(stmt).await?;
   |                            --------- ^^^^ expected `&_`, found `Statement`
   |                            |
   |                            arguments to this method are incorrect
   |
   = note: expected reference `&_`
                 found struct `statement::Statement`