Man pages for pg_migrate

man/Makefile

@@ -0,0 +1,12 @@
+TARGETS=man1/pg_migrate.1 man5/pg_migrate.5
+
+all: $(TARGETS)
+
+man1/pg_migrate.1: man1/pg_migrate.1.markdown
+	@pandoc -s -o man1/pg_migrate.1 -t man -V title=pg_migrate -V section=1 man1/pg_migrate.1.markdown
+
+man5/pg_migrate.5: man5/pg_migrate.5.markdown
+	@pandoc -s -o man5/pg_migrate.5 -t man -V title=pg_migrate -V section=5 man5/pg_migrate.5.markdown
+
+clean:
+	rm -Rf man*/*.[0-9]

man/man1/pg_migrate.1

@@ -0,0 +1,90 @@
+.TH pg_migrate 1 "" 
+.SH NAME
+.PP
+pg_migrate \- PostgreSQL ORM migrations runner
+.SH SYNOPSIS
+.IP
+.nf
+\f[C]
+pg_migrate\ COMMAND\ [directory]
+\f[]
+.fi
+.SH DESCRIPTION
+.PP
+pg_migrate is a utility for managing migrations on a PostgreSQL
+database.
+It allows you to run migrations from a directory, only running those not
+yet applied and rollback to previous versions.
+For example, in development, use pg_migrate to iterate on your database
+schema, and in production, use it to retain a rollback path when pushing
+code that requires a new schema.
+.PP
+Migrations are executable Haskell source code files that run a single
+migration and corresponding rollback.
+All migrations for a project should be stored in the same directory.
+See pg_migrate(5) for details on how migrations are run.
+.SS Migration File Names
+.PP
+Migrations files are underscore delimited and contain the version
+followed by a descriptive name:
+.IP
+.nf
+\f[C]
+\ \ 201304021245_create_users_table.hs
+\f[]
+.fi
+.PP
+Versions are ordered lexically and can be any string not containing the
+characters \[aq].\[aq] or \[aq]_\[aq].
+However, a common choice is the GMT time of creation formatted in
+decreasing order of significance: %Y%m%d%H%M.
+.SS Database format
+.PP
+The only requirement on the database is that it contain a table
+schema_migrations with a VARCHAR column version.
+running "\f[I]pg_migrate init\f[]" will create such a table, by running
+the following SQL:
+.IP
+.nf
+\f[C]
+\ \ CREATE\ TABLE\ schema_migrations\ (
+\ \ \ \ version\ VARCHAR(28)
+\ \ );
+\f[]
+.fi
+.PP
+When a migration is run, it\[aq]s version is inserted into this table.
+When it is rolled back, the version is removed.
+Maintaining all migration versions in the database allows us to easily
+run only new migrations.
+.SH COMMANDS
+.SS migrate [directory]
+.PP
+Run all migrations found in \f[I]directory\f[], starting with the oldest
+migrations not yet commited to the database.
+If not specified, \f[I]directory\f[] is "db/migrations".
+.SS rollback [directory]
+.PP
+Rollback the newest migration in \f[I]directory\f[] committed to the
+database.
+If not specified, \f[I]directory\f[] is "db/migrations".
+.SS init
+.PP
+Prepare the database for using migrations by creating the
+"schema_migrations" table.
+This command will fail if such a table already exists without destroying
+the existing table.
+.SS dump [file]
+.PP
+Dump the current database schema to the \f[I]file\f[], or
+"db/schema.sql" if not \f[I]file\f[] is specified.
+The current implementation simply runs pg_dump(1):
+.IP
+.nf
+\f[C]
+pg_dump\ \-\-schema\-only\ \-O\ \-x
+\f[]
+.fi
+.SH SEE ALSO
+.PP
+pg_migrate(5), pg_dump(1)

man/man1/pg_migrate.1.markdown

@@ -0,0 +1,69 @@
+#NAME
+
+pg\_migrate - PostgreSQL ORM migrations runner
+
+#SYNOPSIS
+
+    pg_migrate COMMAND [directory]
+
+#DESCRIPTION
+
+pg\_migrate is a utility for managing migrations on a PostgreSQL database. It
+allows you to run migrations from a directory, only running those
+not yet applied and rollback to previous versions. For example, in development,
+use pg\_migrate to iterate on your database schema, and in production, use it
+to retain a rollback path when pushing code that requires a new schema.
+
+Migrations are executable Haskell source code files that run a single migration
+and corresponding rollback. All migrations for a project should be stored in
+the same directory. See pg\_migrate(5) for details on how
+migrations are run.
+
+##Migration File Names
+
+Migrations files are underscore delimited and contain the version followed by a descriptive name:
+
+      201304021245_create_users_table.hs
+
+Versions are ordered lexically and can be any string not containing the characters '.' or '\_'. However, a common choice is the GMT time of creation formatted in decreasing order of significance: %Y%m%d%H%M.
+
+##Database format
+
+The only requirement on the database is that it contain a table schema\_migrations with a VARCHAR column version. running "_pg\_migrate init_" will create such a table, by running the following SQL:
+
+      CREATE TABLE schema_migrations (
+        version VARCHAR(28)
+      );
+
+When a migration is run, it's version is inserted into this table. When it is rolled back, the version is removed. Maintaining all migration versions in the database allows us to easily run only new migrations. 
+
+#COMMANDS
+
+##migrate [directory]
+
+Run all migrations found in _directory_, starting with the oldest
+migrations not yet commited to the database. If not specified,
+_directory_ is "db/migrations".
+
+##rollback [directory]
+
+Rollback the newest migration in _directory_ committed to the database.
+If not specified, _directory_ is "db/migrations".
+
+##init
+
+Prepare the database for using migrations by creating the "schema\_migrations"
+table. This command will fail if such a table already exists without destroying
+the existing table.
+
+##dump [file]
+
+Dump the current database schema to the _file_, or "db/schema.sql" if not
+_file_ is specified. The current implementation simply runs pg\_dump(1):
+
+    pg_dump --schema-only -O -x
+
+#SEE ALSO
+
+pg\_migrate(5), pg\_dump(1)
+

man/man5/pg_migrate.5

@@ -0,0 +1,44 @@
+.TH pg_migrate 5 "" 
+.SH NAME
+.PP
+PostgreSQL ORM migration
+.SH SYNOPSIS
+.IP
+.nf
+\f[C]
+201305041232_migration_file.hs\ COMMAND\ [\-\-with\-db\-commit]
+\f[]
+.fi
+.SH DESCRIPTION
+.PP
+A Migrations is an executable Haskell source file (e.g.
+a Haskell source file with a "\f[C]main\ ::\ IO\ ()\f[]" function,
+runnable by \f[C]runghc\f[]).
+It must respond to the commands "up" and "down" by running a migration
+and rollback, respectively.
+Unless the "\-\-with\-db\-commit" flag is set, the result of the
+migration or rollback should not be committed to the database.
+.PP
+While you can implement a migration however you like, the module
+\f[C]Database.PostgreSQL.Migrations\f[] in the \f[C]postgresql\-orm\f[]
+package defines a function called \f[C]defaultMain\f[] that implements
+most of the boiler plate functionality of a migration.
+You need only implement the actual migration and rollback code.
+.SH COMMANDS
+.SS up
+.PP
+Upgrade the database by running the migration
+.SS down
+.PP
+Downgrade the database by rolling back the migration
+.SH FLAGS
+.SS \-\-with\-db\-commit
+.PP
+MUST be included in order to actually commit the migration or rollback
+to the database.
+If this argument is not included, a test run is implied, and the
+migration should affect the database, probably by rolling back the
+transaction before exiting.
+.SH SEE ALSO
+.PP
+pg_migrate(1), runghc(1)

man/man5/pg_migrate.5.markdown

@@ -0,0 +1,45 @@
+#NAME
+
+PostgreSQL ORM migration
+
+#SYNOPSIS
+
+    201305041232_migration_file.hs COMMAND [--with-db-commit]
+
+#DESCRIPTION
+
+A Migrations is an executable Haskell source file (e.g. a Haskell source file
+with a "`main :: IO ()`" function, runnable by `runghc`). It must respond to the
+commands "up" and "down" by running a migration and rollback, respectively.
+Unless the "--with-db-commit" flag is set, the result of the migration or
+rollback should not be committed to the database.
+
+While you can implement a migration however you like, the module
+`Database.PostgreSQL.Migrations` in the `postgresql-orm` package defines a
+function called `defaultMain` that implements most of the boiler plate
+functionality of a migration. You need only implement the actual migration and
+rollback code.
+
+#COMMANDS
+
+##up
+
+Upgrade the database by running the migration
+
+##down
+
+Downgrade the database by rolling back the migration
+
+#FLAGS
+
+##--with-db-commit
+
+MUST be included in order to actually commit the migration or rollback to the
+database. If this argument is not included, a test run is implied, and the
+migration should affect the database, probably by rolling back the transaction
+before exiting.
+
+#SEE ALSO
+
+pg\_migrate(1), runghc(1)
+