The database-migrations Reference Manual

Table of Contents

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

The database-migrations Reference Manual

This is the database-migrations Reference Manual, version 1.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 13:54:06 2019 GMT+0.


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

1 Introduction

h1. database-migrations

database-migrations is a system roughly equivalent to rails migrations for common lisp.  It allows you to migrate your database from one version to another in an easy manner.

h2. documentation

The system is very simple, so there isn't really much documentation available besides the docstrings.  They should be sufficient for your needs.

h2. example

I use the current unix system time to name my migrations.  You may use any number, as long as its positive.

First create the migrations for your system and write them in your source.  To easen the burden, there is a package available to do this work in.  You may however prefer to make one of your own.

  (in-package :migration-user)
  
  (setf *db-connection-parameters* '("database-name" "database-user" "database-password" "hostname-or-server-connection-path"))
  
  (def-query-migration 1239884301 "create users"
    :execute "CREATE TABLE application_user ( user_id SERIAL PRIMARY KEY, name text, email text )"
    :revert  "DROP TABLE application_user")
  (def-query-migration 1239884351 "create books"
    :execute "CREATE TABLE book ( book_id SERIAL PRIMARY KEY, owner_id INTEGER REFERENCES application_user, title text, description text )"
    :revert  "DROP TABLE book")
  

After loading this source, you can easily update the database in the REPL.  Each of these commands take a version, so you're able to specify how far you want the migration to be done.  The given version is always inclusive (thus downgrade will remove all higher-numbered migrations including that one, and upgrade will add all lower-numbered versions including that one).

  (migration-user::upgrade) ;; this will upgrade the database to the latest version available
  (migration-user::downgrade) ;; this will downgrade the database to the first version



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 database-migrations

Maintainer

Aad Versteden <madnificent@gmail.com>

Author

Aad Versteden <madnificent@gmail.com>

License

MIT

Description

System to version the database in roughly the same way rails migrations work. Differences are that only one database is really supported (but hacking around that is trivial) and that migrations are not needed to be stored in separate files.

Version

1.0

Dependency

postmodern

Source

database-migrations.asd (file)

Component

migrations.lisp (file)


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

3 Files

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


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

3.1 Lisp


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

3.1.1 database-migrations.asd

Location

database-migrations.asd

Systems

database-migrations (system)

Packages

database-migrations.sysdef


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

3.1.2 database-migrations/migrations.lisp

Parent

database-migrations (system)

Location

migrations.lisp

Packages
Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 database-migrations.sysdef

Source

database-migrations.asd

Use List

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

4.2 migration-user

Source

migrations.lisp (file)

Use List

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

4.3 database-migrations

Source

migrations.lisp (file)

Use List
Used By List

migration-user

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Special variables

Special Variable: *db-connection-parameters*

Set the connection settings here, is it will be used to connect to the correct database

Package

database-migrations

Source

migrations.lisp (file)


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

5.1.2 Macros

Macro: def-queries-migration NUMBER SUBJECT &key (EXECUTE EXECUTE-QUERIES) (REVERT REVERT-QUERIES)

Creates a migration for a range of sql queries.
This is similar to def-migration, but instead of allowing one query, it allows you to supply a range of queries. (def-queries-migration 1239888485 "example queries migration"
:execute ("CREATE TABLE application_user ( user_id SERIAL PRIMARY KEY, name text, email text )"
"CREATE TABLE user_books ( book_id SERIAL PRIMARY KEY, owner_id INTEGER REFERENCES application_user, title text )") :revert ("DROP TABLE application_user, user_books CASCADE"))

Package

database-migrations

Source

migrations.lisp (file)

Macro: def-query-migration NUMBER SUBJECT &key EXECUTE REVERT

Creates a migration for an sql query.
This only differs with def-migration in the way execute and revert are defined. In definition both execute and revert are wrapped inside (lambda () (with-db (execute <here be supplied content>))) which allows you to only write the query and not the extra stuff surrounding it. with-db sets up a database environment for the variables set in *db-connection-paramters*

Package

database-migrations

Source

migrations.lisp (file)


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

5.1.3 Functions

Function: def-migration &key NUMBER SUBJECT EXECUTE REVERT

Creates the most basic form of a new migration.
A migration is referred to by its number and subject. Each migration should differ in that combination. Execute must be the function to be called when the migration is applied.
Revert must be the function to be called when the migration is reverted.

Package

database-migrations

Source

migrations.lisp (file)

Function: downgrade &optional VERSION

Downgrades the database to the given version.
This will revert all migrations that have been run with a migration-number greater than <version>.
The migrations are downgraded from the greatest available migration-number, to the lowest.
When no version is given, 0 is assumed as that will clear the database (migration_schema will continue to exist).

Package

database-migrations

Source

migrations.lisp (file)

Function: run-unregistered-migrations FROM TO &optional REVERT

USED ONLY FOR DEBUGGING
Forcibly runs the given migrations without writing the changes in the schema. This is something you should never really need to run.

Package

database-migrations

Source

migrations.lisp (file)

Function: upgrade &optional VERSION

Upgrades the database to the given version.
This will run all migrations that haven’t been ran yet and that have a smaller migration-number than <version>.
The migrations are upgraded from the smallest available migration-number to the largest available one (with a cap on <version>). When no version is given, all available migrations are executed.

Package

database-migrations

Source

migrations.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *migrations*

Contains all the migrations that can be executed

Package

database-migrations

Source

migrations.lisp (file)


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

5.2.2 Macros

Macro: with-db &body BODY
Package

database-migrations

Source

migrations.lisp (file)


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

5.2.3 Functions

Function: copy-migration INSTANCE
Package

database-migrations

Source

migrations.lisp (file)

Function: make-migration &key (NUMBER NUMBER) (SUBJECT SUBJECT) (EXECUTE EXECUTE) (REVERT REVERT)
Package

database-migrations

Source

migrations.lisp (file)

Function: migration-execute INSTANCE
Function: (setf migration-execute) VALUE INSTANCE
Package

database-migrations

Source

migrations.lisp (file)

Function: migration-number INSTANCE
Function: (setf migration-number) VALUE INSTANCE
Package

database-migrations

Source

migrations.lisp (file)

Function: migration-p OBJECT
Package

database-migrations

Source

migrations.lisp (file)

Function: migration-revert INSTANCE
Function: (setf migration-revert) VALUE INSTANCE
Package

database-migrations

Source

migrations.lisp (file)

Function: migration-schema-register MIGRATION

Register a migration as to pretend it has been executed

Package

database-migrations

Source

migrations.lisp (file)

Function: migration-schema-revert MIGRATION

Revert a migration as to pretend it was not executed

Package

database-migrations

Source

migrations.lisp (file)

Function: migration-subject INSTANCE
Function: (setf migration-subject) VALUE INSTANCE
Package

database-migrations

Source

migrations.lisp (file)

Function: run-migration MIGRATION &optional REVERT-P REGISTER-P

Runs a single migration with all possible options

Package

database-migrations

Source

migrations.lisp (file)

Function: schema-has-migration-p MIGRATION

Checks whether or not the schema contains the given migration. The migration is stored by its number and its description.

Package

database-migrations

Source

migrations.lisp (file)


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

5.2.4 Structures

Structure: migration ()
Package

database-migrations

Source

migrations.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: number
Readers

migration-number (function)

Writers

(setf migration-number) (function)

Slot: subject
Readers

migration-subject (function)

Writers

(setf migration-subject) (function)

Slot: execute
Readers

migration-execute (function)

Writers

(setf migration-execute) (function)

Slot: revert
Readers

migration-revert (function)

Writers

(setf migration-revert) (function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
database-migrations.asd: The database-migrations<dot>asd file
database-migrations/migrations.lisp: The database-migrations/migrations<dot>lisp file

F
File, Lisp, database-migrations.asd: The database-migrations<dot>asd file
File, Lisp, database-migrations/migrations.lisp: The database-migrations/migrations<dot>lisp file

L
Lisp File, database-migrations.asd: The database-migrations<dot>asd file
Lisp File, database-migrations/migrations.lisp: The database-migrations/migrations<dot>lisp file

Jump to:   D   F   L  

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

A.2 Functions

Jump to:   (  
C   D   F   M   R   S   U   W  
Index Entry  Section

(
(setf migration-execute): Internal functions
(setf migration-number): Internal functions
(setf migration-revert): Internal functions
(setf migration-subject): Internal functions

C
copy-migration: Internal functions

D
def-migration: Exported functions
def-queries-migration: Exported macros
def-query-migration: Exported macros
downgrade: Exported functions

F
Function, (setf migration-execute): Internal functions
Function, (setf migration-number): Internal functions
Function, (setf migration-revert): Internal functions
Function, (setf migration-subject): Internal functions
Function, copy-migration: Internal functions
Function, def-migration: Exported functions
Function, downgrade: Exported functions
Function, make-migration: Internal functions
Function, migration-execute: Internal functions
Function, migration-number: Internal functions
Function, migration-p: Internal functions
Function, migration-revert: Internal functions
Function, migration-schema-register: Internal functions
Function, migration-schema-revert: Internal functions
Function, migration-subject: Internal functions
Function, run-migration: Internal functions
Function, run-unregistered-migrations: Exported functions
Function, schema-has-migration-p: Internal functions
Function, upgrade: Exported functions

M
Macro, def-queries-migration: Exported macros
Macro, def-query-migration: Exported macros
Macro, with-db: Internal macros
make-migration: Internal functions
migration-execute: Internal functions
migration-number: Internal functions
migration-p: Internal functions
migration-revert: Internal functions
migration-schema-register: Internal functions
migration-schema-revert: Internal functions
migration-subject: Internal functions

R
run-migration: Internal functions
run-unregistered-migrations: Exported functions

S
schema-has-migration-p: Internal functions

U
upgrade: Exported functions

W
with-db: Internal macros

Jump to:   (  
C   D   F   M   R   S   U   W  

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

A.3 Variables

Jump to:   *  
E   N   R   S  
Index Entry  Section

*
*db-connection-parameters*: Exported special variables
*migrations*: Internal special variables

E
execute: Internal structures

N
number: Internal structures

R
revert: Internal structures

S
Slot, execute: Internal structures
Slot, number: Internal structures
Slot, revert: Internal structures
Slot, subject: Internal structures
Special Variable, *db-connection-parameters*: Exported special variables
Special Variable, *migrations*: Internal special variables
subject: Internal structures

Jump to:   *  
E   N   R   S  

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

A.4 Data types

Jump to:   D   M   P   S  
Index Entry  Section

D
database-migrations: The database-migrations system
database-migrations: The database-migrations package
database-migrations.sysdef: The database-migrations<dot>sysdef package

M
migration: Internal structures
migration-user: The migration-user package

P
Package, database-migrations: The database-migrations package
Package, database-migrations.sysdef: The database-migrations<dot>sysdef package
Package, migration-user: The migration-user package

S
Structure, migration: Internal structures
System, database-migrations: The database-migrations system

Jump to:   D   M   P   S