The tulip.pkg.database module exports the database package. The package runs the database migrations when app:run is called, executing all registered migrations.


  • connection_string: string = the connection string

  • migrations_connection_string: string = if set, the connection string to use only for the migrations, in which case the connection is not returned to the pool even if one is configured. This is typically useful to run the migrations with a different role than the rest of the application.

  • migrations: array of tables = the migrations to run, each table being an array of migration steps (string or function, as described in the Migrator) with a 'package' field that identifies for which package the migrations apply, and an optional 'after' field that identifies package names (array of strings) that must have their migrations run before this package.

    The field migrations.check_only can be set to true to prevent this App instance from running the migrations. It will only check that all migrations have been run (by looking at the latest version applied for each registered package) and fail if it is not in sync with its configuration.

    The field migrations.check_timeout can be set to limit the time to wait for migrations in seconds, it defaults to 10.

  • pool: table = if set, configures a connection pool so that calling App:db returns a pooled connection if available, and calling conn:close returns it to the pool if possible. The fields are max_idle, max_open, idle_timeout and life_timeout. Defaults are respectively 2, 0 (unlimited), 0 (no timeout) and 0 (no timeout). A release_connection field can also be set to a function, and it will be called prior to return a connection to the pool. It can be used to e.g. reset session settings, rollback any pending transaction, or release any locks. It receives the connection instance and the app instance as arguments.

#API Extensions

Registering this package provides the following method and field extensions.

#conn | ... = App:db([f, ...])

Returns a connection or, if a function is provided as argument, that function is called with the connection which is then released automatically when the function is done - regardless of whether an error was raised or not - and the call returns the return values of the function or nil and the error message.


  • f: function|nil = function to call with the connection
  • ... = extra arguments are passed to the function after the connection


  • conn: connection = if no function is provided, returns the connection
  • ... = if a function is provided, returns the returned values, or nil and an error.
#v = App:lookup_migrations(name)

Returns the migrations registered for that name, or nil if none.


  • name: string = the name for the registered migrations


  • v: array = the registered migrations
#App:register_migrations(name, migs)

Registers the migrations migs for name. If there are already registered migrations for name, the new ones are appended at the end.


  • name: string = the name of the owner of the migrations
  • migs: array = same as for the migrations configuration field

Back to index

About this wiki

commit 3ebfbd288b8e5c95fdf8ce2027a0e94cfa1c8976
Author: Martin Angers <martin.n.angers@gmail.com>
Date:   2021-02-25T14:07:12-05:00

Update to reflect Request:validate_body
Clone this wiki
https://git.sr.ht/~mna/tulip-wiki (read-only)
git@git.sr.ht:~mna/tulip-wiki (read/write)