Database Migrations
Relevant source files
The following files were used as context for generating this wiki page:
The database migration system in Atmos provides a structured, versioned approach to managing schema evolution. Built upon the sea-orm-migration framework, it ensures that the PostgreSQL database schema remains synchronized across different environments by applying incremental changes in a controlled sequence.
The migration logic is encapsulated within the infra crate, specifically under the db/migration module. Each migration is defined as a discrete Rust file implementing the MigrationTrait, allowing for both upward (up) and downward (down) schema transformations.
Migration Architecture
The migration system follows a provider-based pattern where a central Migrator struct aggregates all available migration scripts.
The diagram shows the Migrator as the orchestrator for individual migration files that apply changes to the Database.
Sources: crates/infra/src/db/migration/mod.rs:1-15
The Migrator Trait
The Migrator struct implements MigratorTrait, which defines the collection of migrations to be executed. The migrations() function returns a vector of boxed objects implementing MigrationTrait.
| Component | Responsibility |
|---|---|
Migrator | Central registry for all schema versions. |
MigrationTrait | Interface implemented by individual version files (up/down logic). |
SchemaManager | Sea-ORM utility used within migrations to execute DDL statements. |
Sources: crates/infra/src/db/migration/mod.rs:7-13
Core Schema Definitions
The current migration set focuses on establishing the identity and workspace foundations of the application, primarily through user management and project structure tables.
User and Session Management
The initial migration establishes the users and sessions tables. The users table acts as the primary identity store, while sessions manages active authentication states.
This ER diagram represents the relationship between users and their active sessions as defined in the initial migration.
Sources: crates/infra/src/db/migration/m20260118_000001_create_user_tables.rs:10-60
Project and Workspace Structure
The second migration introduces the projects table and its associated metadata. Projects are linked to owners (users) and contain configuration for workspaces.
| Field | Type | Constraints | Description |
|---|---|---|---|
id | UUID | Primary Key | Unique project identifier |
name | String | Not Null | Display name of the project |
owner_id | UUID | Foreign Key | References users.id (On Delete Cascade) |
description | Text | Nullable | Optional project details |
created_at | DateTime | Default Now | Record creation timestamp |
Sources: crates/infra/src/db/migration/m20260118_000002_create_project_tables.rs:15-45
Migration Execution Logic
Migrations are executed programmatically during application initialization. The system utilizes a fluent API to build tables, define columns, and establish foreign key constraints.
Schema Transformation Flow
When a migration runs, it follows a standard sequence to ensure data integrity, particularly when creating related tables.
This sequence traces the operations performed during the project table creation, highlighting the dependency on the user table.
Sources: crates/infra/src/db/migration/m20260118_000002_create_project_tables.rs:20-55, crates/infra/src/db/migration/mod.rs
Implementation Example: Table Creation
The following snippet illustrates the declarative style used to define tables within a migration file.
// crates/infra/src/db/migration/m20260118_000002_create_project_tables.rs
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
manager
.create_table(
Table::create()
.table(Projects::Table)
.if_not_exists()
.col(ColumnDef::new(Projects::Id).uuid().not_null().primary_key())
.col(ColumnDef::new(Projects::Name).string().not_null())
.col(ColumnDef::new(Projects::OwnerId).uuid().not_null())
.foreign_key(
ForeignKey::create()
.from(Projects::Table, Projects::OwnerId)
.to(Users::Table, Users::Id)
.on_delete(ForeignKeyAction::Cascade)
)
.to_owned(),
)
.await
}
Sources: crates/infra/src/db/migration/m20260118_000002_create_project_tables.rs:25-45
Summary
Database migrations in the Atmos project provide a robust mechanism for schema versioning. By leveraging sea-orm-migration, the project maintains a clear history of changes, from initial user identity setup to complex project and workspace relations. The use of a central Migrator and strongly-typed Rust migration files ensures that schema updates are repeatable, reversible, and integrated directly into the application's infrastructure layer.