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 or graphile-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….