English for Sea-ORM Developers
Learn the English vocabulary for Sea-ORM: entities, active models, relations, and migrations in Rust's async ORM.
Sea-ORM discussions carry familiar ORM concepts but attach Rust-specific names to them, and mixing up terms like entity, model, and active model is one of the more common sources of confusion for developers new to the library.
Key Vocabulary
Entity — the struct and trait implementation representing a database table’s structure, generated either by hand or via the sea-orm-cli code generator from an existing schema.
“Regenerate the entity after that migration — the struct is still missing the new column and won’t compile against the updated schema.”
Model — a plain, immutable struct representing a row fetched from the database, used for reading data without the overhead of change tracking.
“Just fetch a Model here since we’re only reading — we don’t need an ActiveModel unless we’re planning to update the row.”
Active model — a mutable wrapper around a model’s fields that tracks which fields have changed, used specifically for inserts and updates.
“Wrap it in an ActiveModel before calling .save() — a plain Model doesn’t track dirty fields, so the ORM wouldn’t know what to update.”
Relation — a declared association between entities, such as has_many or belongs_to, that enables Sea-ORM to generate joins and eager-loading queries automatically.
“Define the relation between Order and OrderItem so we can call .find_with_related() instead of writing the join by hand.”
Migration — a versioned, code-defined change to the database schema, run in sequence, that keeps the schema and the generated entities consistent across environments. “Don’t hand-edit the production schema — write a migration so the change is tracked, reversible, and applied consistently across every environment.”
Common Phrases
- “Do we need an active model here, or is a read-only model enough for this query?”
- “Is the relation defined between these two entities, or are we still writing manual joins?”
- “Did we regenerate the entity after the schema changed, or is it out of sync?”
- “Is this schema change going through a migration, or was it applied directly to the database?”
- “Which fields does the active model actually consider dirty before this save call?”
Example Sentences
Debugging a stale schema issue: “The compiler’s complaining about a missing field because the entity wasn’t regenerated after the last migration — rerun the CLI generator against the updated schema.”
Explaining an architecture choice: “We use models for all our read paths and only reach for active models on the handful of endpoints that actually mutate data — it keeps the read path lightweight.”
Reviewing a pull request: “This join is written by hand — define the relation between these entities so Sea-ORM can generate it and keep future queries consistent.”
Professional Tips
- Distinguish model from active model explicitly in code reviews — using an active model for read-only queries adds unnecessary overhead and signals a misunderstanding of the library’s design.
- Say entity to mean the generated table representation, not “model” or “schema” — precise naming avoids confusion when discussing regeneration after migrations.
- Reference relation by name when suggesting a join be expressed through Sea-ORM’s API instead of raw SQL — it keeps queries typed and consistent.
- Always describe schema changes as going through a migration — it signals the team is tracking schema history rather than mutating databases ad hoc.
Practice Exercise
- Explain the difference between a model and an active model in Sea-ORM.
- Describe what a relation is and what it lets you avoid writing by hand.
- Write a sentence explaining why an entity needs to be regenerated after a migration.