Dockjump
Docker-based PostgreSQL developer environment with the extraordinarily thoughtful SQL-powered roll-forward migration tool Graphile Migrate.
While graphile-migrate is opinionated about how to do migrations, it is agnostic about how you run your development databases. Dockjump fills that niche, providing local Docker-based PostgreSQL that just works out of the box. It sets up the necessary root, shadow, and application databases for graphile-migrate to do its thing.
In production, Dockjump is not in the picture: you set DATABASE_URL
and run
graphile-migrate migrate
the usual way.
We've been using similar tooling at Metabolize–Curvewise for a while, with a
Postgraphile/CRA project running on MacOS and Linux hosts. Dockjump would work
equally well on any Postgres project, including with npx
if you're not using
Node.
This tooling is new and considered alpha. Developer feedback and contributions welcome!
Installation
npm install --save pg graphile-migrate
npm install --save-dev dockjump pg
How it works
-
dockjump init
writes out.gmrc.js
. -
dockjump start
starts a Docker container with the necessary databases and initially runs the migrations. -
dockjump run --start cmd args
ensures the Docker container is running and runs the specified process. Without--start
it just sets DATABASE_URL (if it's not already set) and runs the command. - With the container running, you can use
graphile-migrate migrate
orgraphile-migrate watch
and connect to the database from the host machine as usual. - Write your migration in
dockjump/current.sql
. - After committing migrations, hooks configured in gmrc invoke
dockjump export-schema
to export the schema. - In CI, run checks to make sure the exported schema is up to date and
current.sql
is empty-ish.
Features
- Generates
.gmrc.js
- Provisions a local, application-specific docker container
- Within the container, provisions root, application, and shadow databases
- Provides commands convenient for interacting with the container, database, schema, and migrations
- Provides command for running psql
- After running migrations, re-exports the schema
- Verifies the exported schema is up to date (useful for running in CI)
- Checks that
dockjump/current.sql
is empty-ish (also useful in CI) - Runs from the command line with zero boilerplate
- Works with Node-based and non-Node-based projects
Related projects
An alternative to this project is Graphile Starter, a batteries-included boilerplate template by the author of graphile-migrate which runs an entire Postgraphile–Next.js application locally or in Docker.
In dockjump, graphile-migrate runs in the host OS, not docker as in docker example.
Acknowledgements
Serious thanks to Benjie and Jem for maintaining the wonderful Graphile suite. And thanks to Jacob Beard who convinced me it was worthwhile to write SQL again.
A few patterns in this tool were gleaned from Graphile Starter.
The name of this package was inspired by mail jumping, a practice which involves docks and the Post….