SeaORM

https://www.sea-ql.org/SeaORM/docs/
Admin
SeaORM is an async Object-Relational Mapping (ORM) library for Rust that provides type-safe database...
Tokens:118,958
Snippets:917
Trust Score:8.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Seaography CLI

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Install the Seaography CLI version 2.0.x. Run this before generating entities.

```bash
cargo install seaography-cli@^2.0  

```

--------------------------------

### Raw SQL Migration Example

Source: https://www.sea-ql.org/SeaORM/docs/migration/writing-migration

Full migration example using raw SQL. Uses `execute_unprepared` for statements without bindings and `Statement::from_sql_and_values` for parameterized queries. Loses multi-backend compatibility.

```rust
use sea_orm::Statement;  
use sea_orm_migration::prelude::*;  
  
#[derive(DeriveMigrationName)]  
pub struct Migration;  
  
#[async_trait]  
impl MigrationTrait for Migration {  
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {  
        let db = manager.get_connection();  
  
        // Use `execute_unprepared` if the SQL statement doesn't have value bindings  
        db.execute_unprepared(  
            "CREATE TABLE `cake` (  
                `id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,  
                `name` varchar(255) NOT NULL  
            )"  
        )  
        .await?;  
  
        // Construct a `Statement` if the SQL contains value bindings  
        db.execute_raw(Statement::from_sql_and_values(  
            manager.get_database_backend(),  
            r#"INSERT INTO `cake` (`name`) VALUES (?)"#,  
            ["Cheese Cake".into()]  
        )).await?;  
  
        Ok(())  
    }  
  
    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {  
        manager  
            .get_connection()  
            .execute_unprepared("DROP TABLE `cake`")  
            .await?;  
  
        Ok(())  
    }  
}  

```

--------------------------------

### Get help for sea-orm-cli commands

Source: https://www.sea-ql.org/SeaORM/docs/generate-entity/sea-orm-cli

Shows how to get help for sea-orm-cli commands and subcommands using the -h flag. The examples list all commands, generate subcommands, and the generate entity subcommand.

```bash
# List all available commands  
sea-orm-cli -h  
  
# List all subcommands available in `generate` command  
sea-orm-cli generate -h  
  
# Show how to use `generate entity` subcommand  
sea-orm-cli generate entity -h  

```

--------------------------------

### Replace action example (replace_all)

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/nested-active-model

Shows how to use replace_all to delete all children or specify an exact set. This is destructive and will delete posts not in the set.

```rust
bob.posts.replace_all([]); // delete all  
bob.posts.replace_all([post_1]); // retain this only  

```

--------------------------------

### Install sea-orm-cli with cargo

Source: https://www.sea-ql.org/SeaORM/docs/generate-entity/sea-orm-cli

Installs the sea-orm-cli tool with cargo. The version specifier ^2.0 is used to match the current documentation version.

```bash
cargo install sea-orm-cli@^2.0  

```

--------------------------------

### SQL with parameter placeholder

Source: https://www.sea-ql.org/SeaORM/docs/install-and-config/debug-log

Example of a SQL statement with a parameter placeholder ($1) as logged by SQLx before SeaORM's debug-print injects the actual value.

```sql
SELECT "cake"."name" FROM "cake" WHERE "cake"."id" = $1  

```

--------------------------------

### Visit GraphQL Playground

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Navigate to the GraphQL Playground at http://localhost:8000 to start running queries.

```text
Visit GraphQL Playground at http://localhost:8000  
```

--------------------------------

### Append action example (nested insert with posts)

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/nested-active-model

Shows how to append a new post to an existing user without querying all posts. The default action is append, which is non-destructive.

```rust
// query user, but no posts  
let bob = user::Entity::load().filter_by_email("bob@sea-ql.org").one(db).await?.unwrap();  
  
let mut bob.into_active_model();  
bob.posts.push(post::ActiveModel::builder().set_title("Another weekend"));  
bob.save(db).await?; // INSERT INTO post ..  

```

--------------------------------

### Setup database schema with SchemaBuilder and manual DDL

Source: https://www.sea-ql.org/SeaORM/docs/write-test/sqlite

Shows two ways to create tables: using SchemaBuilder to register entities and apply schema, or writing DDL manually with Table::create.

```rust
async fn setup_schema(db: &DbConn) -> Result<()> {  
  
    // it doesn't matter which order you register entities.  
    // SeaORM figures out the foreign key dependencies and  
    // creates the tables in the right order along with foreign keys  
    db.get_schema_builder()  
        .register(cake::Entity)  
        .register(cake_filling::Entity)  
        .register(filling::Entity)  
        .apply(db)  
        .await?;  
  
    // or, write DDL manually  
    db.execute(  
        Table::create()  
            .table(cake::Entity)  
            .col(pk_auto(cake::Column::Id))  
            .col(string(cake::Column::Name))  
        ).await?;  
  
    Ok(())  
}  
```

--------------------------------

### Entity Loader load example

Source: https://www.sea-ql.org/SeaORM/docs/relation/complex-relations

Loads users with their profiles, followers, and following using the entity loader. The assertions verify the loaded data matches expected values.

```rust
let users = user::Entity::load()  
    .with(profile::Entity)  
    .with((user_follower::Entity, profile::Entity))  
    .with((user_follower::Entity::REVERSE, profile::Entity))  
    .all(db)  
    .await?;  
  
assert_eq!(users[1].profile, bob.profile);  
assert_eq!(users[1].followers.len(), 1);  
assert_eq!(users[1].followers[0], sam);  
assert_eq!(users[1].following.len(), 1);  
assert_eq!(users[1].following[0], alice);  

```

--------------------------------

### Start the GraphQL server

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Navigate to the generated project directory and run the server with cargo run. The project can be modified, with the schema_builder function in query_root.rs being the key place to add custom entities, queries, and mutations.

```bash
cd graphql  
cargo run  
```

--------------------------------

### Dense Entity Format Example (src/entities/cake.rs)

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Example of a dense-format SeaORM entity generated for the cake table. It includes the `seaography` feature flag and uses the `#[sea_orm::model]` attribute.

```rust
//! `SeaORM` Entity, @generated by sea-orm-codegen 2.0.0  
  
use sea_orm::entity::prelude::*;  
  
#[sea_orm::model]  
#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]  
#[sea_orm(table_name = "cake")]  
pub struct Model {  
    #[sea_orm(primary_key)]  
    pub id: i32,  
    pub name: String,  
    #[sea_orm(column_type = "Decimal(Some((16, 4)))")]  
    pub price: Decimal,  
    pub bakery_id: i32,  
    pub gluten_free: bool,  
    #[sea_orm(  
        belongs_to,  
        from = "bakery_id",  
        to = "id",  
        on_update = "Cascade",  
        on_delete = "Cascade"  
    )]  
    pub bakery: BelongsTo<super::bakery::Entity>,  
    #[sea_orm(has_many, via = "cake_baker")]  
    pub bakers: HasMany<super::baker::Entity>,  
}  
  
impl ActiveModelBehavior for ActiveModel {}  

```

--------------------------------

### Compact Entity Format Example (src/entities/cake.rs)

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Example of a compact-format SeaORM entity generated for the cake table. It includes the `RelatedEntity` enum and uses `DeriveRelatedEntity`.

```rust
//! `SeaORM` Entity, @generated by sea-orm-codegen 2.0.0  
  
use sea_orm::entity::prelude::*;  
  
#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]  
#[sea_orm(table_name = "cake")]  
pub struct Model {  
    #[sea_orm(primary_key)]  
    pub id: i32,  
    pub name: String,  
    #[sea_orm(column_type = "Decimal(Some((16, 4)))")]  
    pub price: Decimal,  
    pub bakery_id: i32,  
    pub gluten_free: bool,  
}  
  
#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]  
pub enum Relation { .. }  
  
impl Related<super::bakery::Entity> for Entity { .. }  
  
impl ActiveModelBehavior for ActiveModel {}  
  
#[derive(Copy, Clone, Debug, EnumIter, DeriveRelatedEntity)]  
pub enum RelatedEntity {  
    #[sea_orm(entity = "super::bakery::Entity")]  
    Bakery,  
    #[sea_orm(entity = "super::baker::Entity")]  
    Baker,  
}  

```

--------------------------------

### Execute unprepared SQL statement with execute_unprepared

Source: https://www.sea-ql.org/SeaORM/docs/basic-crud/raw-sql

Execute an unprepared SQL statement using `ConnectionTrait::execute_unprepared`. The example creates the `citext` extension and returns an `ExecResult`.

```rust
let exec_res: ExecResult =  
    db.execute_unprepared("CREATE EXTENSION IF NOT EXISTS citext").await?;  

```

--------------------------------

### Generated SQL for join alias

Source: https://www.sea-ql.org/SeaORM/docs/relation/nested-selects

SQL generated for the join alias example, showing the alias `factory` used in the query.

```sql
SELECT  
    "cake"."id" AS "id",  
    "cake"."name" AS "name",  
    "factory"."id" AS "bakery_id",  
    "factory"."name" AS "bakery_plant"  
FROM "cake"  
LEFT JOIN "bakery" AS "factory" ON "cake"."bakery_id" = "factory"."id"  
ORDER BY "cake"."id" ASC LIMIT 1  

```

--------------------------------

### Consolidation example for two one-to-many relations

Source: https://www.sea-ql.org/SeaORM/docs/relation/multi-selects

Illustrates how consolidation works for a chain with two one-to-many relations. The flat result is grouped by the first entity and then by the second entity.

```rust
vec![  
    (bakery, Some(baker_1), Some(cake_1)),  
    (bakery, Some(baker_1), Some(cake_2)),  
    (bakery, Some(baker_2), Some(cake_3)),  
]  
// would be consolidated into:  
vec![(  
    bakery,  
    vec![  
        (baker_1, vec![cake_1, cake_2]),  
        (baker_2, vec![cake_3]),  
    ]  
)]  
```

--------------------------------

### SQL with injected parameter value

Source: https://www.sea-ql.org/SeaORM/docs/install-and-config/debug-log

Example of the same SQL statement after SeaORM's debug-print injects the parameter value (101) into the string for easier reading.

```sql
SELECT "cake"."name" FROM "cake" WHERE "cake"."id" = 101  

```

--------------------------------

### Model Loader load_self_via example

Source: https://www.sea-ql.org/SeaORM/docs/relation/complex-relations

Loads followers and following for a collection of users using the model loader with load_self_via and load_self_via_rev. The assertions verify the loaded data.

```rust
let users = user::Entity::find().all(db).await?;  
let followers = users.load_self_via(user_follower::Entity, db).await?;  
let following = users.load_self_via_rev(user_follower::Entity, db).await?;  
  
assert_eq!(users[1], bob);  
assert_eq!(followers[1], [sam.clone()]);  
assert_eq!(following[1], [alice.clone()]);  

```

--------------------------------

### Nested ActiveModel update example

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/nested-active-model

Shows how to modify nested ActiveModels (posts and comments) and save them. SeaORM walks the object tree to detect changes and generates the necessary UPDATE and INSERT statements.

```rust
let mut bob: user::ActiveModel = ..;  
  
// update post title  
bob.posts[0].title = Set("Lorem ipsum dolor sit amet".into());  
// update post comment  
bob.posts[0].comments[0].comment = Set("nice post! I learnt a lot".into());  
// add a new comment too  
bob.posts[1].comments.push(  
    comment::ActiveModel::builder().set_comment("interesting!")  
);  
bob.save(db).await?;  
```

--------------------------------

### Initialize migration directory with sea-orm-cli migrate init

Source: https://www.sea-ql.org/SeaORM/docs/migration/setting-up-migration

Run sea-orm-cli migrate init to create the migration directory in ./migration. Use -d to specify a different directory. The output shows the files created.

```bash
# Setup the migration directory in `./migration`  
$ sea-orm-cli migrate init  
Initializing migration directory...  
Creating file `./migration/src/lib.rs`  
Creating file `./migration/src/m20220101_000001_create_table.rs`  
Creating file `./migration/src/main.rs`  
Creating file `./migration/Cargo.toml`  
Creating file `./migration/README.md`  
Done!  
  
# If you want to setup the migration directory in else where  
$ sea-orm-cli migrate init -d ./other/migration/dir  

```

--------------------------------

### Three-way join plan

Source: https://www.sea-ql.org/SeaORM/docs/relation/nested-selects

Shows the join plan for the three-way join example, starting from Order and joining Customer, LineItem, and Cake.

```text
Order -> Customer
      -> LineItem -> Cake
```

--------------------------------

### Get current crate name for schema registry

Source: https://www.sea-ql.org/SeaORM/docs/generate-entity/entity-first

Alternative to hardcoding the crate name: uses `module_path!()` to get the caller's crate name.

```rust
// This returns the caller's crate  
db.get_schema_registry(module_path!().split("::").next().unwrap())  

```

--------------------------------

### Seaography CLI full help

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Displays the full help for the seaography-cli command, showing all options and defaults. The default framework is poem, and the database URL can be set via the DATABASE_URL environment variable.

```bash
🧭 A GraphQL framework for SeaORM  
  
Usage: seaography-cli [OPTIONS] --entities <ENTITIES> --database-url <DATABASE_URL> <CRATE_NAME>  
  
Arguments:  
  <CRATE_NAME>  Crate name for generated project  
  
Options:  
  -o, --output-dir <OUTPUT_DIR>  
          Project output directory [default: ./]  
  -e, --entities <ENTITIES>  
          Entities directory  
  -u, --database-url <DATABASE_URL>  
          Database URL [env: DATABASE_URL]  
  -f, --framework <FRAMEWORK>  
          Which web framework to use [default: poem] [possible values: actix, poem, axum]  
      --depth-limit <DEPTH_LIMIT>  
          GraphQL depth limit  
      --complexity-limit <COMPLEXITY_LIMIT>  
          GraphQL complexity limit  
  -h, --help  
          Print help  
  -V, --version  
          Print version  
```

--------------------------------

### Sample migration file

Source: https://www.sea-ql.org/SeaORM/docs/migration/setting-up-migration

A template migration file with up and down methods. Replace the todo!() with your own migration scripts.

```rust
use sea_orm_migration::prelude::*;  
  
#[derive(DeriveMigrationName)]  
pub struct Migration;  
  
#[async_trait]  
impl MigrationTrait for Migration {  
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {  
        // Replace the sample below with your own migration scripts  
        todo!();  
    }  
  
    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {  
        // Replace the sample below with your own migration scripts  
        todo!();  
    }  
}  

```

--------------------------------

### Configure connection with ConnectOptions

Source: https://www.sea-ql.org/SeaORM/docs/install-and-config/connection

Configures a database connection with options such as max/min connections, timeouts, SQLx logging, and default schema. The `set_schema_search_path` sets the default Postgres schema. Then connects using the configured options.

```rust
let mut opt = ConnectOptions::new("protocol://username:password@host/database");  
opt.max_connections(100)  
    .min_connections(5)  
    .connect_timeout(Duration::from_secs(8))  
    .acquire_timeout(Duration::from_secs(8))  
    .idle_timeout(Duration::from_secs(8))  
    .max_lifetime(Duration::from_secs(8))  
    .sqlx_logging(false) // disable SQLx logging  
    .sqlx_logging_level(log::LevelFilter::Info)  
    .set_schema_search_path("my_schema"); // set default Postgres schema  
  
let db = Database::connect(opt).await?;  
```

--------------------------------

### SeaORM find_also_related example

Source: https://www.sea-ql.org/SeaORM/docs/internal-design/diesel

Shows SeaORM's find_also_related to fetch a cake with its optional filling in one query, returning a Vec of (cake, Option<fruit>) pairs. This is the readme example for SeaORM's relational API.

```rust
// SeaORM  
let cake_with_filling: Vec<(cake::Model, Option<fruit::Model>)> =  
    Cake::find().find_also_related(Filling).all(db).await?;  
```

--------------------------------

### Override from_str and to_str for DeriveValueType

Source: https://www.sea-ql.org/SeaORM/docs/generate-entity/newtype

Customize the from_str and to_str methods used by DeriveValueType, for example to integrate with strum::Display and strum::EnumString or manual implementations. The example shows a Tag enum with custom conversion functions.

```rust
#[derive(DeriveValueType)]  
#[sea_orm(value_type = "String", from_str = "Tag::from_str", to_str = "Tag::to_str")]  
pub enum Tag {  
    Color,  
    Grey,  
}  
  
impl Tag {  
    fn from_str(s: &str) -> Result<Self, ValueTypeErr> { .. }  
  
    fn to_str(&self) -> &'static str { .. }  
}
```

--------------------------------

### Generate GraphQL project with seaography-cli

Source: https://www.sea-ql.org/SeaORM/docs/graph-ql/getting-started

Run this command to generate a new GraphQL server project. It uses the axum framework and specifies the entities directory. The CLI supports Actix, Axum, and Poem out of the box.

```bash
seaography-cli --output-dir . --entities ./src/entities --framework axum sea-orm-seaography-example  
```

--------------------------------

### Migration directory structure

Source: https://www.sea-ql.org/SeaORM/docs/migration/setting-up-migration

Shows the expected file structure after running sea-orm-cli migrate init. The migration directory contains Cargo.toml, README.md, and src with lib.rs, a sample migration file, and main.rs.

```text
migration  
├── Cargo.toml  
├── README.md  
└── src  
    ├── lib.rs                              # Migrator API, for integration  
    ├── m20220101_000001_create_table.rs    # A sample migration file  
    └── main.rs                             # Migrator CLI, for running manually  

```

--------------------------------

### Get custom result using query_one_raw and query_all_raw

Source: https://www.sea-ql.org/SeaORM/docs/basic-crud/raw-sql

Get custom results using `query_one_raw` and `query_all_raw` methods. Both use `Statement::from_string` with the `MySql` backend. `query_one_raw` returns an `Option<QueryResult>` and `query_all_raw` returns a `Vec<QueryResult>`.

```rust
let query_res: Option<QueryResult> = db  
    .query_one_raw(Statement::from_string(  
        DbBackend::MySql,  
        "SELECT * FROM `cake`;",  
    ))  
    .await?;  
let query_res = query_res.unwrap();  
let id: i32 = query_res.try_get("", "id")?;  
  
let query_res_vec: Vec<QueryResult> = db  
    .query_all_raw(Statement::from_string(  
        DbBackend::MySql,  
        "SELECT * FROM `cake`;",  
    ))  
    .await?;  

```

--------------------------------

### SeaORM: Offset-based pagination with paginate()

Source: https://www.sea-ql.org/SeaORM/docs/internal-design/diesel

Shows how to use SeaORM's built-in offset-based pagination. The paginator is created with paginate(), then num_pages() and fetch_page() are used to get the total number of pages and fetch a specific page. This avoids writing manual LIMIT/OFFSET queries.

```rust
let paginator = Post::find()  
    .order_by_asc(post::Column::Id)  
    .paginate(db, posts_per_page);  
let num_pages = paginator.num_pages().await?;  
let posts: Vec<post::Model> = paginator.fetch_page(current_page).await?;  

```

--------------------------------

### Run migration via sea-orm-cli

Source: https://www.sea-ql.org/SeaORM/docs/migration/running-migration

Executes the migration command using the default manifest path. The DATABASE_URL environment variable must be set.

```bash
$ sea-orm-cli migrate COMMAND  

```

--------------------------------

### Remove tags from a post

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/nested-active-model

Removes all tags from a post and replaces them with the given list. In this example, the tag 'sunny' is removed from the post.

```rust
post.tags.replace_all([outdoor]); // let's say we remove the tag sunny  

```

--------------------------------

### Generated SQL for nested partial model

Source: https://www.sea-ql.org/SeaORM/docs/relation/nested-selects

SQL generated for the nested partial model example, showing the `bakery_` prefix on aliases.

```sql
SELECT  
    "cake"."id" AS "id",  
    "cake"."name" AS "name",  
    "bakery"."id" AS "bakery_id",  
    "bakery"."name" AS "bakery_brand"  
FROM "cake"  
LEFT JOIN "bakery" ON "cake"."bakery_id" = "bakery"."id"  
ORDER BY "cake"."id" ASC LIMIT 1  

```

--------------------------------

### Insert one active model and get Model

Source: https://www.sea-ql.org/SeaORM/docs/basic-crud/insert

Inserts an active model and returns the fresh Model, with auto-generated fields populated from the database.

```rust
let pear = fruit::ActiveModel {  
    name: Set("Pear".to_owned()),  
    ..Default::default() // all other attributes are `NotSet`  
};  
  
let pear: fruit::Model = pear.insert(db).await?;  

```

--------------------------------

### Connect to SQLite and run tests

Source: https://www.sea-ql.org/SeaORM/docs/write-test/sqlite

Shows the main integration test function that connects to an in-memory SQLite database, sets up the schema, and runs test cases.

```rust
async fn main() -> Result<(), DbErr> {  
    // Connecting SQLite  
    let db = Database::connect("sqlite::memory:").await?;  
  
    // Setup database schema  
    setup_schema(&db).await?;  
  
    // Performing tests  
    testcase(&db).await?;  
  
    Ok(())  
}  
```

--------------------------------

### Insert One (ActiveModel::insert)

Source: https://www.sea-ql.org/SeaORM/docs/basic-crud/insert

Insert an active model and get back a fresh `Model`. Its value is retrieved from database, so any auto-generated fields will be populated.

```APIDOC
## Insert One

### Description
Insert an active model and get back a fresh `Model`. Its value is retrieved from database, so any auto-generated fields will be populated.

### Method
insert

### Parameters
#### ActiveModel
- **name** (String) - Required - The value to set for the `name` attribute.
- **other attributes** - Optional - All other attributes are `NotSet` by default.

### Request Example
```rust
let pear = fruit::ActiveModel {
    name: Set("Pear".to_owned()),
    ..Default::default() // all other attributes are `NotSet`
};

let pear: fruit::Model = pear.insert(db).await?;
```

### Response
#### Success Response
Returns a `Model` instance with the inserted data, including auto-generated fields.

```

--------------------------------

### Create Index with SeaQuery

Source: https://www.sea-ql.org/SeaORM/docs/migration/writing-migration

Creates an index using SeaQuery's `Index::create()` builder. The `..` placeholder indicates additional builder methods.

```rust
manager.create_index(sea_query::Index::create()..)  

```

--------------------------------

### Connect to database using Database::connect

Source: https://www.sea-ql.org/SeaORM/docs/install-and-config/connection

Creates a `DatabaseConnection` by connecting to a database using a protocol URL. The protocol can be `mysql:`, `postgres:`, or `sqlite:`. The connection is a struct wrapping an inner `DatabaseConnectionType` enum, and each query acquires and releases a connection from the pool.

```rust
let db: DatabaseConnection = Database::connect("protocol://username:password@host/database").await?;  
```

--------------------------------

### SQL generated by find_with_related

Source: https://www.sea-ql.org/SeaORM/docs/relation/model-loader

The SQL query generated by the find_with_related example. It uses a LEFT JOIN and orders by cake.id, duplicating cake data for each fruit.

```sql
SELECT  
    "cake"."id" AS "A_id", "cake"."name" AS "A_name",  
    "fruit"."id" AS "B_id", "fruit"."name" AS "B_name", "fruit"."cake_id" AS "B_cake_id"  
FROM "cake"  
LEFT JOIN "fruit" ON "cake"."id" = "fruit"."cake_id"  
ORDER BY "cake"."id" ASC  

```

--------------------------------

### SeaORM: Cursor-based pagination with cursor_by()

Source: https://www.sea-ql.org/SeaORM/docs/internal-design/diesel

Demonstrates cursor-based pagination using cursor_by(). The cursor is configured with after() and before() to filter results, then first() retrieves the first N rows. This is useful for efficient pagination on large datasets.

```rust
let mut cursor = post::Entity::find().cursor_by(post::Column::Id);  
  
// Filter paginated result by "post"."id" > 1 AND "post"."id" < 100  
cursor.after(1).before(100);  
  
// Get first 10 rows (order by "post"."id" ASC)  
let posts: Vec<post::Model> = cursor.first(10).all(db).await?  

```

--------------------------------

### SQLite connection string to create file if not exists

Source: https://www.sea-ql.org/SeaORM/docs/install-and-config/connection

Connection string for SQLite that creates the database file if it does not exist, using the `mode=rwc` option.

```text
sqlite://path/to/db.sqlite?mode=rwc  
```

--------------------------------

### Drop Table with SeaQuery

Source: https://www.sea-ql.org/SeaORM/docs/migration/writing-migration

Drops a table using SeaQuery's `Table::drop()`. The `use entity::post;` import is shown as an example of referencing an entity.

```rust
use entity::post;  
  
manager.drop_table(sea_query::Table::drop()..)  

```

--------------------------------

### Assert generated SQL for custom join

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/custom-join-condition

Verifies the generated SQL for a left join using the custom relation. The expected SQL matches the initial example.

```rust
assert_eq!(  
    cake::Entity::find()  
        .join(JoinType::LeftJoin, cake::Relation::TropicalFruit.def())  
        .build(DbBackend::MySql)  
        .to_string(),  
    [  
        "SELECT `cake`.`id`, `cake`.`name` FROM `cake`",  
        "LEFT JOIN `fruit` ON `cake`.`id` = `fruit`.`cake_id` AND `fruit`.`name` LIKE '%tropical%'",  
    ]  
    .join(" ")  
);  

```

--------------------------------

### Synchronize database schema with entity definitions

Source: https://www.sea-ql.org/SeaORM/docs/generate-entity/entity-first

Add this to `main.rs` right after creating the database connection to synchronize the database schema with entity definitions. Requires the `schema-sync` and `entity-registry` feature flags.

```rust
let db = &Database::connect(db_url).await?;  
// synchronizes database schema with entity definitions  
db.get_schema_registry("my_crate::entity::*").sync(db).await?;  

```

--------------------------------

### Fruit model with Serialize and Deserialize

Source: https://www.sea-ql.org/SeaORM/docs/basic-crud/json

Defines a SeaORM entity model for the `fruit` table with `Serialize` and `Deserialize` derives. This model is used in the JSON-to-ActiveModel conversion examples.

```rust
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel, Serialize, Deserialize)]  
#[sea_orm(table_name = "fruit")]  
pub struct Model {  
    #[sea_orm(primary_key)]  
    pub id: i32,  
    pub name: String,  
    pub cake_id: Option<i32>,  
}  
```

--------------------------------

### Run migrator on app startup

Source: https://www.sea-ql.org/SeaORM/docs/migration/setting-up-migration

Connects to the database and runs all pending migrations using Migrator::up. Requires the migration crate to be imported.

```rust
use migration::{Migrator, MigratorTrait};  
  
let connection = sea_orm::Database::connect(&database_url).await?;  
Migrator::up(&connection, None).await?;  

```

--------------------------------

### SeaORM: Entity definition and DDL generation

Source: https://www.sea-ql.org/SeaORM/docs/internal-design/diesel

Shows an entity definition using DeriveEntityModel and how to generate DDL statements with Schema::create_index_from_entity(). The example creates a unique index on the lineitem table and verifies the generated SQL. This demonstrates SeaORM's entity-first approach to schema management.

```rust
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]  
#[sea_orm(table_name = "lineitem")]  
pub struct Model {  
    #[sea_orm(primary_key)]  
    pub id: i32,  
    #[sea_orm(unique_key = "item")]  
    pub order_id: i32,  
    #[sea_orm(unique_key = "item")]  
    pub cake_id: i32,  
}  
  
let stmts = Schema::new(backend).create_index_from_entity(lineitem::Entity);  
  
assert_eq!(  
    backend.build(stmts[0]),  
    r#"CREATE UNIQUE INDEX "idx-lineitem-item" ON "lineitem" ("order_id", "cake_id")"#  
);  

```

--------------------------------

### Custom join conditions with join, join_rev, and on_condition

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/advanced-joins

Illustrates custom join conditions using the join method with RelationDef, join_rev, and join_as with on_condition. The example builds a query and asserts the generated MySQL SQL string.

```rust
use sea_orm::{JoinType, RelationTrait};  
use sea_query::Expr;  
  
assert_eq!(  
    cake::Entity::find()  
        .column_as(filling::Column::Id.count(), "count")  
        .column_as(  
            Expr::col(("fruit_alias", fruit::Column::Name)).into_simple_expr(),  
            "fruit_name"  
        )  
        // construct `RelationDef` on the fly  
        .join_rev(  
            JoinType::InnerJoin,  
            cake_filling::Entity::belongs_to(cake::Entity)  
                .from(cake_filling::Column::CakeId)  
                .to(cake::Column::Id)  
                .into()  
        )  
        // reuse a `Relation` from existing Entity  
        .join(JoinType::InnerJoin, cake_filling::Relation::Filling.def())  
        // join with table alias and custom on condition  
        .join_as(  
            JoinType::LeftJoin,  
            cake::Relation::Fruit  
                .def()  
                .on_condition(|_left, right| {  
                    Expr::col((right, fruit::Column::Name))  
                        .like("%tropical%")  
                        .into_condition()  
                }),  
            "fruit_alias"  
        )  
        .group_by(cake::Column::Id)  
        .having(filling::Column::Id.count().equals(Expr::value(2)))  
        .build(DbBackend::MySql)  
        .to_string(),  
    [  
        "SELECT `cake`.`id`, `cake`.`name`, COUNT(`filling`.`id`) AS `count`, `fruit_alias`.`name` AS `fruit_name` FROM `cake`",  
        "INNER JOIN `cake_filling` ON `cake_filling`.`cake_id` = `cake`.`id`",  
        "INNER JOIN `filling` ON `cake_filling`.`filling_id` = `filling`.`id`",  
        "LEFT JOIN `fruit` AS `fruit_alias` ON `cake`.`id` = `fruit_alias`.`cake_id` AND `fruit_alias`.`name` LIKE '%tropical%'",  
        "GROUP BY `cake`.`id`",  
        "HAVING COUNT(`filling`.`id`) = 2",  
    ]  
    .join(" ")  
);  

```

--------------------------------

### Check migration status with get_pending_migrations

Source: https://www.sea-ql.org/SeaORM/docs/migration/running-migration

Retrieves pending migrations and verifies their count, name, and status. The example asserts that there are 5 pending migrations and checks the first one.

```rust
let migrations = Migrator::get_pending_migrations(db).await?;  
assert_eq!(migrations.len(), 5);  
  
let migration = migrations[0];  
assert_eq!(migration.name(), "m20220118_000002_create_fruit_table");  
assert_eq!(migration.status(), MigrationStatus::Pending);  

```

--------------------------------

### Initialize tracing-subscriber for SeaORM debug logs

Source: https://www.sea-ql.org/SeaORM/docs/install-and-config/debug-log

Set up tracing-subscriber to capture and view SeaORM's debug logs. The with_test_writer() is used for testing; replace with a proper writer for production.

```rust
pub async fn main() {  
    tracing_subscriber::fmt()  
        .with_max_level(tracing::Level::DEBUG)  
        .with_test_writer()  
        .init();  
  
    // ...  
}  

```

--------------------------------

### Paginate SeaORM query with custom page size

Source: https://www.sea-ql.org/SeaORM/docs/basic-crud/select

Converts a SeaORM select into a paginator with a custom page size (50 in this example). Iterates over pages using fetch_and_next().

```rust
use sea_orm::{entity::*, query::*, tests_cfg::cake};  
let mut cake_pages = cake::Entity::find()  
    .order_by_asc(cake::Column::Id)  
    .paginate(db, 50);  
 
while let Some(cakes) = cake_pages.fetch_and_next().await? {  
    // Do something on cakes: Vec<cake::Model>  
}  

```

--------------------------------

### Run migration via sea-orm-cli with custom manifest path

Source: https://www.sea-ql.org/SeaORM/docs/migration/running-migration

Executes the migration command with a custom manifest path using the -d option.

```bash
$ sea-orm-cli migrate COMMAND -d ./other/migration/dir  

```

--------------------------------

### Seed data transactionally

Source: https://www.sea-ql.org/SeaORM/docs/migration/seeding-data

Starts a transaction from the connection, inserts a cake record within the transaction, and commits it. This ensures the seeding operation is atomic and can be rolled back if needed.

```rust
use sea_orm_migration::sea_orm::{entity::*, query::*};

// ...

#[async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        // Get the connection and start a transaction
        let db = manager.get_connection();
        let txn = db.begin().await?;

        cake::ActiveModel {
            name: Set("Cheesecake".to_owned()),
            ..Default::default()
        }
        .insert(&txn)
        .await?;

        // Commit it
        txn.commit().await?;

        Ok(())
    }
}

```

--------------------------------

### db.begin() / txn.commit() / txn.rollback()

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/transaction

Manually begins a transaction with `begin`, then commits or rolls back with `commit` or `rollback`. If the transaction handle goes out of scope, it is automatically rolled back.

```APIDOC
## db.begin() / txn.commit() / txn.rollback()

### Description
Manually begins a transaction with `begin`, then commits or rolls back with `commit` or `rollback`. If the transaction handle goes out of scope, it is automatically rolled back.

### Methods
- `begin` (method on `TransactionTrait`) - Starts a new transaction and returns a `DatabaseTransaction` handle.
- `commit` (method on `DatabaseTransaction`) - Commits the transaction.
- `rollback` (method on `DatabaseTransaction`) - Rolls back the transaction.

### Example
```rust
let txn = db.begin().await?;

bakery::ActiveModel {
    name: Set("SeaSide Bakery".to_owned()),
    profit_margin: Set(10.4),
    ..Default::default()
}
.save(&txn)
.await?;

bakery::ActiveModel {
    name: Set("Top Bakery".to_owned()),
    profit_margin: Set(15.0),
    ..Default::default()
}
.save(&txn)
.await?;

txn.commit().await?;
```

### Response
- `begin` returns a `Result<DatabaseTransaction, DbErr>`.
- `commit` returns a `Result<(), DbErr>`.
- `rollback` returns a `Result<(), DbErr>`.
```

--------------------------------

### Conditionally select all columns except one

Source: https://www.sea-ql.org/SeaORM/docs/advanced-query/custom-select

Advanced example that selects all columns except a specific one by filtering the Column iterator. The generated SQL excludes the filtered column.

```rust
assert_eq!(  
    cake::Entity::find()  
        .select_only()  
        .columns(cake::Column::iter().filter(|col| match col {  
            cake::Column::Id => false,  
            _ => true,  
        }))  
        .build(DbBackend::Postgres)  
        .to_string(),  
    r#"SELECT "cake"."name" FROM "cake""#  
);  
```
Tokens:
Raw