Initial version (#1)

.circleci/config.yml

@@ -0,0 +1,42 @@
+version: 2
+
+jobs:
+  build:
+    docker:
+      - image: circleci/node:lts
+
+    steps:
+      - checkout
+
+      - run:
+          name: Install dependencies
+          command: npm ci
+
+      - run:
+          name: Run tests
+          command: npm test
+
+      - run:
+          name: Check types
+          command: npm run check-types
+          when: always
+
+      - run:
+          name: Check lint
+          command: npm run lint
+          when: always
+
+      - run:
+          name: Check that schema are up to date
+          command: ./node_modules/.bin/1schema check
+          when: always
+
+      - run:
+          name: Check prettier
+          command: npm run prettier:check
+          when: always
+
+      - run:
+          name: Run the build
+          command: npm run build
+          when: always

.eslintignore

@@ -0,0 +1 @@
+dist/

.eslintrc.yml

@@ -0,0 +1,28 @@
+env:
+  mocha: true
+
+extends:
+  - standard
+  - 'plugin:@typescript-eslint/recommended'
+  - prettier
+
+plugins:
+  - simple-import-sort
+
+parser: '@typescript-eslint/parser'
+
+rules:
+  # We keep whitespace cleaned up.
+  no-trailing-spaces: 'error'
+  eol-last: 'error'
+
+  '@typescript-eslint/explicit-function-return-type':
+    ['error', { 'allowExpressions': true }]
+
+  # Our additions.
+  no-var: 'error'
+  prefer-const: 'error'
+  no-console: 'error'
+
+  'simple-import-sort/imports': 'error'
+  'simple-import-sort/exports': 'error'

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: '/'
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 10

.prettierignore

@@ -0,0 +1,3 @@
+package.json
+package-lock.json
+dist/

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Initial public release.

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2023 Metabolize LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,91 @@
+# 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!
+
+[graphile migrate]: https://github.com/graphile/migrate
+
+## Installation
+
+```sh
+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][].
+
+[graphile starter]: https://github.com/graphile/starter
+[docker example]: https://github.com/graphile/migrate/blob/main/docs/docker/README.md
+
+## 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….
+
+![](https://fh-sites.imgix.net/sites/4390/2020/08/31200405/U.S.-Mailboat-Tour-image-1.jpg?auto=compress%2Cformat&w=700&h=700&fit=max)
+
+[mail jumping]: https://www.atlasobscura.com/articles/mail-jumping-lake-geneva
+[benjie]: https://github.com/benjie
+[jem]: https://github.com/jemgillam
+[jacob beard]: https://github.com/jbeard4