SeaORM CLI Tool
Relevant source files
The following files were used as context for generating this wiki page:
SeaORM CLI is a powerful command-line utility designed to accelerate development with the SeaORM framework. Its primary responsibilities include generating Rust entity files from existing database schemas and managing database migrations. By automating these tasks, the tool ensures consistency between the database state and the application's data models.
The tool supports major relational databases, including MySQL, PostgreSQL, and SQLite. It provides a structured workflow for developers, allowing them to initialize migration projects, track schema changes through versioned migration files, and synchronize their Rust codebase with live database structures.
Sources: sea-orm-cli/README.md, README.md:120-130
Core Functionalities
The SeaORM CLI is organized into two primary subcommands: generate and migrate. These subcommands handle the lifecycle of database interaction from initial schema creation to ongoing maintenance.
Entity Generation
The generate entity command inspects a live database and produces Rust source code representing the database tables as SeaORM entities. In SeaORM 2.0, this generation defaults to a "dense" format where relations are defined directly on the Model struct.
The diagram above shows the data flow from a live database through the CLI tool to generate usable Rust code.
Sources: sea-orm-cli/README.md:16-25, CLAUDE.md:12-30
Migration Management
The migration system allows developers to define schema changes in Rust. The CLI provides commands to initialize the migration environment, create new migration scripts, and apply or rollback changes.
| Command | Description |
|---|---|
init | Initializes a new migration directory in the project. |
generate | Creates a new versioned migration file with a given name. |
up | Applies pending migrations to the database. |
down | Rolls back the last applied migration(s). |
status | Displays the current state of all migrations (Applied/Pending). |
fresh | Drops all tables and reapplies all migrations from scratch. |
refresh | Rolls back all migrations and then reapplies them. |
Sources: sea-orm-cli/README.md:27-58
Workflow Architecture
The CLI acts as a bridge between the developer's environment and the database driver. It utilizes sea-schema for database introspection and sea-orm-codegen for producing the final Rust files.
This sequence diagram illustrates the internal process of the entity generation command.
Sources: sea-orm-cli/Cargo.toml:34-40, sea-orm-cli/README.md:16-25
Installation and Setup
Developers can install the CLI tool directly from crates.io or build it from the project source.
- Standard Installation:
cargo install sea-orm-cli - Building from Source:
cargo install --force --path sea-orm-cli - Development Execution:
To run the CLI during SeaORM development without installing:cargo run --manifest-path sea-orm-cli/Cargo.toml -- migrate init
Sources: CONTRIBUTING.md:103-125, sea-orm-cli/README.md:3-14
Development Guidelines (SeaORM 2.0)
When using the CLI with SeaORM 2.0 projects, certain patterns are enforced to leverage new framework features:
- Dense Entity Format: Generation utilizes the
#[sea_orm::model]macro, which simplifies relation definitions compared to version 1.0. - Strongly-Typed Columns: The generated code supports the
COLUMNconstant for compile-time type safety during filtering. - Schema Registry: The CLI facilitates the "Entity-First" workflow where the
SchemaRegistrycan synchronize database state based on entity definitions.
Sources: CLAUDE.md:6-20, README.md:132-140
Conclusion
The SeaORM CLI Tool is an essential component of the SeaORM ecosystem, providing the automation necessary for maintainable database-backed Rust applications. By handling the complexities of schema discovery and migration versioning, it allows developers to focus on application logic while maintaining a type-safe interface to their data layer.