Skip to content

Migrations

David Ciulla edited this page Nov 7, 2026 · 2 revisions

Migrations

Laravex migrations are plain Elixir modules that live in database/migrations/. The migrator discovers them by filename, tracks which have run in a migrations table, and provides the full complement of Artisan commands to run, roll back, and refresh the schema.

Generating a Migration

Create a new file in database/migrations/ following the timestamp naming convention:

database/migrations/2024_01_15_120000_create_posts_table.ex

A minimal migration module:

defmodule Database.Migrations.CreatePostsTable do
  def up do
    Laravex.Database.Schema.create("posts", fn t ->
      t = Laravex.Database.Blueprint.id(t)
      t = Laravex.Database.Blueprint.foreign_id(t, "user_id")
      t = Laravex.Database.Blueprint.string(t, "title")
      t = Laravex.Database.Blueprint.text(t, "body", nullable: true)
      t = Laravex.Database.Blueprint.boolean(t, "published")
      t = Laravex.Database.Blueprint.timestamps(t)
      t
    end)
  end

  def down do
    Laravex.Database.Schema.drop_if_exists("posts")
  end
end

Schema & Blueprint

Laravex.Database.Schema provides the table-level API; Laravex.Database.Blueprint describes columns and indexes.

Available Column Types

Function SQLite type Notes
Blueprint.id/1 INTEGER PRIMARY KEY AUTOINCREMENT Conventional id column
Blueprint.string/3 TEXT NOT NULL nullable: true to allow NULL
Blueprint.text/3 TEXT NOT NULL
Blueprint.long_text/3 TEXT NOT NULL
Blueprint.medium_text/3 TEXT NOT NULL
Blueprint.integer/3 INTEGER NOT NULL
Blueprint.big_integer/3 INTEGER NOT NULL
Blueprint.unsigned_integer/3 INTEGER NOT NULL
Blueprint.boolean/3 INTEGER NOT NULL Stored as 0/1
Blueprint.timestamp/3 TEXT NOT NULL ISO-8601 string
Blueprint.timestamps/1 TEXT × 2 Adds created_at, updated_at (nullable)
Blueprint.foreign_id/3 INTEGER NOT NULL FK by convention
Blueprint.remember_token/1 TEXT nullable Standard Laravel remember token

Column Options

Option Type Effect
nullable: true boolean Omits NOT NULL
unique: true boolean Adds inline UNIQUE constraint
primary: true boolean Adds inline PRIMARY KEY
index: true boolean Creates a separate CREATE INDEX statement

Indexes

# Standard index
t = Laravex.Database.Blueprint.index(t, ["email"])
# => CREATE INDEX IF NOT EXISTS posts_email_index ON posts (email)

# Unique index
t = Laravex.Database.Blueprint.unique(t, ["email"])
# => CREATE UNIQUE INDEX IF NOT EXISTS posts_email_unique ON posts (email)

# Composite index
t = Laravex.Database.Blueprint.index(t, ["user_id", "published"])

Custom index names can be provided as a third argument.

Soft-Delete Column

t = Laravex.Database.Blueprint.soft_deletes(t)
# Adds: deleted_at TEXT (nullable)

t = Laravex.Database.Blueprint.soft_deletes(t, "archived_at")
# Custom column name

Morph Columns {#morph-columns}

Morph column pairs store the type string and the owner ID required by Eloquex-Relationships#Polymorphic Relationships:

# NOT NULL type + INTEGER id + composite index
t = Laravex.Database.Blueprint.morphs(t, "commentable")
# → commentable_type TEXT NOT NULL
# → commentable_id INTEGER NOT NULL
# → CREATE INDEX … ON table (commentable_type, commentable_id)

# Nullable variant
t = Laravex.Database.Blueprint.nullable_morphs(t, "imageable")

# UUID variant (both columns are TEXT)
t = Laravex.Database.Blueprint.uuid_morphs(t, "taggable")

Pass index: false to suppress the auto-generated composite index.

Foreign Keys with constrained

Chain constrained/2 on a foreign_id/3 column to add an inline REFERENCES clause:

t = Laravex.Database.Blueprint.foreign_id(t, "user_id") |> Laravex.Database.Blueprint.constrained("users")
# → user_id INTEGER NOT NULL REFERENCES users(id)

# Infer the table name from the column (strips trailing _id and pluralises)
t = Laravex.Database.Blueprint.foreign_id(t, "user_id") |> Laravex.Database.Blueprint.constrained()

# Custom referenced column and cascade
t =
  Laravex.Database.Blueprint.foreign_id(t, "author_id")
  |> Laravex.Database.Blueprint.constrained("users", column: "id", on_delete: :cascade)

Dropping Columns

t = Laravex.Database.Blueprint.drop_column(t, "old_field")
t = Laravex.Database.Blueprint.drop_column(t, ["field_a", "field_b"])

Altering Tables

Modify an existing table with Schema.alter/2 (aliased as Schema.table/2):

Laravex.Database.Schema.alter("posts", fn t ->
  t = Laravex.Database.Blueprint.string(t, "slug", nullable: true)
  t = Laravex.Database.Blueprint.boolean(t, "featured")
  t = Laravex.Database.Blueprint.drop_column(t, "legacy_flag")
  t
end)

# `table/2` is an alias for `alter/2`
Laravex.Database.Schema.table("posts", fn t -> ... end)

Internally, alter emits ALTER TABLE … ADD COLUMN for each new column and ALTER TABLE … DROP COLUMN for each drop_column call.

Renaming Tables

Laravex.Database.Schema.rename("posts", "articles")

Dropping Tables

Laravex.Database.Schema.drop_if_exists("posts")

Running Migrations

# Run all pending migrations
./artisan migrate

# Roll back the last batch
./artisan migrate:rollback

# Roll back all and re-run
./artisan migrate:refresh

# Drop all tables and re-run
./artisan migrate:fresh

# Delete all data without dropping structure
./artisan migrate:wipe

# Show migration status
./artisan migrate:status

The migrations table stores the migration name and batch number. migrate:rollback reverts the most recent batch; migrate:refresh calls all down/0 functions in reverse order then re-runs everything.

Batch Mechanism

Each ./artisan migrate run groups newly-executed migrations into the next batch number (incrementing from MAX(batch) in the migrations table). rollback removes the last batch atomically.

The Default Migrations

Laravex ships four zero-date migrations that run first:

File Tables Created
0001_01_01_000000_create_users_table.ex users, password_reset_tokens, sessions
0001_01_01_000001_create_cache_table.ex cache, cache_locks
0001_01_01_000002_create_jobs_table.ex jobs, job_batches, failed_jobs
0001_01_01_000003_create_personal_access_tokens_table.ex personal_access_tokens
0001_01_01_000004_create_notifications_table.ex notifications

See Also

  • Database — SQLite connection configuration
  • Query-Builder — Raw and fluent SQL after migration
  • Seeding — Populating tables with test data
  • Eloquex — Model-based access to migrated tables

Clone this wiki locally