Migratus

https://github.com/yogthos/migratus
Admin
Migratus is a general migration framework for Clojure that supports SQL and code-based database...
Tokens:9,160
Snippets:83
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configuration Setup

Source: https://context7.com/yogthos/migratus/llms.txt

Demonstrates various ways to configure Migratus, including basic H2, MySQL, PostgreSQL with connection URI, and using existing DataSources or connections.

```APIDOC
## Configuration Setup

The configuration map specifies the store type, migration directory, database connection, and optional settings for transactions, custom table names, and property substitution.

### Basic Configuration (H2)
```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store                :database
   :migration-dir        "migrations/"
   :init-script          "init.sql"
   :init-in-transaction? false
   :migration-table-name "schema_migrations"
   :db {:dbtype "h2"
        :dbname "site.db"}})
```

### MySQL Configuration
```clojure
(def mysql-config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype   "mysql"
        :dbname   "migratus"
        :user     "root"
        :password ""}})
```

### PostgreSQL with Connection URI
```clojure
(def postgres-config
  {:store         :database
   :migration-dir "migrations"
   :db {:connection-uri "jdbc:postgresql://localhost:5432/mydb?user=postgres&password=secret"}})
```

### Using Existing DataSource (e.g., HikariCP)
```clojure
(require '[hikari-cp.core :as hk])

(def datasource-config
  {:store :database
   :db {:datasource (hk/make-datasource
                      {:adapter "h2"
                       :url     "jdbc:h2:./site.db"})}})
```

### Using Existing Connection with Managed Lifecycle
```clojure
(require '[next.jdbc :as jdbc])

(def connection (jdbc/get-connection {:dbtype "h2" :dbname "site.db"}))

(def managed-connection-config
  {:store :database
   :db {:connection connection}
   :managed-connection? true ;; Migratus won't close the connection
   })
```
```

--------------------------------

### Define Database Migration Configuration

Source: https://github.com/yogthos/migratus/blob/master/README.md

Provides a comprehensive example of a database configuration map for Migratus, including directory settings and database credentials.

```clojure
{:store :database
 :migration-dir "migrations"
 :exclude-scripts ["*.clj"]
 :db {:dbtype "mysql"
      :dbname "migratus"
      :user "root"
      :password ""}}
```

--------------------------------

### Configuring Multiple Migration Directories

Source: https://context7.com/yogthos/migratus/llms.txt

Example of configuring Migratus to use multiple migration directories. This is useful for modular applications where migrations might be spread across different modules or sources.

```clojure
(def config
  {:store         :database
   :migration-dir ["migrations/core"
                   "migrations/plugins"
                   "migrations/tenant"]
   :db {:dbtype "postgresql"
        :dbname "mydb"}})

;; Migrations from all directories are collected, sorted by ID, and run in order
(migratus/migrate config)
```

--------------------------------

### Disable Transactions in Migrations

Source: https://github.com/yogthos/migratus/blob/master/README.md

Disable transactional DDL for databases that do not support it by adding a specific comment directive at the start of the migration file.

```sql
-- :disable-transaction
```

--------------------------------

### Initialize and Manage Migrations in Clojure

Source: https://github.com/yogthos/migratus/blob/master/README.md

Demonstrates how to configure the Migratus environment and execute core migration operations like init, migrate, rollback, up, and down.

```clojure
(ns my-migrations
 (:require [migratus.core :as migratus]))

(def config {:store                :database
             :migration-dir        "migrations/"
             :init-script          "init.sql"
             :init-in-transaction? false
             :migration-table-name "foo_bar"
             :db {:dbtype "h2"
                  :dbname "site.db"}})

(migratus/init config)
(migratus/migrate config)
(migratus/rollback config)
(migratus/up config 20111206154000)
(migratus/down config 20111206154000)
```

--------------------------------

### migratus.core/init

Source: https://context7.com/yogthos/migratus/llms.txt

Initializes the database by running an optional init script. Useful for setting up schemas, extensions, or other prerequisites before migrations are applied.

```APIDOC
## migratus.core/init

Initializes the database by running an optional init script. This is useful for creating schemas, extensions, or other prerequisites before migrations run.

### Method
```clojure
(migratus/init config)
```

### Parameters

- **config** (map) - Required - The configuration map for Migratus.

### Request Example
```clojure
(ns my-app.setup
  (:require [migratus.core :as migratus]))

(def config
  {:store                :database
   :migration-dir        "migrations/"
   :init-script          "init.sql"
   :init-in-transaction? false
   :db {:dbtype "postgresql"
        :dbname "mydb"
        :user   "postgres"
        :password "secret"}})

;; Run the init script (e.g., resources/migrations/init.sql)
;; init.sql might contain:
;; CREATE SCHEMA IF NOT EXISTS app;
;; CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
(migratus/init config)
```

### Response

#### Success Response
- **nil** - Indicates successful initialization.

#### Response Example
```
nil
```
```

--------------------------------

### Configure Migratus Database Connections

Source: https://context7.com/yogthos/migratus/llms.txt

Demonstrates how to define configuration maps for different database backends including H2, MySQL, and PostgreSQL. It also shows how to integrate existing DataSources or managed connections.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store                :database
   :migration-dir        "migrations/"
   :init-script          "init.sql"
   :init-in-transaction? false
   :migration-table-name "schema_migrations"
   :db {:dbtype "h2"
        :dbname "site.db"}})

(def mysql-config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype   "mysql"
        :dbname   "migratus"
        :user     "root"
        :password ""}})

(def postgres-config
  {:store         :database
   :migration-dir "migrations"
   :db {:connection-uri "jdbc:postgresql://localhost:5432/mydb?user=postgres&password=secret"}})

(require '[hikari-cp.core :as hk])
(def datasource-config
  {:store :database
   :db {:datasource (hk/make-datasource
                      {:adapter "h2"
                       :url     "jdbc:h2:./site.db"})}})

(require '[next.jdbc :as jdbc])
(def connection (jdbc/get-connection {:dbtype "h2" :dbname "site.db"}))
(def managed-connection-config
  {:store :database
   :db {:connection connection}
   :managed-connection? true})
```

--------------------------------

### Initialize Database with Migratus

Source: https://context7.com/yogthos/migratus/llms.txt

Initializes the database schema by executing a specified init script. This is typically used for setting up prerequisites like schemas or extensions.

```clojure
(ns my-app.setup
  (:require [migratus.core :as migratus]))

(def config
  {:store                :database
   :migration-dir        "migrations/"
   :init-script          "init.sql"
   :init-in-transaction? false
   :db {:dbtype "postgresql"
        :dbname "mydb"
        :user   "postgres"
        :password "secret"}})

(migratus/init config)
```

--------------------------------

### Execute Migratus CLI Commands

Source: https://github.com/yogthos/migratus/blob/master/README.md

Run common migration tasks such as initializing the migration table, applying pending migrations, or creating new migration files via the command line.

```bash
clj -M:migrate init
clj -M:migrate migrate
clj -M:migrate create create-user-table
```

--------------------------------

### Configure Database Connections for Migratus

Source: https://github.com/yogthos/migratus/blob/master/README.md

Shows how to configure Migratus using various database connection methods including raw JDBC connections and HikariCP data sources.

```clojure
(ns my-migrations
  (:require [next.jdbc :as jdbc]
            [hikari-cp.core :as hk]))

;; Using raw connection
(def connection (jdbc/get-connection {:dbtype "h2" :dbname "site.db"}))
(def config {:db {:connection connection}})

;; Using HikariCP
(def datasource-options {:adapter "h2" :url "jdbc:h2:./site.db"})
(def config {:db {:datasource (hk/make-datasource datasource-options)}})
```

--------------------------------

### CLI Migration Commands

Source: https://context7.com/yogthos/migratus/llms.txt

Use the Migratus CLI via the clj tool to initialize, run, create, and rollback migrations.

```bash
clj -M:migrate --config migratus.edn init
clj -M:migrate --config migratus.edn migrate
clj -M:migrate --config migratus.edn create create-orders-table
clj -M:migrate --config migratus.edn rollback
clj -M:migrate --config migratus.edn up 20231201100000
```

--------------------------------

### Configure Migratus with Property Substitution

Source: https://github.com/yogthos/migratus/blob/master/README.md

Configure the Migratus store with custom properties and environment variables for dynamic template replacement in SQL files.

```clojure
{:store :database
 :properties {:env ["database.table"]
              :map {:database {:user "bob"}}}
 :db {:dbtype   "h2"
      :dbname   "site.db"}}
```

--------------------------------

### Create EDN Migration File

Source: https://github.com/yogthos/migratus/blob/master/README.md

Generates a new code-based migration file using the migratus.core/create function. This function accepts a configuration map, a migration name, and an optional type parameter.

```clojure
(migratus/create config "import-users" :edn)
```

--------------------------------

### Add Migration Result Assertions

Source: https://github.com/yogthos/migratus/blob/master/README.md

Demonstrates how to use the -- expect comment syntax in SQL migration files to verify the number of rows affected by a query.

```sql
-- expect 17;;
update foobar set thing = 'c' where thing = 'a';

--;;

-- expect 1;;
delete from foobar where thing = 'c';
```

--------------------------------

### migratus.core/create

Source: https://context7.com/yogthos/migratus/llms.txt

Generates new migration files. Supports timestamp-based IDs and can create both SQL and EDN (code-based) migration files.

```APIDOC
## migratus.core/create

Creates new migration files with timestamp-based IDs. Supports both SQL and EDN (code-based) migration types.

### Method
```clojure
(migratus/create config migration-name [migration-type])
```

### Parameters

- **config** (map) - Required - The configuration map for Migratus.
- **migration-name** (string) - Required - The base name for the migration files.
- **migration-type** (keyword) - Optional - Defaults to `:sql`. Use `:edn` for code-based migrations.

### Request Example

#### SQL Migration
```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config {:migration-dir "migrations"})

;; Create SQL migration files
(migratus/create config "create-users-table")
;; => ("20231215143022-create-users-table.up.sql"
;;     "20231215143022-create-users-table.down.sql")

;; The generated SQL files will be empty, ready to fill:
;; resources/migrations/20231215143022-create-users-table.up.sql
;; resources/migrations/20231215143022-create-users-table.down.sql
```

#### EDN (Code-based) Migration
```clojure
(migratus/create config "import-legacy-data" :edn)
;; => ("20231215143100-import-legacy-data.edn")
```

### Response

#### Success Response
- **Vector of strings** - Paths to the generated migration files.

#### Response Example
```clojure
("20231215143022-create-users-table.up.sql"
 "20231215143022-create-users-table.down.sql")
```
```

--------------------------------

### Configure Migratus in Leiningen

Source: https://github.com/yogthos/migratus/blob/master/README.md

Add the Migratus plugin to your project.clj file and define the database connection settings within the :migratus configuration key.

```clojure
:plugins [[migratus-lein "<VERSION>"]]

:migratus {:store :database
           :migration-dir "migrations"
           :db {:dbtype "mysql"
                :dbname "migratus"
                :user "root"
                :password ""}}
```

--------------------------------

### Define Migratus Configuration

Source: https://github.com/yogthos/migratus/blob/master/README.md

Create a configuration file to specify the database store and connection details. It supports static EDN files or dynamic Clojure files for environment-based credentials.

```clojure
;; migratus.edn
{:store :database
 :migration-dir "migrations"
 :db {:dbtype "mysql"
      :dbname "migratus"
      :user "root"
      :password ""}}
```

```clojure
;; migratus.clj
{:store :database
 :db {:jdbcUrl (get (System/getenv) "JDBC_DATABASE_URL")}}
```

--------------------------------

### Define Code-Based Migrations

Source: https://github.com/yogthos/migratus/blob/master/README.md

Explains how to implement migrations using Clojure functions defined in EDN files, allowing for complex logic that cannot be expressed in SQL.

```clojure
;; resources/migrations/20170331141500-import-users.edn
{:ns app.migrations.import-users
 :up-fn migrate-up
 :down-fn migrate-down
 :transaction? true}

;; src/app/migrations/import_users.clj
(ns app.migrations.import-users)
(defn migrate-up [config] ...)
(defn migrate-down [config] ...)
```

--------------------------------

### Implement Property Substitution

Source: https://context7.com/yogthos/migratus/llms.txt

Inject environment variables and custom values into SQL migration scripts using the properties configuration map.

```clojure
(def config
  {:store         :database
   :migration-dir "migrations"
   :properties    {:env ["database.schema"]
                   :map {:app {:version "2.0"}}}
   :db {:dbtype "postgresql"
        :dbname "mydb"}})
```

```sql
CREATE SCHEMA IF NOT EXISTS ${migratus.schema};
--;;
GRANT SELECT, INSERT ON ${database.schema}.users TO ${migratus.user};
--;;
COMMENT ON SCHEMA ${migratus.schema} IS 'App version ${app.version}';
```

--------------------------------

### Create Code-Based EDN Migrations

Source: https://context7.com/yogthos/migratus/llms.txt

For complex logic, use EDN files to reference Clojure functions for up and down migration steps.

```clojure
;; resources/migrations/20231205100000-import-users.edn
{:ns my-app.migrations.import-users
 :up-fn migrate-up
 :down-fn migrate-down
 :transaction? true}
```

```clojure
(ns my-app.migrations.import-users
  (:require [next.jdbc :as jdbc]
            [clojure.data.csv :as csv]
            [clojure.java.io :as io]))

(defn migrate-up [config]
  (let [conn (:conn config)]
    (with-open [reader (io/reader "legacy-users.csv")]
      (doseq [row (rest (csv/read-csv reader))]
        (jdbc/execute! conn
          ["INSERT INTO users (id, email, name) VALUES (?, ?, ?)"
           (parse-long (first row))
           (second row)
           (nth row 2)])))))

(defn migrate-down [config]
  (let [conn (:conn config)]
    (jdbc/execute! conn ["DELETE FROM users WHERE imported = true"])))
```

--------------------------------

### Migratus CLI Commands

Source: https://context7.com/yogthos/migratus/llms.txt

Common commands for managing database migrations using the Migratus command-line interface. These commands allow for running, resetting, listing, and managing migrations.

```bash
clj -M:migrate --config migratus.edn down 20231201100000
clj -M:migrate --config migratus.edn reset
clj -M:migrate --config migratus.edn list --pending
clj -M:migrate --config migratus.edn list --applied --format json
clj -M:migrate --config migratus.edn list --available
clj -M:migrate --config migratus.edn -v migrate
```

--------------------------------

### Migratus Core Operations

Source: https://github.com/yogthos/migratus/blob/master/README.md

Standard operations for initializing the database and managing migration lifecycles.

```APIDOC
## [FUNCTION] migratus/init

### Description
Initializes the database using the specified init script.

### Parameters
- **config** (map) - Required - Configuration map containing :store, :migration-dir, and :db details.

### Request Example
(migratus/init config)

## [FUNCTION] migratus/migrate

### Description
Applies all pending migrations to the database.

### Parameters
- **config** (map) - Required - Configuration map.

## [FUNCTION] migratus/rollback

### Description
Rolls back the most recently applied migration.

### Parameters
- **config** (map) - Required - Configuration map.
```

--------------------------------

### Modifying SQL with :modify-sql-fn

Source: https://context7.com/yogthos/migratus/llms.txt

Demonstrates how to use the :modify-sql-fn option in Migratus configuration to transform SQL statements before execution. This is particularly useful for systems that require DDL commands to be processed through specific functions.

```clojure
(defn wrap-ddl [sql]
  (if (re-find #"(?i)^(CREATE|ALTER|DROP)" sql)
    (format "SELECT pglogical.replicate_ddl_command('%s')"
            (clojure.string/replace sql "'" "''"))
    sql))

(def config
  {:store         :database
   :migration-dir "migrations"
   :modify-sql-fn wrap-ddl
   :db {:dbtype "postgresql"
        :dbname "mydb"}})
```

--------------------------------

### Generate Migration Files

Source: https://github.com/yogthos/migratus/blob/master/README.md

Utility function to generate timestamp-prefixed up and down SQL migration files in the configured directory.

```clojure
(migratus/create config "create-user")
(migratus/create {:migration-dir "migrations"} "create-user")
```

--------------------------------

### Leiningen Plugin Configuration and Usage

Source: https://context7.com/yogthos/migratus/llms.txt

Configuration of the migratus-lein plugin in project.clj and common Leiningen commands for managing database migrations. This includes setting up database connection details and migration directories.

```clojure
;; project.clj
(defproject my-app "0.1.0"
  :dependencies [[migratus "1.6.5"]]
  :plugins [[migratus-lein "0.7.3"]]
  :migratus {:store         :database
             :migration-dir "migrations"
             :db {:dbtype   "postgresql"
                  :dbname   "mydb"
                  :user     "postgres"
                  :password "secret"}})
```

```bash
# Run pending migrations
lein migratus migrate

# Create new migration
lein migratus create create-products-table

# Rollback last migration
lein migratus rollback

# Apply specific migrations
lein migratus up 20231201100000 20231202100000

# Roll back specific migrations
lein migratus down 20231202100000

# Reset database
lein migratus reset

# List pending migrations
lein migratus pending
```

--------------------------------

### Define SQL Migration Files

Source: https://context7.com/yogthos/migratus/llms.txt

SQL migrations use a timestamp-based naming convention with .up.sql and .down.sql files. Multiple statements are separated by the --;; delimiter.

```sql
-- resources/migrations/20231201100000-create-users-table.up.sql
CREATE TABLE IF NOT EXISTS users (
    id BIGINT PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
--;;
CREATE INDEX idx_users_email ON users(email);
--;;
CREATE INDEX idx_users_created_at ON users(created_at);
```

```sql
-- resources/migrations/20231201100000-create-users-table.down.sql
DROP INDEX IF EXISTS idx_users_created_at;
--;;
DROP INDEX IF EXISTS idx_users_email;
--;;
DROP TABLE IF EXISTS users;
```

--------------------------------

### Execute Functions in SQL Migrations

Source: https://github.com/yogthos/migratus/blob/master/README.md

Wrap procedural code or functions within a migration file, such as using a DO block in PostgreSQL.

```sql
DO $func$
 BEGIN
 PERFORM schema_name.function_name('foo', 10);
END;$func$;
```

--------------------------------

### Create New Migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Generates new migration files using timestamp-based IDs. Supports creating both SQL migration pairs and EDN-based code migrations.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config {:migration-dir "migrations"})

(migratus/create config "create-users-table")
(migratus/create config "import-legacy-data" :edn)
```

--------------------------------

### Define SQL Migration Scripts

Source: https://github.com/yogthos/migratus/blob/master/README.md

Create up and down SQL files to manage database schema changes. The up script defines the creation logic, while the down script handles the rollback.

```sql
CREATE TABLE IF NOT EXISTS foo(id BIGINT);
```

```sql
DROP TABLE IF EXISTS foo;
```

--------------------------------

### Execute Multiple SQL Statements

Source: https://github.com/yogthos/migratus/blob/master/README.md

Run multiple SQL commands in a single migration by separating them with the --;; delimiter. Migratus splits these commands and executes them within a transaction.

```sql
CREATE TABLE IF NOT EXISTS quux(id bigint, name varchar(255));
--;;
CREATE INDEX quux_name on quux(name);
```

--------------------------------

### Execute Pending Migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Runs all pending migrations in chronological order based on their timestamp IDs. Returns nil on success or status indicators for errors and lock contention.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "app.db"}})

(migratus/migrate config)
```

--------------------------------

### Run Tests with Kaocha

Source: https://github.com/yogthos/migratus/blob/master/README.md

Execute project tests using the Kaocha test runner, supporting various flags for failure handling, focusing on specific tests, or running integration suites.

```bash
bin/kaocha --test-help
bin/kaocha --fail-fast
bin/kaocha --fail-fast --focus migratus.test.migration.sql/test-run-sql-migrations
bin/kaocha testcontainers
```

--------------------------------

### Configure Migratus in deps.edn

Source: https://github.com/yogthos/migratus/blob/master/README.md

Add the Migratus dependency and alias to your project's deps.edn file to enable command-line migration tasks.

```clojure
:aliases {:migrate {:extra-deps {com.github.paulbutcher/clj-migratus {:git/tag "v1.0.0" :git/sha "67d0fe5"}} :main-opts ["-m" "clj-migratus"]}}
```

--------------------------------

### Apply specific migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Applies specific migrations by their IDs. Already completed migrations are silently skipped.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "app.db"}})

(migratus/up config 20231201100000)
(migratus/up config 20231201100000 20231205140000 20231210090000)
```

--------------------------------

### Configure and Assert Migration Results

Source: https://context7.com/yogthos/migratus/llms.txt

Enable result validation to ensure that SQL migrations affect the expected number of rows. This requires setting expect-results? to true in the configuration.

```clojure
(def config
  {:store           :database
   :migration-dir   "migrations"
   :expect-results? true
   :db {:dbtype "h2" :dbname "app.db"}})
```

```sql
-- resources/migrations/20231203100000-update-status.up.sql
-- expect 100;;
UPDATE orders SET status = 'processed' WHERE status = 'pending';
--;;
-- expect 1;;
DELETE FROM orders WHERE id = 12345;
```

--------------------------------

### Configure Migratus for Leiningen

Source: https://github.com/yogthos/migratus/blob/master/README.md

Defines the Migratus configuration within the project.clj file to enable database migration management via the Leiningen plugin.

```clojure
:migratus {:store :database
           :migration-dir "migrations"
           :db {:dbtype "mysql"
                :dbname "//localhost/migratus"
                :user "root"
                :password ""}}
```

--------------------------------

### Pass Arguments to Migration Functions

Source: https://context7.com/yogthos/migratus/llms.txt

Pass additional arguments to migration functions by defining vectors in the EDN configuration file.

```clojure
;; resources/migrations/20231206100000-backfill-data.edn
{:ns my-app.migrations.backfill
 :up-fn [migrate-up "production" {:batch-size 1000}]
 :down-fn [migrate-down "production"]
 :transaction? false}
```

```clojure
(ns my-app.migrations.backfill
  (:require [next.jdbc :as jdbc]))

(defn migrate-up [config env opts]
  (let [conn (:conn config)
        batch-size (:batch-size opts 500)]
    (println "Backfilling data for environment:" env)
    (loop [offset 0]
      (let [rows (jdbc/execute! conn
                   ["SELECT id FROM records WHERE processed IS NULL LIMIT ? OFFSET ?"
                    batch-size offset])]
        (when (seq rows)
          (recur (+ offset batch-size)))))))

(defn migrate-down [config env]
  (println "Rolling back backfill for:" env))
```

--------------------------------

### List pending and completed migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Functions to retrieve lists of migrations that are either pending or already successfully applied.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "app.db"}})

(migratus/pending-list config)
(migratus/completed-list config)
```

--------------------------------

### Run migrations until specific point

Source: https://context7.com/yogthos/migratus/llms.txt

Executes migrations up to a specific ID or rolls back migrations after a specific ID, useful for testing migration states.

```clojure
(ns my-app.test.migrations
  (:require [migratus.core :as migratus]))

(def config {:store :database :migration-dir "migrations" :db {:dbtype "h2" :dbname "test.db"}})

(migratus/migrate-until-just-before config 20231210090000)
(migratus/rollback-until-just-after config 20231201100000)
```

--------------------------------

### migratus.core/migrate

Source: https://context7.com/yogthos/migratus/llms.txt

Applies all pending migrations to the database in the order of their timestamp IDs. Handles potential conflicts and errors during the migration process.

```APIDOC
## migratus.core/migrate

Runs all pending migrations in sorted order by ID. Returns nil on success, :ignore if the table is reserved by another instance, or :failure on error. Supports thread cancellation for long-running migrations.

### Method
```clojure
(migratus/migrate config)
```

### Parameters

- **config** (map) - Required - The configuration map for Migratus.

### Request Example
```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "app.db"}})

;; Apply all pending migrations
(migratus/migrate config)
```

### Response

#### Success Response
- **nil** - Indicates all migrations were applied successfully.

#### Other Responses
- **:ignore** - Returned if the migration table is reserved by another Migratus instance.
- **:failure** - Returned if any migration fails.

#### Response Example (Success)
```
nil
```

#### Logs Output Example
```
INFO migratus.core - Starting migrations
INFO migratus.core - Running up for [20231201100000 20231205140000]
INFO migratus.core - Up 20231201100000-create-users-table
INFO migratus.core - Up 20231205140000-add-email-index
INFO migratus.core - Ending migrations
```
```

--------------------------------

### Code-based Migrations

Source: https://github.com/yogthos/migratus/blob/master/README.md

Defining migrations using Clojure functions for complex logic.

```APIDOC
## [EDN] Code-based Migration Definition

### Description
Define a migration in an EDN file pointing to a Clojure namespace.

### Structure
- **:ns** (string) - Required - Namespace containing the migration functions.
- **:up-fn** (symbol) - Required - Function to execute for migration.
- **:down-fn** (symbol) - Optional - Function to execute for rollback.
- **:transaction?** (boolean) - Optional - Whether to run in a transaction.

### Example
{:ns app.migrations.import-users :up-fn migrate-up :down-fn migrate-down :transaction? true}
```

--------------------------------

### Squash multiple migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Combines multiple consecutive migrations into a single migration file and deletes the originals.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config {:store :database :migration-dir "migrations" :db {:dbtype "h2" :dbname "app.db"}})

(migratus/create-squash config 20231201100000 20231205140000 "initial-schema")
```

--------------------------------

### Migration File Generation

Source: https://github.com/yogthos/migratus/blob/master/README.md

Utility function to generate timestamped migration file pairs.

```APIDOC
## [FUNCTION] migratus/create

### Description
Creates a new pair of up/down migration files in the configured directory.

### Parameters
- **config** (map) - Required - Configuration map.
- **name** (string) - Required - The name of the migration to create.

### Request Example
(migratus/create {:migration-dir "migrations"} "create-user")
```

--------------------------------

### Reset database state

Source: https://context7.com/yogthos/migratus/llms.txt

Resets the database by rolling back all applied migrations and reapplying all migrations from scratch.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "test.db"}})

(migratus/reset config)
```

--------------------------------

### Roll back specific migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Rolls back specific migrations by their IDs. Migrations that are not currently applied are skipped.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "app.db"}})

(migratus/down config 20231205140000)
(migratus/down config 20231210090000 20231205140000)
```

--------------------------------

### Update Migration Table Schema

Source: https://github.com/yogthos/migratus/blob/master/CHANGES.md

Required schema changes for Migratus version 0.9.1 to support human-readable descriptions and timestamps. This update adds 'applied' and 'description' columns to the existing migration tracking table.

```clojure
[:applied "timestamp" "" ""]
[:description "VARCHAR(1024)" "" ""]
```

```sql
ALTER TABLE migratus.schema_migrations ADD COLUMN description varchar(1024);
--;;
ALTER TABLE migratus.schema_migrations ADD COLUMN applied timestamp with time zone;
```

--------------------------------

### Rollback latest migration

Source: https://context7.com/yogthos/migratus/llms.txt

Rolls back the most recently applied migration. It only affects the single migration with the latest applied timestamp.

```clojure
(ns my-app.migrations
  (:require [migratus.core :as migratus]))

(def config
  {:store         :database
   :migration-dir "migrations"
   :db {:dbtype "h2" :dbname "app.db"}})

(migratus/rollback config)
```

--------------------------------

### Disable Transactions in SQL Migrations

Source: https://context7.com/yogthos/migratus/llms.txt

Use the -- :disable-transaction directive for databases that do not support transactional DDL, such as MySQL.

```sql
-- resources/migrations/20231202100000-alter-large-table.up.sql
-- :disable-transaction
ALTER TABLE large_table ADD COLUMN new_field VARCHAR(255);
--;;
CREATE INDEX CONCURRENTLY idx_large_table_new_field ON large_table(new_field);
```
Tokens:
Raw