Usage
saitama
, once installed, offers a single command, punch
, that controls the migrations and the testing.
punch
follows the GNU recommendations for command line interfaces, and offers:
-h
or--help
to print help, and-V
or--version
to print the version
Migrations
You can use punch
to migrate forward or backward to a specific migration.
The migrations should be named \d+_.+\.sql
. Backwards are considered all the migrations
that the first underscore after the digits is followed by backwards_
.
usage: punch migrate [-h] [-H HOST] [-P PORT] [-d DBNAME] [-u USER]
[-p PASSWORD] [-s SETTINGS] [-D] [-f] [-b] [-y]
[migration]
positional arguments:
migration The target migration number. If unspecified,
punch will migrate to latest one
optional arguments:
-h, --help Show this help message and exit
-H HOST, --host HOST The postgres host
-P PORT, --port PORT The postgres port
-d DBNAME, --dbname DBNAME The postgres database
-u USER, --user USER The postgres user
-p PASSWORD, --password PASSWORD The user's password
-s SETTINGS, --settings SETTINGS The path to the settings file
-D, --drop Drop the existing db and create a new one
-f, --fake Fake the migrations up to the specified one
-b, --backwards Backwards migration
-y, --yes Run in non-interactive mode
Writing a migration
In order to write a migration you just have to write an sql file:
-- /path/to/0001_initial_migration.sql
CREATE TABLE users(
user_id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
username TEXT,
password TEXT
);
You can also specify a backwards migration
-- /path/to/0001_backwards_initial_migration.sql
DROP TABLE users;
Testing
Testing will create a database named test_<dbname>
,
run all the migrations to this database, run the tests in the test directory,
and produce a report. An exit code 1 is returned if any assertion fails.
usage: punch test [-h] [-H HOST] [-P PORT] [-d DBNAME] [-u USER] [-p PASSWORD]
[-s SETTINGS]
optional arguments:
-h, --help Show this help message and exit
-H HOST, --host HOST The postgres host
-P PORT, --port PORT The postgres port
-d DBNAME, --dbname DBNAME The postgres database
-u USER, --user USER The postgres user
-p PASSWORD, --password PASSWORD The user's password
-s SETTINGS, --settings SETTINGS The path to the settings file
Writing a test
In order to write a migration you just have to write an PL/pgSQL function in an sql
file which returns the result of unittest.result();
.
You can make assertions by calling unittest.assert
.
The function should be in the unittest
schema.
-- /path/to/test_name.sql
CREATE FUNCTION unittest.bar()
RETURNS unittest.test_result
LANGUAGE plpgsql
AS
$$
DECLARE
_cnt INT;
BEGIN
INSERT
INTO users (username, password)
VALUES ('user', 'hashed_and_salted_password');
SELECT count(*)
FROM users
INTO _cnt;
PERFORM unittest.assert(_cnt <> 0, 'No user was created!');
RETURN unittest.result();
END
$$;