The cl-migratum Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-migratum Reference Manual

This is the cl-migratum Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:22:52 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Database Schema Migration System for Common Lisp

cl-migratum is a Common Lisp system, which provides facilities for performing database schema migrations.

Requirements

Installation

Clone the cl-migratum repo in your Quicklisp local-projects directory.

git clone https://github.com/dnaeon/cl-migratum.git

Load the system.

CL-USER> (ql:quickload :cl-migratum)

Concepts

The cl-migratum system uses the following concepts to describe the process of discovering and applying schema migrations, so it is important that you get familiar with them first.

Migration

A migration represents a resource that provides information about a schema change, e.g. it provides the unique id of the change, the required scripts that can be used to upgrade and/or downgrade the database.

Migration resources are discovered via providers and are being used by drivers during the process of upgrade/downgrade of the schema.

Provider

The provider is responsible for discovering migration resources.

For example a provider can discover migrations from local path by scanning files that match a given pattern or fetch migrations from a remote endpoint (e.g. HTTP service).

The provider is also responsible for creating new migration sequences.

The following providers are supported by cl-migratum.

| Name | Description | System | |--------------|------------------------------------------------------------------|-----------------------------------| | local-path | Provider that can discover migration resources from a local path | cl-migratum.provider.local-path |

Driver

The driver carries out the communication with the database against which schema changes will be applied.

It is responsible for applying schema changes, registering successfully applied migrations and unregistering them when reverting back to a previous state.

A driver uses a provider in order to discover migrations, which can be applied against the database it is connected to.

The following drivers are supported by cl-migratum.

| Name | Description | System | |-------|--------------------------------------------------------------------------------------------------------------------|--------------------------| | sql | Driver for performing schema migrations against a SQL database using CL-DBI | cl-migratum.driver.sql |

Usage

The following section contains some examples to get you started.

Create Provider

First, we will create a new provider that can discover migration files from a local path. In order to create a local-path provider we need to load the system for the respective provider.

CL-USER> (ql:quickload :cl-migratum.provider.local-path)

Once you load the system we can create a local-path provider.

CL-USER> (defparameter *provider*
           (migratum.provider.local-path:make-local-path-provider #P"~/Projects/lisp/cl-migratum/t/migrations/"))
*PROVIDER*

The LOCAL-PATH-PROVIDER discovers migration files which match the following pattern.

| Pattern | Description | |-------------------------------|------------------| | <id>-<description>.up.sql | Upgrade script | | <id>-<description>.down.sql | Downgrade script |

A provider can optionally be initialized, which can be done using the MIGRATUM:PROVIDER-INIT generic function. Not all providers would require initialization, but some will and therefore it is good that you always initialize them first.

In order to list the migrations provided by a provider you can use the MIGRATUM:PROVIDER-LIST-MIGRATIONS generic function, e.g.

CL-USER> (migratum:provider-list-migrations *provider*)
(#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {100527E5D3}>
 #<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {100527E673}>
 #<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {100527E713}>)

The following generic functions can be used to interact with discovered migrations.

| Method | Description | |---------------------------------------|---------------------------------------------------------| | MIGRATUM:MIGRATION-ID | Returns the unique migration id | | MIGRATUM:MIGRATION-DESCRIPTION | Returns the description of the migration | | MIGRATUM:MIGRATION-APPLIED | Returns the timestamp of when the migration was applied | | MIGRATUM:MIGRATION-LOAD-UP-SCRIPT | Returns the upgrade script of the migration | | MIGRATUM:MIGRATION-LOAD-DOWN-SCRIPT | Returns the downgrade script of the migration |

For example in order to collect the unique IDs of migration resources you can evaluate the following expression.

CL-USER> (mapcar #'migratum:migration-id
                 (migratum:provider-list-migrations *provider*))
(20200421180337 20200421173908 20200421173657)

Create Driver

Once we have a provider for discovering migration resources we need to create a driver, which can be used to communicate with the database we want to apply migrations on.

Here is how we can create a SQL driver. First, lets load the system, which provides that driver.

CL-USER> (ql:quickload :cl-migratum.driver.sql)

The SQL driver uses CL-DBI interface to communicate with the database, so we will need to create a database connection.

CL-USER> (defparameter *conn*
           (dbi:connect :sqlite3 :database-name "/Users/dnaeon/cl-migratum.db"))
*CONN*

And now we can instantiate our SQL driver using the previously created provider and connection.

CL-USER> (defparameter *driver*
           (migratum.driver.sql:make-sql-driver *provider* *conn*))
*DRIVER*

Initialize Driver

Each driver may require some initialization steps to be executed before being able to apply migrations, so make sure that you initialize a driver once you create it.

An example requirement for a driver might be to create some required database schema used to track which migrations have been applied already, so lets initialize our driver first.

CL-USER> (migratum:driver-init *driver*)

Pending Migrations

In order to get the list of pending (not applied yet) migrations we can use the MIGRATUM:LIST-PENDING function, e.g.

CL-USER> (migratum:list-pending *driver*)
(#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {10052A0583}>
 #<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {10052A0623}>
 #<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {10052A06C3}>)

Or, we can display a table of the pending migrations using the MIGRATUM:DISPLAY-PENDING function instead.

CL-USER> (migratum:display-pending *driver*)
.-----------------------------------.
|        PENDING MIGRATIONS         |
+----------------+------------------+
| ID             | DESCRIPTION      |
+----------------+------------------+
| 20200421173657 | create_table_foo |
| 20200421173908 | create_table_bar |
| 20200421180337 | create_table_qux |
+----------------+------------------+
| TOTAL          |                3 |
+----------------+------------------+
NIL

The migrations will be sorted in the order they need to be applied.

Applying Migrations

The following functions are used for applying pending migrations.

This is how we can apply all pending migrations for example.

CL-USER> (migratum:apply-pending *driver*)
 <INFO> [18:10:14] cl-migratum.core core.lisp (apply-pending) -
  Found 3 pending migration(s) to be applied
 <INFO> [18:10:14] cl-migratum.core core.lisp (apply-and-register) -
  Applying migration 20200421173657 - create_table_foo
 <INFO> [18:10:14] cl-migratum.core core.lisp (apply-and-register) -
  Applying migration 20200421173908 - create_table_bar
 <INFO> [18:10:14] cl-migratum.core core.lisp (apply-and-register) -
  Applying migration 20200421180337 - create_table_qux
NIL

Get Latest Migration

You can use the MIGRATUM:LATEST-MIGRATION function to get the latest applied migration, e.g.

CL-USER> (migratum:migration-id (migratum:latest-migration *driver*))
20200421180337

The MIGRATUM:CONTAINS-APPLIED-MIGRATIONS-P predicate can be used to query whether there are any migrations applied, e.g.

CL-USER> (migratum:contains-applied-migrations-p *driver*)
T

Displaying Applied Migrations

The following functions can be used to get and display the list of applied database migrations.

| Function | Description | |--------------------------------|----------------------------------------| | MIGRATUM:DRIVER-LIST-APPLIED | Returns the list of applied migrations | | MIGRATUM:DISPLAY-APPLIED | Display a table of applied migrations |

This is how we can get the list of applied migrations.

CL-USER> (migratum:driver-list-applied *driver*)
(#<CL-MIGRATUM.CORE:MIGRATION {1006095B23}>
 #<CL-MIGRATUM.CORE:MIGRATION {1006095B73}>
 #<CL-MIGRATUM.CORE:MIGRATION {1006095BC3}>)

Or we can display a nice table of the applied migrations instead.

CL-USER> (migratum:display-applied *driver*)
.---------------------------------------------------------.
|                   APPLIED MIGRATIONS                    |
+----------------+------------------+---------------------+
| ID             | DESCRIPTION      | APPLIED             |
+----------------+------------------+---------------------+
| 20200421180337 | create_table_qux | 2020-04-21 15:17:46 |
| 20200421173908 | create_table_bar | 2020-04-21 15:14:13 |
| 20200421173657 | create_table_foo | 2020-04-21 15:12:52 |
+----------------+------------------+---------------------+
|                | TOTAL            |                   3 |
+----------------+------------------+---------------------+
NIL

The output of these functions will be the applied migrations in descending order by their id, first one being the most recent one.

The SQL driver by default will fetch the last 100 applied migrations. You can control this behaviour by using the :offset and :limit keyword parameters, which allows you to fetch applied migrations in pages.

For example, if you are interested only in the last ten applied migrations you can evaluate the following expression.

CL-USER> (migratum:display-applied *driver* :limit 10)

Or if you want to skip the first ten migrations, you can evaluate this expression instead.

CL-USER> (migratum.display-applied *driver* :offset 10 :limit 10)

Stepping through migrations

Using the following functions you can step through migrations.

| Function | Description | |------------------------|--------------------------------------| | MIGRATUM:APPLY-NEXT | Apply the next pending migration(s) | | MIGRATUM:REVERT-LAST | Revert the last applied migration(s) |

This is useful in situations when you don't want to apply all migrations at once, but rather do it one at a time. Both of these functions accept a keyword parameter :count which specifies the number of migrations to apply or revert.

Consider the following pending migrations.

CL-USER> (migratum:display-pending *driver*)
.-----------------------------------.
|        PENDING MIGRATIONS         |
+----------------+------------------+
| ID             | DESCRIPTION      |
+----------------+------------------+
| 20200421173657 | create_table_foo |
| 20200421173908 | create_table_bar |
| 20200421180337 | create_table_qux |
+----------------+------------------+
| TOTAL          |                3 |
+----------------+------------------+
NIL

We can apply them one by one and verify them as we go.

CL-USER> (migratum:apply-next *driver*)
 <INFO> [20:04:25] cl-migratum.core core.lisp (apply-and-register) -
  Applying migration 20200421173657 - create_table_foo
NIL
CL-USER> (migratum:apply-next *driver*)
 <INFO> [20:04:28] cl-migratum.core core.lisp (apply-and-register) -
  Applying migration 20200421173908 - create_table_bar
NIL
CL-USER> (migratum:apply-next *driver*)
 <INFO> [20:04:29] cl-migratum.core core.lisp (apply-and-register) -
  Applying migration 20200421180337 - create_table_qux
NIL

If we want to revert the last three migrations we can use the MIGRATUM:REVERT-LAST function, e.g.

CL-USER> (migratum:revert-last *driver* :count 3)
 <INFO> [20:06:00] cl-migratum.core core.lisp (revert-and-unregister) -
  Reverting migration 20200421180337 - create_table_qux
 <INFO> [20:06:00] cl-migratum.core core.lisp (revert-and-unregister) -
  Reverting migration 20200421173908 - create_table_bar
 <INFO> [20:06:00] cl-migratum.core core.lisp (revert-and-unregister) -
  Reverting migration 20200421173657 - create_table_foo
NIL

Creating New Migrations

The MIGRATUM:PROVIDER-CREATE-MIGRATION generic function creates a new migration sequence, when supported by the provider that you are using.

Here's one example of creating a new migration, which also specifies the upgrade and downgrade scripts as part of the keyword parameters.

CL-USER> (defparameter *migration*
           (migratum:provider-create-migration *provider*
                                               :description "create table fubar"
                                               :up "CREATE TABLE fubar (id INTEGER PRIMARY KEY);"
                                               :down "DROP TABLE fubar;"))
*MIGRATION*

We can also inspect the newly created migration, e.g.

CL-USER> (migratum:migration-id *migration*)
20200421201406
CL-USER> (migratum:migration-description *migration*)
"create_table_fubar"
CL-USER> (migratum:migration-load-up-script *migration*)
"CREATE TABLE fubar (id INTEGER PRIMARY KEY);"
CL-USER> (migratum:migration-load-down-script *migration*)
"DROP TABLE fubar;"

Multiple Statements

If you need to run multiple statements when using the sql driver you can separate each statement in the migration using the --;; separator.

The following example migration would create two tables as part of a single transaction.

CREATE TABLE foo (
    id INTEGER PRIMARY KEY
);
--;;
CREATE TABLE bar (
    id INTEGER PRIMARY KEY
);

Debug logging

cl-migratum uses log4cl, so you can enable debug logging, if needed.

CL-USER> (log:config :debug)

Implemeting new migration resources

Generally new migration resources will be implemented along with a provider, which discovers them.

You can implement a new migration resource by subclassing the MIGRATUM:BASE-MIGRATION class.

The following generic functions should be implemented on the newly defined class.

| Method | Description | |---------------------------------------|------------------------------| | MIGRATUM:MIGRATION-LOAD-UP-SCRIPT | Returns the upgrade script | | MIGRATUM:MIGRATION-LOAD-DOWN-SCRIPT | Returns the downgrade script |

The following generic functions can be overriden, if needed.

| Method | Description | |----------------------------------|-----------------------------------------------------| | MIGRATUM:MIGRATION-ID | Returns the unique migration id | | MIGRATUM:MIGRATION-DESCRIPTION | Returns description of the migration | | MIGRATUM:MIGRATION-APPLIED | Returns timestamp of when the migration was applied |

Example implementation that loads migration resources from a remote HTTP server might look like this. The following code uses Dexador as the HTTP client.

(defun http-get (url)
  "HTTP GETs the given URL"
  (let ((contents (dex:get url :force-string t)))
    contents))

(defclass http-migration (base-migration)
  ((up-script-url
    :initarg :up-script-url
    :initform (error "Must specify URL to upgrade script")
    :accessor http-migration-up-script-url
    :documentation "URL to the upgrade script")
   (down-script-url
    :initarg :down-script-url
    :initform (error "Must specify URL to downgrade script")
    :accessor http-migration-down-script-url
    :documentation "URL to the downgrade script"))
  (:documentation "HTTP migration resource"))

(defmethod migration-load-up-script ((migration http-migration) &key)
  (http-get (http-migration-up-script-url migration)))

(defmethod migration-load-down-script ((migration http-migration) &key)
  (http-get (http-migration-down-script-url migration)))

A provider should simply MAKE-INSTANCE of the HTTP-MIGRATION class by providing values for the required slots while discovering migrations via the PROVIDER-LIST-MIGRATIONS function.

Implementing new providers

You can implement custom providers, which can discover migration resources from various sources, e.g. local path, remote HTTP endpoints, etc.

Each provider determines the rules, which identify a resource as a valid migration, so custom logic for discovering them can be implemented by using your own provider. For example the local-path provider considers files to be valid migrations, if they match a given regex pattern.

In order to create a new provider you can subclass the MIGRATUM:BASE-PROVIDER class and implement the following generic functions on your newly defined class.

| Method | Description | |--------------------------------------|--------------------------------------------| | MIGRATUM:PROVIDER-LIST-MIGRATIONS | Responsible for discovering migrations | | MIGRATUM:PROVIDER-CREATE-MIGRATION | Creates a new migration using the provider |

The following methods can be overriden, if needed.

| Method | Description | |---------------------------------|---------------------------------------------------------| | MIGRATUM:PROVIDER-NAME | Returns a human-friendly name of the provider | | MIGRATUM:PROVIDER-INIT | Initializes the provider, if needed | | MIGRATUM:PROVIDER-INITIALIZED | Returns T if provider is initialized, NIL otherwise |

You can also check the local-path provider implementation for some example code.

Implementing new drivers

A driver is responsible for communicating with the database we are migrating and actually executing the upgrade and downgrade scripts.

The driver also takes care of registering applied migrations after applying an upgrade script and also unregistering them during downgrade, thus it is the drivers' decision how to implement registering and unregistering. For example the sql builtin driver registers applied migrations on the same database it is migrating, but a custom driver could choose a different stategy instead, e.g. use a key/value store, local files, or some remote endpoint instead.

New drivers can be implemented by subclassing the MIGRATUM:BASE-DRIVER class. The following methods should be implemented on drivers.

| Method | Description | |----------------------------------------|--------------------------------------------| | MIGRATUM:DRIVER-LIST-APPLIED | Returns the list of applied migrations | | MIGRATUM:DRIVER-REGISTER-MIGRATION | Registers a successfully applied migration | | MIGRATUM:DRIVER-UNREGISTER-MIGRATION | Unregisters previously applied migration | | MIGRATUM:DRIVER-APPLY-UP-MIGRATION | Executes the upgrade script | | MIGRATUM:DRIVER-APPLY-DOWN-MIGRATION | Executes the downgrade script |

The following methods can be overriden, if needed.

| Method | Description | |-------------------------------|-------------------------------------------------------| | MIGRATUM:DRIVER-INIT | Initializes the driver, if needed | | MIGRATUM:DRIVER-NAME | Returns the human-friendly name of the driver | | MIGRATUM:DRIVER-PROVIDER | Returns the provider used by the driver | | MIGRATUM:DRIVER-INITIALIZED | Returns T if driver is initialized, NIL otherwise |

You can check the sql driver implementation for some example code.

Tests

Tests are provided as part of the cl-migratum.test system.

In order to run the tests you can evaluate the following expressions.

CL-USER> (ql:quickload :cl-migratum.test)
CL-USER> (asdf:test-system :cl-migratum.test)

Or you can run the tests in a Docker container instead.

First, build the Docker image.

docker build -t cl-migratum .

Run the tests.

docker run --rm cl-migratum

Contributing

cl-migratum is hosted on Github. Please contribute by reporting issues, suggesting features or by sending patches using pull requests.

Authors

License

This project is Open Source and licensed under the BSD License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-migratum

Long Name

cl-migratum

Maintainer

Marin Atanasov Nikolov <dnaeon@gmail.com>

Author

Marin Atanasov Nikolov <dnaeon@gmail.com>

Home Page

https://github.com/dnaeon/cl-migratum

Source Control

https://github.com/dnaeon/cl-migratum

Bug Tracker

https://github.com/dnaeon/cl-migratum

License

BSD 2-Clause

Description

Database schema migration system for Common Lisp

Long Description

# Database Schema Migration System for Common Lisp

‘cl-migratum‘ is a Common Lisp system, which provides facilities for
performing [database schema
migrations](https://en.wikipedia.org/wiki/Schema_migration).

## Requirements

* [Quicklisp](https://www.quicklisp.org/beta/)

## Installation

Clone the [cl-migratum](https://github.com/dnaeon/cl-migratum) repo in your
[Quicklisp local-projects directory](https://www.quicklisp.org/beta/faq.html).

“‘ shell
git clone https://github.com/dnaeon/cl-migratum.git
“‘

Load the system.

“‘ shell
CL-USER> (ql:quickload :cl-migratum)
“‘

## Concepts

The ‘cl-migratum‘ system uses the following concepts to describe
the process of discovering and applying schema migrations, so it is
important that you get familiar with them first.

### Migration

A ‘migration‘ represents a resource that provides information about a
schema change, e.g. it provides the unique id of the change, the
required scripts that can be used to upgrade and/or downgrade the
database.

Migration resources are discovered via ‘providers‘ and are being
used by ‘drivers‘ during the process of upgrade/downgrade of the
schema.

### Provider

The ‘provider‘ is responsible for discovering migration resources.

For example a provider can discover migrations from local path by
scanning files that match a given pattern or fetch migrations from
a remote endpoint (e.g. HTTP service).

The ‘provider‘ is also responsible for creating new migration
sequences.

The following providers are supported by ‘cl-migratum‘.

| Name | Description | System | |————–|——————————————————————|———————————–|
| ‘local-path‘ | Provider that can discover migration resources from a local path | ‘cl-migratum.provider.local-path‘ |

### Driver

The ‘driver‘ carries out the communication with the
database against which schema changes will be applied.

It is responsible for applying schema changes, registering
successfully applied migrations and unregistering them when
reverting back to a previous state.

A ‘driver‘ uses a ‘provider‘ in order to discover ‘migrations‘, which
can be applied against the database it is connected to.

The following drivers are supported by ‘cl-migratum‘.

| Name | Description | System | |——-|——————————————————————————————————————–|————————–| | ‘sql‘ | Driver for performing schema migrations against a SQL database using [CL-DBI](https://github.com/fukamachi/cl-dbi) | ‘cl-migratum.driver.sql‘ |

## Usage

The following section contains some examples to get you started.

### Create Provider

First, we will create a new ‘provider‘ that can discover migration files from a
local path. In order to create a ‘local-path‘ provider we need to load the
system for the respective provider.

“‘ common-lisp
CL-USER> (ql:quickload :cl-migratum.provider.local-path)

“‘

Once you load the system we can create a ‘local-path‘ provider.

“‘ common-lisp
CL-USER> (defparameter *provider*
(migratum.provider.local-path:make-local-path-provider #P"~/Projects/lisp/cl-migratum/t/migrations/"))
*PROVIDER*
“‘

The ‘LOCAL-PATH-PROVIDER‘ discovers migration files which match the following pattern.

| Pattern | Description |
|——————————-|——————|
| ‘<id>-<description>.up.sql‘ | Upgrade script |
| ‘<id>-<description>.down.sql‘ | Downgrade script |

A provider can optionally be initialized, which can be done using the
‘MIGRATUM:PROVIDER-INIT‘ generic function. Not all providers would
require initialization, but some will and therefore it is good that
you always initialize them first.

In order to list the migrations provided by a ‘provider‘ you can use
the ‘MIGRATUM:PROVIDER-LIST-MIGRATIONS‘ generic function, e.g.

“‘ common-lisp
CL-USER> (migratum:provider-list-migrations *provider*)
(#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {100527E5D3}>
#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {100527E673}>
#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {100527E713}>)
“‘

The following generic functions can be used to interact with
discovered migrations.

| Method | Description | |—————————————|———————————————————|
| ‘MIGRATUM:MIGRATION-ID‘ | Returns the unique migration id |
| ‘MIGRATUM:MIGRATION-DESCRIPTION‘ | Returns the description of the migration |
| ‘MIGRATUM:MIGRATION-APPLIED‘ | Returns the timestamp of when the migration was applied |
| ‘MIGRATUM:MIGRATION-LOAD-UP-SCRIPT‘ | Returns the upgrade script of the migration |
| ‘MIGRATUM:MIGRATION-LOAD-DOWN-SCRIPT‘ | Returns the downgrade script of the migration |

For example in order to collect the unique IDs of migration resources you can
evaluate the following expression.

“‘ common-lisp
CL-USER> (mapcar #’migratum:migration-id
(migratum:provider-list-migrations *provider*))
(20200421180337 20200421173908 20200421173657)
“‘

### Create Driver

Once we have a provider for discovering migration resources we need to
create a driver, which can be used to communicate with the database
we want to apply migrations on.

Here is how we can create a ‘SQL‘ driver. First, lets load the
system, which provides that driver.

“‘ common-lisp
CL-USER> (ql:quickload :cl-migratum.driver.sql)
“‘

The SQL driver uses [CL-DBI](https://github.com/fukamachi/cl-dbi)
interface to communicate with the database, so we will need to create
a database connection.

“‘ common-lisp
CL-USER> (defparameter *conn*
(dbi:connect :sqlite3 :database-name "/Users/dnaeon/cl-migratum.db"))
*CONN*
“‘

And now we can instantiate our SQL driver using the previously created
provider and connection.

“‘ common-lisp
CL-USER> (defparameter *driver*
(migratum.driver.sql:make-sql-driver *provider* *conn*))
*DRIVER*
“‘

### Initialize Driver

Each driver may require some initialization steps to be executed
before being able to apply migrations, so make sure that you
initialize a driver once you create it.

An example requirement for a driver might be to create some required
database schema used to track which migrations have been applied
already, so lets initialize our driver first.

“‘ common-lisp
CL-USER> (migratum:driver-init *driver*)
“‘

### Pending Migrations

In order to get the list of pending (not applied yet) migrations we can
use the ‘MIGRATUM:LIST-PENDING‘ function, e.g.

“‘ common-lisp
CL-USER> (migratum:list-pending *driver*)
(#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {10052A0583}>
#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {10052A0623}>
#<CL-MIGRATUM.PROVIDER.LOCAL-PATH:LOCAL-PATH-MIGRATION {10052A06C3}>)
“‘

Or, we can display a table of the pending migrations using the
‘MIGRATUM:DISPLAY-PENDING‘ function instead.

“‘ common-lisp
CL-USER> (migratum:display-pending *driver*)
.———————————–.
| PENDING MIGRATIONS |
+—————-+——————+
| ID | DESCRIPTION |
+—————-+——————+
| 20200421173657 | create_table_foo |
| 20200421173908 | create_table_bar |
| 20200421180337 | create_table_qux |
+—————-+——————+
| TOTAL | 3 |
+—————-+——————+
NIL
“‘

The migrations will be sorted in the order they need to be applied.

### Applying Migrations

The following functions are used for applying pending migrations.

* ‘MIGRATUM:APPLY-PENDING‘ - applies all pending migrations
* ‘MIGRATUM:APPLY-NEXT‘ - applies the next pending migration

This is how we can apply all pending migrations for example.

“‘ common-lisp
CL-USER> (migratum:apply-pending *driver*)
<INFO> [18:10:14] cl-migratum.core core.lisp (apply-pending) -
Found 3 pending migration(s) to be applied
<INFO> [18:10:14] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20200421173657 - create_table_foo
<INFO> [18:10:14] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20200421173908 - create_table_bar
<INFO> [18:10:14] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20200421180337 - create_table_qux
NIL
“‘

### Get Latest Migration

You can use the ‘MIGRATUM:LATEST-MIGRATION‘ function to get the latest
applied migration, e.g.

“‘ common-lisp
CL-USER> (migratum:migration-id (migratum:latest-migration *driver*))
20200421180337
“‘

The ‘MIGRATUM:CONTAINS-APPLIED-MIGRATIONS-P‘ predicate can be used to
query whether there are any migrations applied, e.g.

“‘ common-lisp
CL-USER> (migratum:contains-applied-migrations-p *driver*)
T
“‘

### Displaying Applied Migrations

The following functions can be used to get and display the
list of applied database migrations.

| Function | Description | |——————————–|—————————————-|
| ‘MIGRATUM:DRIVER-LIST-APPLIED‘ | Returns the list of applied migrations |
| ‘MIGRATUM:DISPLAY-APPLIED‘ | Display a table of applied migrations |

This is how we can get the list of applied migrations.

“‘ common-lisp
CL-USER> (migratum:driver-list-applied *driver*)
(#<CL-MIGRATUM.CORE:MIGRATION {1006095B23}>
#<CL-MIGRATUM.CORE:MIGRATION {1006095B73}>
#<CL-MIGRATUM.CORE:MIGRATION {1006095BC3}>)
“‘

Or we can display a nice table of the applied migrations instead.

“‘ common-lisp
CL-USER> (migratum:display-applied *driver*)
.———————————————————.
| APPLIED MIGRATIONS |
+—————-+——————+———————+
| ID | DESCRIPTION | APPLIED |
+—————-+——————+———————+
| 20200421180337 | create_table_qux | 2020-04-21 15:17:46 |
| 20200421173908 | create_table_bar | 2020-04-21 15:14:13 |
| 20200421173657 | create_table_foo | 2020-04-21 15:12:52 |
+—————-+——————+———————+
| | TOTAL | 3 |
+—————-+——————+———————+
NIL
“‘

The output of these functions will be the applied migrations in
descending order by their id, first one being the most recent one.

The ‘SQL‘ driver by default will fetch the last 100 applied
migrations. You can control this behaviour by using the ‘:offset‘ and
‘:limit‘ keyword parameters, which allows you to fetch applied
migrations in pages.

For example, if you are interested only in the last ten applied
migrations you can evaluate the following expression.

“‘ common-lisp
CL-USER> (migratum:display-applied *driver* :limit 10)
“‘

Or if you want to skip the first ten migrations, you can evaluate
this expression instead.

“‘ common-lisp
CL-USER> (migratum.display-applied *driver* :offset 10 :limit 10)
“‘

### Stepping through migrations

Using the following functions you can step through migrations.

| Function | Description |
|————————|————————————–|
| ‘MIGRATUM:APPLY-NEXT‘ | Apply the next pending migration(s) |
| ‘MIGRATUM:REVERT-LAST‘ | Revert the last applied migration(s) |

This is useful in situations when you don’t want to apply
all migrations at once, but rather do it one at a time. Both of these
functions accept a keyword parameter ‘:count‘ which specifies the
number of migrations to apply or revert.

Consider the following pending migrations.

“‘ common-lisp
CL-USER> (migratum:display-pending *driver*)
.———————————–.
| PENDING MIGRATIONS |
+—————-+——————+
| ID | DESCRIPTION |
+—————-+——————+
| 20200421173657 | create_table_foo |
| 20200421173908 | create_table_bar |
| 20200421180337 | create_table_qux |
+—————-+——————+
| TOTAL | 3 |
+—————-+——————+
NIL
“‘

We can apply them one by one and verify them as we go.

“‘ common-lisp
CL-USER> (migratum:apply-next *driver*)
<INFO> [20:04:25] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20200421173657 - create_table_foo
NIL
CL-USER> (migratum:apply-next *driver*)
<INFO> [20:04:28] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20200421173908 - create_table_bar
NIL
CL-USER> (migratum:apply-next *driver*)
<INFO> [20:04:29] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20200421180337 - create_table_qux
NIL
“‘

If we want to revert the last three migrations we can use the
‘MIGRATUM:REVERT-LAST‘ function, e.g.

“‘ common-lisp
CL-USER> (migratum:revert-last *driver* :count 3)
<INFO> [20:06:00] cl-migratum.core core.lisp (revert-and-unregister) -
Reverting migration 20200421180337 - create_table_qux
<INFO> [20:06:00] cl-migratum.core core.lisp (revert-and-unregister) -
Reverting migration 20200421173908 - create_table_bar
<INFO> [20:06:00] cl-migratum.core core.lisp (revert-and-unregister) -
Reverting migration 20200421173657 - create_table_foo
NIL
“‘

### Creating New Migrations

The ‘MIGRATUM:PROVIDER-CREATE-MIGRATION‘ generic function creates a
new migration sequence, when supported by the provider that you are
using.

Here’s one example of creating a new migration, which also specifies
the upgrade and downgrade scripts as part of the keyword parameters.

“‘ common-lisp
CL-USER> (defparameter *migration*
(migratum:provider-create-migration *provider*
:description "create table fubar"
:up "CREATE TABLE fubar (id INTEGER PRIMARY KEY);"
:down "DROP TABLE fubar;"))
*MIGRATION*
“‘

We can also inspect the newly created migration, e.g.

“‘ common-lisp
CL-USER> (migratum:migration-id *migration*)
20200421201406
CL-USER> (migratum:migration-description *migration*)
"create_table_fubar"
CL-USER> (migratum:migration-load-up-script *migration*)
"CREATE TABLE fubar (id INTEGER PRIMARY KEY);"
CL-USER> (migratum:migration-load-down-script *migration*)
"DROP TABLE fubar;"
“‘

### Multiple Statements

If you need to run multiple statements when using the ‘sql‘ driver you
can separate each statement in the migration using the ‘–;;‘
separator.

The following example migration would create two tables as part of a
single transaction.

“‘ sql
CREATE TABLE foo (
id INTEGER PRIMARY KEY
);
–;;
CREATE TABLE bar (
id INTEGER PRIMARY KEY
);
“‘

### Debug logging

‘cl-migratum‘ uses [log4cl](https://github.com/sharplispers/log4cl),
so you can enable debug logging, if needed.

“‘ common-lisp
CL-USER> (log:config :debug)
“‘

## Implemeting new migration resources

Generally new migration resources will be implemented along with a
‘provider‘, which discovers them.

You can implement a new migration resource by subclassing the
‘MIGRATUM:BASE-MIGRATION‘ class.

The following generic functions should be implemented on the newly
defined class.

| Method | Description |
|—————————————|——————————|
| ‘MIGRATUM:MIGRATION-LOAD-UP-SCRIPT‘ | Returns the upgrade script |
| ‘MIGRATUM:MIGRATION-LOAD-DOWN-SCRIPT‘ | Returns the downgrade script |

The following generic functions can be overriden, if needed.

| Method | Description | |———————————-|—————————————————–|
| ‘MIGRATUM:MIGRATION-ID‘ | Returns the unique migration id |
| ‘MIGRATUM:MIGRATION-DESCRIPTION‘ | Returns description of the migration |
| ‘MIGRATUM:MIGRATION-APPLIED‘ | Returns timestamp of when the migration was applied |

Example implementation that loads migration resources from a remote
HTTP server might look like this. The following code uses
[Dexador](https://github.com/fukamachi/dexador) as the HTTP client.

“‘ common-lisp
(defun http-get (url)
"HTTP GETs the given URL"
(let ((contents (dex:get url :force-string t)))
contents))

(defclass http-migration (base-migration)
((up-script-url
:initarg :up-script-url
:initform (error "Must specify URL to upgrade script")
:accessor http-migration-up-script-url
:documentation "URL to the upgrade script")
(down-script-url
:initarg :down-script-url
:initform (error "Must specify URL to downgrade script")
:accessor http-migration-down-script-url
:documentation "URL to the downgrade script"))
(:documentation "HTTP migration resource"))

(defmethod migration-load-up-script ((migration http-migration) &key)
(http-get (http-migration-up-script-url migration)))

(defmethod migration-load-down-script ((migration http-migration) &key)
(http-get (http-migration-down-script-url migration)))
“‘

A provider should simply ‘MAKE-INSTANCE‘ of the ‘HTTP-MIGRATION‘ class by
providing values for the required slots while discovering migrations via
the ‘PROVIDER-LIST-MIGRATIONS‘ function.

## Implementing new providers

You can implement custom ‘providers‘, which can discover migration
resources from various sources, e.g. local path, remote HTTP endpoints,
etc.

Each ‘provider‘ determines the rules, which identify a resource as a
valid migration, so custom logic for discovering them can be
implemented by using your own provider. For example the ‘local-path‘
provider considers files to be valid migrations, if they match a given
regex pattern.

In order to create a new provider you can subclass the
‘MIGRATUM:BASE-PROVIDER‘ class and implement the following generic
functions on your newly defined class.

| Method | Description | |————————————–|——————————————–|
| ‘MIGRATUM:PROVIDER-LIST-MIGRATIONS‘ | Responsible for discovering migrations |
| ‘MIGRATUM:PROVIDER-CREATE-MIGRATION‘ | Creates a new migration using the provider |

The following methods can be overriden, if needed.

| Method | Description | |———————————|———————————————————|
| ‘MIGRATUM:PROVIDER-NAME‘ | Returns a human-friendly name of the provider |
| ‘MIGRATUM:PROVIDER-INIT‘ | Initializes the provider, if needed |
| ‘MIGRATUM:PROVIDER-INITIALIZED‘ | Returns ‘T‘ if provider is initialized, ‘NIL‘ otherwise |

You can also check the [local-path
provider](./src/provider/local-path.lisp) implementation for some
example code.

## Implementing new drivers

A ‘driver‘ is responsible for communicating with the database we are
migrating and actually executing the upgrade and downgrade scripts.

The driver also takes care of registering applied migrations after
applying an upgrade script and also unregistering them during
downgrade, thus it is the drivers’ decision how to implement
registering and unregistering. For example the ‘sql‘ builtin driver
registers applied migrations on the same database it is migrating, but
a custom driver could choose a different stategy instead, e.g. use a
key/value store, local files, or some remote endpoint instead.

New drivers can be implemented by subclassing the
‘MIGRATUM:BASE-DRIVER‘ class. The following methods should be
implemented on drivers.

| Method | Description | |—————————————-|——————————————–|
| ‘MIGRATUM:DRIVER-LIST-APPLIED‘ | Returns the list of applied migrations |
| ‘MIGRATUM:DRIVER-REGISTER-MIGRATION‘ | Registers a successfully applied migration |
| ‘MIGRATUM:DRIVER-UNREGISTER-MIGRATION‘ | Unregisters previously applied migration |
| ‘MIGRATUM:DRIVER-APPLY-UP-MIGRATION‘ | Executes the upgrade script |
| ‘MIGRATUM:DRIVER-APPLY-DOWN-MIGRATION‘ | Executes the downgrade script |

The following methods can be overriden, if needed.

| Method | Description | |——————————-|——————————————————-|
| ‘MIGRATUM:DRIVER-INIT‘ | Initializes the driver, if needed |
| ‘MIGRATUM:DRIVER-NAME‘ | Returns the human-friendly name of the driver |
| ‘MIGRATUM:DRIVER-PROVIDER‘ | Returns the ‘provider‘ used by the ‘driver‘ |
| ‘MIGRATUM:DRIVER-INITIALIZED‘ | Returns ‘T‘ if driver is initialized, ‘NIL‘ otherwise |

You can check the [sql driver](./src/driver/sql.lisp) implementation
for some example code.

## Tests

Tests are provided as part of the ‘cl-migratum.test‘ system.

In order to run the tests you can evaluate the following expressions.

“‘ common-lisp
CL-USER> (ql:quickload :cl-migratum.test)
CL-USER> (asdf:test-system :cl-migratum.test)
“‘

Or you can run the tests in a Docker container instead.

First, build the Docker image.

“‘ shell
docker build -t cl-migratum .
“‘

Run the tests.

“‘ shell
docker run –rm cl-migratum
“‘

## Contributing

‘cl-migratum‘ is hosted on
[Github](https://github.com/dnaeon/cl-migratum). Please contribute by
reporting issues, suggesting features or by sending patches using pull
requests.

## Authors

* Marin Atanasov Nikolov (dnaeon@gmail.com)

## License

This project is Open Source and licensed under the [BSD
License](http://opensource.org/licenses/BSD-2-Clause).

Version

0.1.0

Dependencies
Source

cl-migratum.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 cl-migratum/util

Parent

cl-migratum (system)

Location

src/

Component

util.lisp (file)


Next: , Previous: , Up: Modules   [Contents][Index]

3.2 cl-migratum/core

Dependency

util (module)

Parent

cl-migratum (system)

Location

src/

Component

core.lisp (file)


Previous: , Up: Modules   [Contents][Index]

3.3 cl-migratum/client-package

Dependencies
Parent

cl-migratum (system)

Location

src/

Component

package.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cl-migratum.asd

Location

cl-migratum.asd

Systems

cl-migratum (system)

Packages

cl-migratum-system


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cl-migratum/util/util.lisp

Parent

util (module)

Location

src/util.lisp

Packages

cl-migratum.util

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 cl-migratum/core/core.lisp

Parent

core (module)

Location

src/core.lisp

Packages

cl-migratum.core

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.4 cl-migratum/client-package/package.lisp

Parent

client-package (module)

Location

src/package.lisp

Packages

cl-migratum


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 cl-migratum-system

Source

cl-migratum.asd

Use List

Next: , Previous: , Up: Packages   [Contents][Index]

5.2 cl-migratum.util

Source

util.lisp (file)

Nickname

migratum.util

Use List

common-lisp

Exported Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

5.3 cl-migratum.core

Source

core.lisp (file)

Nickname

migratum.core

Use List

common-lisp

Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

5.4 cl-migratum

Source

package.lisp (file)

Nickname

migratum

Use List

common-lisp


Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Functions

Function: apply-next DRIVER &key COUNT

Apply the next COUNT of pending migrations

Package

cl-migratum.core

Source

core.lisp (file)

Function: apply-pending DRIVER

Applies the pending migrations

Package

cl-migratum.core

Source

core.lisp (file)

Function: contains-applied-migrations-p DRIVER

Predicate for testing whether we have any migrations applied

Package

cl-migratum.core

Source

core.lisp (file)

Function: display-applied DRIVER &rest REST

Displays the applied migrations in a table

Package

cl-migratum.core

Source

core.lisp (file)

Function: display-pending DRIVER

Display the pending migrations in a table

Package

cl-migratum.core

Source

core.lisp (file)

Function: latest-migration DRIVER

Returns the latest applied migration

Package

cl-migratum.core

Source

core.lisp (file)

Function: list-pending DRIVER

Returns the list of migrations that have not been applied yet

Package

cl-migratum.core

Source

core.lisp (file)

Function: make-migration-id ()

Creates a new migration id

Package

cl-migratum.util

Source

util.lisp (file)

Function: provider-find-migration-by-id PROVIDER ID

Returns the migration with the given id from the provider

Package

cl-migratum.core

Source

core.lisp (file)

Function: revert-last DRIVER &key COUNT

Reverts the last COUNT applied migrations

Package

cl-migratum.core

Source

core.lisp (file)

Function: take N SEQUENCE

Take N items from the given sequence

Package

cl-migratum.util

Source

util.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Generic functions

Generic Function: driver-apply-down-migration DRIVER MIGRATION &key

Applies the downgrade migration script using the given driver

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: driver-apply-up-migration DRIVER MIGRATION &key

Applies the upgrade migration script using the given driver

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: driver-init DRIVER &key

Initializes the driver, e.g. creates required schema

Package

cl-migratum.core

Source

core.lisp (file)

Methods
Method: driver-init (DRIVER base-driver) &key
Generic Function: driver-initialized OBJECT
Generic Function: (setf driver-initialized) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: driver-initialized (BASE-DRIVER base-driver)
Method: (setf driver-initialized) NEW-VALUE (BASE-DRIVER base-driver)

Returns T if driver is initialized, NIL otherwise

Source

core.lisp (file)

Generic Function: driver-list-applied DRIVER &key

Returns a list of the applied migrations in descending order

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: driver-name OBJECT
Generic Function: (setf driver-name) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: driver-name (BASE-DRIVER base-driver)
Method: (setf driver-name) NEW-VALUE (BASE-DRIVER base-driver)

Name of the driver

Source

core.lisp (file)

Generic Function: driver-provider OBJECT
Generic Function: (setf driver-provider) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: driver-provider (BASE-DRIVER base-driver)
Method: (setf driver-provider) NEW-VALUE (BASE-DRIVER base-driver)

Provider used by the driver

Source

core.lisp (file)

Generic Function: driver-register-migration DRIVER MIGRATION &key

Registers a successfully applied migration

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: driver-unregister-migration DRIVER MIGRATION &key

Unregisters a previously applied migration

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: migration-applied OBJECT
Generic Function: (setf migration-applied) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: migration-applied (BASE-MIGRATION base-migration)
Method: (setf migration-applied) NEW-VALUE (BASE-MIGRATION base-migration)

Timestamp when the migration was applied

Source

core.lisp (file)

Generic Function: migration-description OBJECT
Generic Function: (setf migration-description) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: migration-description (BASE-MIGRATION base-migration)
Method: (setf migration-description) NEW-VALUE (BASE-MIGRATION base-migration)

Description of the migration

Source

core.lisp (file)

Generic Function: migration-id OBJECT
Generic Function: (setf migration-id) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: migration-id (BASE-MIGRATION base-migration)
Method: (setf migration-id) NEW-VALUE (BASE-MIGRATION base-migration)

Unique migration id

Source

core.lisp (file)

Generic Function: migration-load-down-script MIGRATION &key

Returns the contents of the downgrade migration script

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: migration-load-up-script MIGRATION &key

Returns the contents of the upgrade migration script

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: provider-create-migration PROVIDER &key ID DESCRIPTION UP DOWN

Creates a new migration resource using the given provider

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: provider-init PROVIDER &key

Initializes the driver, if needed

Package

cl-migratum.core

Source

core.lisp (file)

Methods
Method: provider-init (PROVIDER base-provider) &key
Generic Function: provider-initialized OBJECT
Generic Function: (setf provider-initialized) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: provider-initialized (BASE-PROVIDER base-provider)
Method: (setf provider-initialized) NEW-VALUE (BASE-PROVIDER base-provider)

Returns T if provider is initialized, NIL otherwise

Source

core.lisp (file)

Generic Function: provider-list-migrations PROVIDER &key

Returns the list of migration resources discovered by the provider

Package

cl-migratum.core

Source

core.lisp (file)

Generic Function: provider-name OBJECT
Generic Function: (setf provider-name) NEW-VALUE OBJECT
Package

cl-migratum.core

Methods
Method: provider-name (BASE-PROVIDER base-provider)
Method: (setf provider-name) NEW-VALUE (BASE-PROVIDER base-provider)

Name of the provider

Source

core.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Classes

Class: base-driver ()

Base class for migration drivers

Package

cl-migratum.core

Source

core.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: name

Name of the driver

Type

string

Initargs

:name

Initform

(error "must specify driver name")

Readers

driver-name (generic function)

Writers

(setf driver-name) (generic function)

Slot: provider

Provider used by the driver

Initargs

:provider

Initform

(error "must specify migrations provider")

Readers

driver-provider (generic function)

Writers

(setf driver-provider) (generic function)

Slot: initialized

Returns T if driver is initialized, NIL otherwise

Initargs

:initialized

Readers

driver-initialized (generic function)

Writers

(setf driver-initialized) (generic function)

Class: base-migration ()

Base class for migration resources

Package

cl-migratum.core

Source

core.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: id

Unique migration id

Type

integer

Initargs

:id

Initform

(error "must specify migration id")

Readers

migration-id (generic function)

Writers

(setf migration-id) (generic function)

Slot: description

Description of the migration

Type

string

Initargs

:description

Initform

(error "must specify migration description")

Readers

migration-description (generic function)

Writers

(setf migration-description) (generic function)

Slot: applied

Timestamp when the migration was applied

Initargs

:applied

Readers

migration-applied (generic function)

Writers

(setf migration-applied) (generic function)

Class: base-provider ()

Base class for migration providers

Package

cl-migratum.core

Source

core.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: name

Name of the provider

Type

string

Initargs

:name

Initform

(error "must specify provider name")

Readers

provider-name (generic function)

Writers

(setf provider-name) (generic function)

Slot: initialized

Returns T if provider is initialized, NIL otherwise

Initargs

:initialized

Readers

provider-initialized (generic function)

Writers

(setf provider-initialized) (generic function)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Functions

Function: apply-and-register DRIVER MIGRATION

Applies the migration and registers it

Package

cl-migratum.core

Source

core.lisp (file)

Function: revert-and-unregister DRIVER MIGRATION

Reverts and unregisters a given migration.
The migration to be reverted is first loaded via the driver provider, in order to ensure we can load the downgrade script.

Package

cl-migratum.core

Source

core.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-migratum.asd: The cl-migratum․asd file
cl-migratum/client-package: The cl-migratum/client-package module
cl-migratum/client-package/package.lisp: The cl-migratum/client-package/package․lisp file
cl-migratum/core: The cl-migratum/core module
cl-migratum/core/core.lisp: The cl-migratum/core/core․lisp file
cl-migratum/util: The cl-migratum/util module
cl-migratum/util/util.lisp: The cl-migratum/util/util․lisp file

F
File, Lisp, cl-migratum.asd: The cl-migratum․asd file
File, Lisp, cl-migratum/client-package/package.lisp: The cl-migratum/client-package/package․lisp file
File, Lisp, cl-migratum/core/core.lisp: The cl-migratum/core/core․lisp file
File, Lisp, cl-migratum/util/util.lisp: The cl-migratum/util/util․lisp file

L
Lisp File, cl-migratum.asd: The cl-migratum․asd file
Lisp File, cl-migratum/client-package/package.lisp: The cl-migratum/client-package/package․lisp file
Lisp File, cl-migratum/core/core.lisp: The cl-migratum/core/core․lisp file
Lisp File, cl-migratum/util/util.lisp: The cl-migratum/util/util․lisp file

M
Module, cl-migratum/client-package: The cl-migratum/client-package module
Module, cl-migratum/core: The cl-migratum/core module
Module, cl-migratum/util: The cl-migratum/util module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   F   G   L   M   P   R   T  
Index Entry  Section

(
(setf driver-initialized): Exported generic functions
(setf driver-initialized): Exported generic functions
(setf driver-name): Exported generic functions
(setf driver-name): Exported generic functions
(setf driver-provider): Exported generic functions
(setf driver-provider): Exported generic functions
(setf migration-applied): Exported generic functions
(setf migration-applied): Exported generic functions
(setf migration-description): Exported generic functions
(setf migration-description): Exported generic functions
(setf migration-id): Exported generic functions
(setf migration-id): Exported generic functions
(setf provider-initialized): Exported generic functions
(setf provider-initialized): Exported generic functions
(setf provider-name): Exported generic functions
(setf provider-name): Exported generic functions

A
apply-and-register: Internal functions
apply-next: Exported functions
apply-pending: Exported functions

C
contains-applied-migrations-p: Exported functions

D
display-applied: Exported functions
display-pending: Exported functions
driver-apply-down-migration: Exported generic functions
driver-apply-up-migration: Exported generic functions
driver-init: Exported generic functions
driver-init: Exported generic functions
driver-initialized: Exported generic functions
driver-initialized: Exported generic functions
driver-list-applied: Exported generic functions
driver-name: Exported generic functions
driver-name: Exported generic functions
driver-provider: Exported generic functions
driver-provider: Exported generic functions
driver-register-migration: Exported generic functions
driver-unregister-migration: Exported generic functions

F
Function, apply-and-register: Internal functions
Function, apply-next: Exported functions
Function, apply-pending: Exported functions
Function, contains-applied-migrations-p: Exported functions
Function, display-applied: Exported functions
Function, display-pending: Exported functions
Function, latest-migration: Exported functions
Function, list-pending: Exported functions
Function, make-migration-id: Exported functions
Function, provider-find-migration-by-id: Exported functions
Function, revert-and-unregister: Internal functions
Function, revert-last: Exported functions
Function, take: Exported functions

G
Generic Function, (setf driver-initialized): Exported generic functions
Generic Function, (setf driver-name): Exported generic functions
Generic Function, (setf driver-provider): Exported generic functions
Generic Function, (setf migration-applied): Exported generic functions
Generic Function, (setf migration-description): Exported generic functions
Generic Function, (setf migration-id): Exported generic functions
Generic Function, (setf provider-initialized): Exported generic functions
Generic Function, (setf provider-name): Exported generic functions
Generic Function, driver-apply-down-migration: Exported generic functions
Generic Function, driver-apply-up-migration: Exported generic functions
Generic Function, driver-init: Exported generic functions
Generic Function, driver-initialized: Exported generic functions
Generic Function, driver-list-applied: Exported generic functions
Generic Function, driver-name: Exported generic functions
Generic Function, driver-provider: Exported generic functions
Generic Function, driver-register-migration: Exported generic functions
Generic Function, driver-unregister-migration: Exported generic functions
Generic Function, migration-applied: Exported generic functions
Generic Function, migration-description: Exported generic functions
Generic Function, migration-id: Exported generic functions
Generic Function, migration-load-down-script: Exported generic functions
Generic Function, migration-load-up-script: Exported generic functions
Generic Function, provider-create-migration: Exported generic functions
Generic Function, provider-init: Exported generic functions
Generic Function, provider-initialized: Exported generic functions
Generic Function, provider-list-migrations: Exported generic functions
Generic Function, provider-name: Exported generic functions

L
latest-migration: Exported functions
list-pending: Exported functions

M
make-migration-id: Exported functions
Method, (setf driver-initialized): Exported generic functions
Method, (setf driver-name): Exported generic functions
Method, (setf driver-provider): Exported generic functions
Method, (setf migration-applied): Exported generic functions
Method, (setf migration-description): Exported generic functions
Method, (setf migration-id): Exported generic functions
Method, (setf provider-initialized): Exported generic functions
Method, (setf provider-name): Exported generic functions
Method, driver-init: Exported generic functions
Method, driver-initialized: Exported generic functions
Method, driver-name: Exported generic functions
Method, driver-provider: Exported generic functions
Method, migration-applied: Exported generic functions
Method, migration-description: Exported generic functions
Method, migration-id: Exported generic functions
Method, provider-init: Exported generic functions
Method, provider-initialized: Exported generic functions
Method, provider-name: Exported generic functions
migration-applied: Exported generic functions
migration-applied: Exported generic functions
migration-description: Exported generic functions
migration-description: Exported generic functions
migration-id: Exported generic functions
migration-id: Exported generic functions
migration-load-down-script: Exported generic functions
migration-load-up-script: Exported generic functions

P
provider-create-migration: Exported generic functions
provider-find-migration-by-id: Exported functions
provider-init: Exported generic functions
provider-init: Exported generic functions
provider-initialized: Exported generic functions
provider-initialized: Exported generic functions
provider-list-migrations: Exported generic functions
provider-name: Exported generic functions
provider-name: Exported generic functions

R
revert-and-unregister: Internal functions
revert-last: Exported functions

T
take: Exported functions

Jump to:   (  
A   C   D   F   G   L   M   P   R   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   A   D   I   N   P   S  
Index Entry  Section

A
applied: Exported classes

D
description: Exported classes

I
id: Exported classes
initialized: Exported classes
initialized: Exported classes

N
name: Exported classes
name: Exported classes

P
provider: Exported classes

S
Slot, applied: Exported classes
Slot, description: Exported classes
Slot, id: Exported classes
Slot, initialized: Exported classes
Slot, initialized: Exported classes
Slot, name: Exported classes
Slot, name: Exported classes
Slot, provider: Exported classes

Jump to:   A   D   I   N   P   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   P   S  
Index Entry  Section

B
base-driver: Exported classes
base-migration: Exported classes
base-provider: Exported classes

C
cl-migratum: The cl-migratum system
cl-migratum: The cl-migratum package
cl-migratum-system: The cl-migratum-system package
cl-migratum.core: The cl-migratum․core package
cl-migratum.util: The cl-migratum․util package
Class, base-driver: Exported classes
Class, base-migration: Exported classes
Class, base-provider: Exported classes

P
Package, cl-migratum: The cl-migratum package
Package, cl-migratum-system: The cl-migratum-system package
Package, cl-migratum.core: The cl-migratum․core package
Package, cl-migratum.util: The cl-migratum․util package

S
System, cl-migratum: The cl-migratum system

Jump to:   B   C   P   S