If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/SeaQL/sea-orm shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 19 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live SeaQL/sea-orm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/SeaQL/sea-orm.

What it runs against: a local clone of SeaQL/sea-orm — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in SeaQL/sea-orm | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of SeaQL/sea-orm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/SeaQL/sea-orm.git
#   cd sea-orm
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of SeaQL/sea-orm and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "SeaQL/sea-orm(\\.git)?\\b" \\
  && ok "origin remote is SeaQL/sea-orm" \\
  || miss "origin remote is not SeaQL/sea-orm (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "sea-orm-macros" \\
  && ok "sea-orm-macros" \\
  || miss "missing critical file: sea-orm-macros"
test -f "sea-orm-codegen" \\
  && ok "sea-orm-codegen" \\
  || miss "missing critical file: sea-orm-codegen"
test -f "DEVELOPMENT.md" \\
  && ok "DEVELOPMENT.md" \\
  || miss "missing critical file: DEVELOPMENT.md"
test -f "examples/actix_example" \\
  && ok "examples/actix_example" \\
  || miss "missing critical file: examples/actix_example"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/SeaQL/sea-orm"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SeaORM is a production-ready async Rust ORM that provides a high-level, type-safe interface to relational databases (MySQL, PostgreSQL, SQLite) with support for complex relationships (1-1, 1-N, M-N, self-referential) and nested queries. It powers REST, GraphQL, and gRPC APIs with 250k+ weekly downloads and features like automatic code generation via sea-orm-codegen, dynamic query builders, and pagination. Workspace monorepo (sea-orm + sea-orm-macros + sea-orm-codegen + sea-orm-arrow) where core ORM lives in src/lib.rs, code generation in sea-orm-codegen/, procedural macros in sea-orm-macros/, and Arrow integration in sea-orm-arrow/. Build tools in build-tools/ handle sync, publishing, and formatting. 10+ integration examples under examples/ (actix_example/, axum_example/, quickstart/, etc.).

Rust backend engineers building web services, REST APIs, and GraphQL servers who need an ergonomic ORM inspired by Rails/Django/Sequelize patterns. Specifically targets developers coming from Ruby/Python/Node.js ecosystems who want familiar ORM concepts but with Rust's type safety and async/await support.

Production-ready and actively maintained. At v2.0.0-rc.38 with strong industry adoption (250k+ weekly downloads), comprehensive CI via .github/workflows/rust.yml, extensive examples across 10+ web frameworks (Actix, Axum, Rocket, etc.), and regular changelog updates (38 RCs tracked in changelog/). Trusted by startups and enterprises.

Moderate dependency footprint (async-trait, sqlx, chrono, derive_more, etc.) with some optional dependencies that must be feature-gated (sqlx-all, postgres-vector, arrow). Still in RC phase (2.0.0-rc.38) meaning breaking changes are possible between RCs. Workspace includes 3 dependent crates (sea-orm-macros, sea-orm-codegen, sea-orm-arrow) that must stay in sync.

Active RC cycle for v2.0.0 (currently rc.38). Recent changelog entries (rc.37, rc.38) suggest ongoing feature refinement and bug fixes. Release automation configured via .github/workflows/release-bot.yml and build-tools/publish.sh indicates regular release cadence. DEVELOPMENT.md and CONTRIBUTING.md are maintained guides.

git clone https://github.com/SeaQL/sea-orm.git && cd sea-orm && cargo build. For a quick demo: cargo run --example quickstart. For integration testing, see build-tools/docker-compose.yml for database setup.

Daily commands: For development: cargo build. Run tests: cargo test. Format code: ./build-tools/rustfmt.sh. Lint: ./build-tools/rustclippy.sh. For examples: cargo run --example quickstart or cargo run -p axum-example (from examples/ directory). Database required for integration tests (see docker-compose.yml).

• Cargo.toml — Workspace root defining all members (sea-orm, sea-orm-macros, sea-orm-codegen, sea-orm-arrow) and core dependencies; essential for understanding the project structure and feature flags.
• sea-orm-macros — Procedural macros crate that powers entity definition and query building; contributors must understand derive macro patterns for entity modeling.
• sea-orm-codegen — Code generation engine for scaffolding entities from databases; critical for the entity-first workflow and migration tooling.
• DEVELOPMENT.md — Development guidelines and contributor setup instructions specific to SeaORM's architecture and testing approach.
• examples/actix_example — Reference implementation showing end-to-end ORM usage with web framework integration, migrations, and CRUD patterns.
• CLAUDE.md — AI assistant guide documenting codebase conventions, common patterns, and architectural decisions for this ORM.
• README.md — Project overview establishing SeaORM's positioning as async ORM for Rust with feature-rich query building and multi-database support.

Add a New Entity to the ORM

1. Create a new migration file in examples/actix_example/migration/src/ named m{timestamp}_{description}.rs that implements the Migration trait with up() and down() methods defining your table schema (examples/actix_example/migration/src/m20220120_000001_create_post_table.rs)
2. Generate or manually create the entity struct in examples/actix_example/entity/src/ with #[derive(DeriveEntity)] macro, defining columns as ActiveValue types and relations (examples/actix_example/entity/src/post.rs)
3. Export the new entity in examples/actix_example/entity/src/lib.rs and examples/actix_example/entity/src/prelude.rs for convenient importing (examples/actix_example/entity/src/prelude.rs)
4. Add the migration to the migration list in examples/actix_example/migration/src/lib.rs by implementing MigrationTrait::up() registration (examples/actix_example/migration/src/lib.rs)

Add a New API Endpoint with Query/Mutation

1. Create a new service module in examples/actix_example/api/src/service/ or extend query.rs/mutation.rs with a public async function accepting db connection and entity filters (examples/actix_example/api/src/service/query.rs)
2. Use sea-orm query builders (Entity::find(), Entity::find_by_id()) with optional relations loading via .find_related() for N+1 optimization (examples/actix_example/api/src/service/mutation.rs)
3. Create a new Actix route handler in examples/actix_example/api/src/lib.rs that calls your service and returns JSON response via HttpResponse::Ok().json() (examples/actix_example/api/src/lib.rs)
4. Add route registration in the Actix app configuration using .service(web::scope('/endpoint').route('', web::get().to(handler))) (examples/actix_example/src/main.rs)

Add a New Feature Flag or Database Driver Support

1. Define the feature in the root Cargo.toml under [features] section, typically gating database-specific dependencies like sqlx with features "mysql", "postgres", or "sqlite" (Cargo.toml)
2. Create conditional compilation blocks in sea-orm-codegen or appropriate crate using #[cfg(feature = "your-feature")] to conditionally compile driver-specific code (sea-orm-codegen)
3. Update DEVELOPMENT.md and examples to document feature activation and driver-specific connection string formats for new database support (DEVELOPMENT.md)
4. Add feature to Cargo.toml docs.rs metadata array to ensure documentation builds with your new feature on docs.rs (Cargo.toml)

Add Integration Test for New Query Feature

1. Create a new test file in examples/actix_example/api/tests/ named {feature}_tests.rs that sets up test database and migrations (examples/actix_example/api/tests/crud_tests.rs)
2. Write test functions using #[tokio::test] that instantiate a database connection, run migrations, and assert query/mutation behavior (examples/actix_example/api/tests/crud_tests.rs)
3. Use sea-orm transactions with db.begin_txn() to ensure test isolation and automatic rollback after each test completes (examples/actix_example/api/tests/crud_tests.rs)

• Rust + async/await (tokio, sqlx) — Provides zero-cost abstraction compile-time safety while enabling high-performance async I/O for concurrent database connections without garbage collection overhead
• Procedural macros (syn, quote) — Enables zero-runtime-cost derive attributes (#[derive(DeriveEntity)]) that generate type-safe query builders and model definitions at compile time
• Multiple database backend support (MySQL, PostgreSQL, SQLite) — Allows ORM to unify query building across databases with conditional compilation and database-agnostic query trait implementations
• Dynamic query building via builder pattern — Provides ergonomic, type-safe SQL construction that prevents injection attacks and allows programmatic filter composition for REST/GraphQL APIs

• Compile-time code generation via macros vs runtime reflection

  • Why: SeaORM uses procedural macros for entity definitions rather than runtime introspection, sacrificing dynamic schema discovery for zero-overhead type safety and compile-time validation
  • Consequence: Entities must be defined or generated ahead of time; schema changes require code regeneration, but all query errors surface at compile time

• Eager relation loading default vs lazy loading with N+1 protection

  • Why: SeaORM requires explicit relation loading (.find_related()) to prevent accidental N+1 queries, trading implicit convenience for explicit control
  • Consequence: Developers must deliberately compose relations, increasing code verbosity but eliminating hidden performance cliffs common in ORMs like Hibernate

• Multiple async runtime support (tokio, async-std) vs single runtime

  • Why: SeaORM abstracts over runtime through generic traits, allowing pluggable executors rather than forcing tokio dependency
  • Consequence: Slightly more trait complexity and compilation time, but flexibility to integrate with any async ecosystem without forcing dependency conflicts

• Workspace with separate crates (sea-orm, sea-orm-macros, sea-orm-codegen, sea-orm-arrow) vs monolithic crate

  • Why: Separates concerns: macros (compile-only), codegen (CLI tool), and arrow integration (analytics) into optional dependencies to minimize transitive deps for end users
  • Consequence: Increased workspace coordination during releases but lighter dependency trees for most users and faster compilation for projects not using codegen

• Real-time change streams (not a real-time database; focus is batch/request-response patterns)
• Authentication & authorization (domain handled by application frameworks like Actix; SeaORM focuses on

RC version (2.0.0-rc.38) may have breaking changes before stable release; check CHANGELOG.md and VERSIONS.md before upgrading. Docker dependencies required for full integration testing (see build-tools/docker-compose.yml); tests will skip if databases unavailable. Feature flags sqlx-all, postgres-vector, with-arrow are mutually exclusive with other DB drivers in some cases. Rust 1.85.0+ required (edge-of-stable). sea-orm-cli installed separately; code generation assumes valid database connection.

• Async trait methods and dynamic dispatch — SeaORM relies heavily on async-trait crate to define async methods in traits (e.g., Entity::find(), Model::save()), which is non-trivial in Rust without helper crates
• Procedural macros (derive macros) — Entity, Column, and ActiveModel derive macros in sea-orm-macros generate boilerplate ORM code at compile-time; understanding how they expand is crucial for debugging and extending
• Type-level programming and associated types — SeaORM uses Rust's associated types (e.g., Entity::Model, Relation::Related) to maintain type safety across queries without runtime overhead
• N+1 query problem and eager loading — SeaORM's relation loading strategies (find_with_related, preload()) solve N+1 issues; understanding when to use each is essential for performance
• Dynamic query building with method chaining — SeaORM queries are built fluently (filter().order_by().limit()) rather than compile-time-checked like Diesel; enables runtime flexibility at cost of fewer guarantees
• Connection pooling and async lifetime management — SeaORM abstracts database connections via DbConn and connection pooling libraries; lifetimes must be carefully managed in async contexts to avoid blocking the runtime
• Self-referential and composite relationship modeling — SeaORM supports advanced relationship patterns (M-N junction tables, self-joins for hierarchies) that require careful schema definition and relation modeling

• sqlx-rs/sqlx — Lower-level async SQL toolkit that SeaORM wraps; understanding sqlx's query builder is essential to SeaORM's design
• SeaQL/sea-query — Companion query-builder crate used internally by SeaORM for dynamic SQL construction without a full ORM layer
• SeaQL/seaography — GraphQL API generator built on top of SeaORM models; extends SeaORM entities into GraphQL schemas automatically
• tokio-rs/tokio — Async runtime that powers SeaORM's async/await execution model via runtime-tokio-native-tls feature
• diesel-rs/diesel — Alternative Rust ORM with compile-time query verification; represents a different philosophy (sync-first, compile-time checks vs SeaORM's async-first, dynamic)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for sea-orm-arrow integration

The sea-orm-arrow feature is listed in Cargo.toml as an optional dependency but there's no visible test directory for arrow-specific functionality. Arrow integration is a powerful feature for analytics workloads, and comprehensive tests would help ensure reliability and prevent regressions. This would be valuable for users combining ORM queries with data processing pipelines.

• [ ] Create tests/arrow_integration/ directory for arrow-specific integration tests
• [ ] Add tests for converting various entity types to Arrow RecordBatches (numeric, string, datetime types)
• [ ] Add tests for nested relations conversion to Arrow format
• [ ] Add tests for with-arrow feature flag combinations with different database backends
• [ ] Document arrow integration patterns in examples/ or sea-orm-arrow/src/

Implement missing sync versions of sea-orm async APIs (make-sync.sh completion)

The build-tools/make-sync.sh script exists but appears incomplete. SeaORM is async-first, but many users need synchronous wrappers for compatibility with blocking code. Creating a comprehensive sync wrapper crate (sea-orm-sync) with corresponding tests would significantly expand usability for legacy systems and blocking contexts.

• [ ] Extend build-tools/make-sync.sh to generate a complete sea-orm-sync crate structure in a new workspace member
• [ ] Add blocking wrapper implementations for core APIs (find, insert, update, delete, query builder)
• [ ] Create tests/sync_api/ with tests verifying sync wrappers work with tokio::task::block_in_place
• [ ] Add examples/sync_example/ demonstrating sync API usage with actix-web or similar blocking framework
• [ ] Update DEVELOPMENT.md with sync crate maintenance guidelines

Add missing RBAC (Role-Based Access Control) feature documentation and examples

The rbac feature is enabled in docs.rs metadata but there's no visible example demonstrating its usage in the examples/ directory. RBAC is a common security requirement for enterprise applications, and concrete examples would help users understand how to implement row-level security and role-based filtering with SeaORM.

• [ ] Create examples/rbac_example/ with a complete working example showing user roles, permissions, and data filtering
• [ ] Add rbac-specific tests in tests/ covering role assignment, permission checking, and query filtering based on roles
• [ ] Document RBAC patterns in sea-orm-macros/src/ or create a new docs/RBAC.md guide
• [ ] Create a changelog entry in changelog/ documenting the rbac feature improvements
• [ ] Add integration examples showing rbac with the actix_example API service

• Add missing integration examples for newer frameworks like Salvo and Seaography; see examples/ directory structure and existing axum_example/ as template.
• Expand unit test coverage for sea-orm-codegen/src/ to verify code generation edge cases (composite keys, self-referential relations, enum columns) against real schemas.
• Document and add examples for the RBAC (role-based access control) feature mentioned in Cargo.toml features but absent from most examples/ demonstrations.

SeaORM appears to be a well-maintained ORM project with generally sound security practices. The primary concerns are configuration issues (invalid edition specification) and incomplete visibility into the full dependency tree. The project uses dual licensing (MIT/Apache-2.0), has active CI/CD workflows, and follows Rust ecosystem best practices. However, the Cargo.toml configuration error is a significant issue that must be corrected. A full security audit should include running 'cargo audit' against all dependencies and reviewing the complete dependency tree, which was truncated in the provided content.

• Medium · Outdated Rust Edition Declaration — Cargo.toml. The Cargo.toml specifies edition = '2024', which does not exist. The latest stable Rust edition is 2021. This is likely a configuration error that could cause compilation issues or unexpected behavior. Fix: Change edition to '2021' or the appropriate stable edition: edition = '2021'
• Medium · Incomplete Dependency Specification — Cargo.toml [dependencies] section. The Cargo.toml dependency section appears truncated and incomplete. Critical dependencies for an ORM (like sqlx, tokio, serde) are not fully listed in the provided content. This makes it difficult to assess the full security posture of dependencies. Fix: Ensure all dependencies are listed with specific versions and review them with 'cargo audit' to identify known vulnerabilities
• Low · Missing MSRV Alignment — Cargo.toml. The rust-version is set to 1.85.0, but the edition is declared as 2024 (which doesn't exist). When correcting the edition, ensure MSRV is compatible with the chosen edition. Fix: Verify that rust-version (1.85.0) is compatible with edition 2021. For edition 2021, MSRV should be 1.56.0 or higher, which is satisfied here.
• Low · Build Scripts Present Without Full Review — build-tools/. The repository contains several build scripts in build-tools/ directory (bump.sh, publish.sh, etc.). While not necessarily vulnerable, shell scripts should be carefully reviewed for injection risks and proper input validation. Fix: Review all shell scripts for proper input validation, use of shellcheck, and avoid eval or exec with untrusted input
• Low · Example Projects Include .env File Reference — examples/actix_example/.env. The examples/actix_example directory contains .env file reference, which typically stores configuration and potentially secrets. While not shown in content, .env files should never be committed to version control. Fix: Ensure .env files are in .gitignore. Use .env.example as a template instead. Never commit actual credentials.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.