The database-migrations Reference Manual

This is the database-migrations Reference Manual, version 1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 05:00:38 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 database-migrations

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.

Maintainer

Aad Versteden <>

Author

Aad Versteden <>

License

MIT

Version

1.0

Dependency

postmodern (system).

Source

database-migrations.asd.

Child Component

migrations.lisp (file).


3 Files

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


3.1 Lisp


3.1.1 database-migrations/database-migrations.asd

Source

database-migrations.asd.

Parent Component

database-migrations (system).

ASDF Systems

database-migrations.

Packages

database-migrations.sysdef.


3.1.2 database-migrations/migrations.lisp

Source

database-migrations.asd.

Parent Component

database-migrations (system).

Packages
Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 database-migrations

Source

migrations.lisp.

Use List
  • common-lisp.
  • postmodern.
Used By List

migration-user.

Public Interface
Internals

4.2 migration-user

Source

migrations.lisp.

Use List

4.3 database-migrations.sysdef

Source

database-migrations.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

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


5.1 Public Interface


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.


5.1.2 Macros

Macro: def-queries-migration (number subject &key execute revert)

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.

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.


5.1.3 Ordinary 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.

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.

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.

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.


5.2 Internals


5.2.1 Special variables

Special Variable: *migrations*

Contains all the migrations that can be executed

Package

database-migrations.

Source

migrations.lisp.


5.2.2 Macros

Macro: with-db (&body body)
Package

database-migrations.

Source

migrations.lisp.


5.2.3 Ordinary functions

Function: copy-migration (instance)
Package

database-migrations.

Source

migrations.lisp.

Function: make-migration (&key number subject execute revert)
Package

database-migrations.

Source

migrations.lisp.

Reader: migration-execute (instance)
Writer: (setf migration-execute) (instance)
Package

database-migrations.

Source

migrations.lisp.

Target Slot

execute.

Reader: migration-number (instance)
Writer: (setf migration-number) (instance)
Package

database-migrations.

Source

migrations.lisp.

Target Slot

number.

Function: migration-p (object)
Package

database-migrations.

Source

migrations.lisp.

Reader: migration-revert (instance)
Writer: (setf migration-revert) (instance)
Package

database-migrations.

Source

migrations.lisp.

Target Slot

revert.

Function: migration-schema-register (migration)

Register a migration as to pretend it has been executed

Package

database-migrations.

Source

migrations.lisp.

Function: migration-schema-revert (migration)

Revert a migration as to pretend it was not executed

Package

database-migrations.

Source

migrations.lisp.

Reader: migration-subject (instance)
Writer: (setf migration-subject) (instance)
Package

database-migrations.

Source

migrations.lisp.

Target Slot

subject.

Function: run-migration (migration &optional revert-p register-p)

Runs a single migration with all possible options

Package

database-migrations.

Source

migrations.lisp.

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.


5.2.4 Structures

Structure: migration
Package

database-migrations.

Source

migrations.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: number
Package

common-lisp.

Readers

migration-number.

Writers

(setf migration-number).

Slot: subject
Readers

migration-subject.

Writers

(setf migration-subject).

Slot: execute
Package

postmodern.

Readers

migration-execute.

Writers

(setf migration-execute).

Slot: revert
Readers

migration-revert.

Writers

(setf migration-revert).


Appendix A Indexes


A.1 Concepts


A.2 Functions

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

(
(setf migration-execute): Private ordinary functions
(setf migration-number): Private ordinary functions
(setf migration-revert): Private ordinary functions
(setf migration-subject): Private ordinary functions

C
copy-migration: Private ordinary functions

D
def-migration: Public ordinary functions
def-queries-migration: Public macros
def-query-migration: Public macros
downgrade: Public ordinary functions

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

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

R
run-migration: Private ordinary functions
run-unregistered-migrations: Public ordinary functions

S
schema-has-migration-p: Private ordinary functions

U
upgrade: Public ordinary functions

W
with-db: Private macros