class Rotor::Migrator

Runs migrations (Rotor::Migration classes) against a database and records which ran in a table (schema_migrations unless table: says otherwise: version bigint PRIMARY KEY, inserted_at), which migrate and rollback create when it is missing.

class MigCreateUsers < Rotor::Migration
  version 20261107120000

  def change
    create_table :users do |t|
      t.column :name, String
    end
  end
end

class MigAddAge < Rotor::Migration
  version 20261108090000

  def change
    add_column :users, :age, Int, default: 0
  end
end

PG::Pool.open("postgres://app@localhost/shop") do |pool|
  migrator = Rotor::Migrator.new(Rotor::Repo.new(pool: pool), [MigCreateUsers, MigAddAge], log: ->(line: String) { puts line })
  migrator.migrate     # [20261107120000, 20261108090000]
  migrator.status      # [[20261107120000, "MigCreateUsers", :up], [20261108090000, "MigAddAge", :up]]
  migrator.rollback    # [20261108090000]
end

• Each migration runs in a transaction of its own, its version's row written in it (PostgreSQL's DDL is transactional): one that fails is rolled back whole, raising Rotor::MigrationError, and those before it stay applied. One whose class says disable_transaction! runs outside one, its row written after it succeeds.
• migrate and rollback take one connection of the repository's for their whole run (Rotor::Adapter#hold), take a session-level pg_advisory_lock on it (its key derived from the table's name), and run every migration there: two processes migrating at once run one after the other, the second finding nothing pending. lock_timeout: bounds the wait (PostgreSQL's lock_timeout, during the lock alone); without it the wait has no bound.
• Versions are unique among the migrations given. migrate refuses a pending version lower than the highest one applied (Rotor::MigrationError, before running anything), unless allow_out_of_order: true: versions are timestamps, and an older one appearing late is usually a merge that went wrong, to look at before it runs. Applied versions without a migration in the list are shown by status as :unknown; rollback refuses them.
• The repository must not be inside a transaction: each migration opens its own (ArgumentError otherwise). When the run ends, a transaction a migration left open is rolled back and the lock released; a connection taken from a pool has its settings reset (RESET ALL), so that a migration's SET does not reach the pool, while a repository over one connection keeps its session as the migrations left it (theirs and the program's settings alike). A migration without a transaction that leaves one open fails.

/home/runner/work/rotor/rotor/src/migrator.qz:60

Class methods

op = Rotor::Operation::RenameColumn.new("posts", "body", "content")
Rotor::Migrator.render(op)  # => ["ALTER TABLE \"posts\" RENAME COLUMN \"body\" TO \"content\""]

Rotor::Migrator.literal("it's")              # => "'it''s'"
Rotor::Migrator.literal(1.5)                 # => "1.5"
Rotor::Migrator.literal(Rotor::SQL.raw("now()"))  # => "now()"

Methods