Library usage documentation

[FelixZY]

Feature description

I need to use graphile-migrate as a library rather than via the CLI. However, here does not appear to be any documentation on how to use graphile-migrate as a library. I therefore would humbly like to request it be added.

Motivating example

I would like to run some database tests using @testcontainers/postgresql. Actually, I think it would be really cool if there was an example implementation for this in the README!

Supporting development

I [tick all that apply]:

• [x] am interested in building this feature myself
• [x] am interested in collaborating on building this feature
• [x] am willing to help testing this feature before it's released
• [ ] am willing to write a test-driven test suite for this feature (before it exists)
• [ ] am a Graphile sponsor ❤️
• [ ] have an active support or consultancy contract with Graphile

[FelixZY]

Here's some code I wrote to scaffold testcontainers with prisma for tests a while back. I'm planning a rewrite though.

https://github.com/dansdata-se/api/blob/develop/src/__test__/db/index.ts

[benjie]

Graphile Migrate isn't designed to be used as a library; library usage is not a supported interface and I don't intend it to become one at this time. (Maybe some day, but not currently a priority.)

That said, usage mirrors the CLI usage - each command is exported (e.g. import { commit } from 'graphile-migrate' for the graphile-migrate commit command) and you should be able to use the TypeScript types to figure out which options each command takes - or browse the relevant handler in the source:

https://github.com/graphile/migrate/blob/06c81b3140b86696d5b58fe2dda4f906d3cee1cf/src/commands/commit.ts#L149-L154

I think you can import the settings (the first argument to each command) directly from your .gmrc.js file assuming it's a CommonJS file. Don't use the methods that are prefixed with an _ - they're internal. Unless you want to, technically it's all internal :man_shrugging:

[benjie]

(I appreciate the offer to do the work; but I'm not keen to support long-term library usage at this time as it would require the APIs to be stable and I'm not sure they are yet.)