Synchronous Support (sea-orm-sync)

Relevant source files

The following files were used as context for generating this wiki page:

• sea-orm-sync/src/lib.rs
• sea-orm-sync/CLAUDE.md
• sea-orm-sync/README.md
• sea-orm-sync/Cargo.toml
• sea-orm-sync/src/docs.rs

sea-orm-sync is a specialized version of the SeaORM library designed to provide the full SeaORM API without requiring an asynchronous runtime. It is specifically optimized for lightweight command-line interface (CLI) programs and environments where async/await overhead is unnecessary, particularly when utilizing SQLite.

Sources: sea-orm-sync/src/lib.rs:253-255, sea-orm-sync/README.md:214-216

This module mirrors the core SeaORM functionality but replaces asynchronous operations with blocking equivalents. It facilitates a "sync-first" development flow where code is transformed from the main async repository into a synchronous format using specialized build scripts.

Sources: sea-orm-sync/CLAUDE.md:3-11

Generation and Workflow

The sea-orm-sync codebase is not edited directly. Instead, it is generated from the root src/ and tests/ directories using a transformation process.

Transformation Logic

The make-sync.sh (or make-sync.gnu.sh for Linux) script performs the following operations:

• Copies the main source files into the sea-orm-sync directory.
• Strips async and .await keywords.
• Removes #[async_trait] annotations.
• Replaces futures_util::lock::Mutex with std::sync::Mutex.
• Applies sed transforms to convert asynchronous patterns to synchronous ones.

Sources: sea-orm-sync/CLAUDE.md:3-11

Code Generation Flow

The following diagram illustrates the relationship between the core async library and the synchronous crate generation.

The script requires full filesystem access to apply substitutions correctly, otherwise, asynchronous artifacts may remain in the generated output.

Sources: sea-orm-sync/CLAUDE.md:19-24

Architecture and Components

The architecture of sea-orm-sync mirrors the standard SeaORM structure but operates within a blocking context.

Core Modules

The synchronous crate includes the same high-level modules as the async version:

Module	Description
database	Handles database connections and backends.
entity	Defines the Entity type and ORM operations.
executor	Performs synchronous execution of queries on Models or ActiveModels.
query	Types and methods to build synchronous database queries.
schema	Defines Entity schemas and supports schema synchronization.

Sources: sea-orm-sync/src/lib.rs:818-837

Rusqlite Integration

Unlike the main crate which relies on sqlx, sea-orm-sync typically utilizes rusqlite for its synchronous SQLite backend. This is enabled via the rusqlite feature flag, which wires up sea-query-rusqlite and sea-schema-sync/rusqlite.

Sources: sea-orm-sync/CLAUDE.md:25-27, sea-orm-sync/Cargo.toml:103-103

Synchronous Database Operations

Operations in sea-orm-sync follow the same API patterns as SeaORM 2.0 but return results immediately rather than Future objects.

Entity Loading and Selection

The Entity Loader uses synchronous joins for 1-1 relations and data loaders for 1-N relations to eliminate N+1 problems.

Comparison of Async vs Sync Syntax

Feature	Async SeaORM	Sync SeaORM
Method Call	.all(db).await?	.all(db)?
One Result	.one(db).await?	.one(db)?
Save Model	.save(db).await?	.save(db)?
Transaction	db.transaction(...) (Async)	db.transaction(...) (Sync)

Sources: sea-orm-sync/src/lib.rs:264-272, sea-orm-sync/src/docs.rs:72-83

Configuration and Feature Flags

sea-orm-sync provides extensive feature flags to customize behavior, including support for various data types and database-specific extensions.

Feature	Description
sync	Core feature enabling synchronous operations.
rusqlite	Enables the synchronous SQLite driver.
macros	Enables SeaORM derive macros (e.g., DeriveEntityModel).
with-json	Integrates serde_json for JSON column support.
schema-sync	Enables the Entity-First workflow for synchronizing schemas.
postgres-array	Adds support for PostgreSQL array types in queries.

Sources: sea-orm-sync/Cargo.toml:86-118

Dependency Mapping

The crate uses ouroboros for self-referential structs and derive_more for debug implementations, which are critical for the synchronous wrappers around database handles.

Sources: sea-orm-sync/Cargo.toml:39-47

Summary

sea-orm-sync provides a production-ready, synchronous ORM experience for Rust developers. By leveraging a transformation-based generation process, it ensures API parity with the main SeaORM 2.0 release while catering to environments like CLI tools and lightweight SQLite applications that benefit from a blocking execution model.

Sources: sea-orm-sync/src/lib.rs:253-255, sea-orm-sync/CLAUDE.md:3-7