Changelog: Breaking changes scheduled for v1!

[JAForbes]

pgmg@v1 will be released soon. We've both added and removed features based on a lot of dogfooding. We think we have a pretty clear idea of what the API surface and responsibilities of pgmg should be.

If you are coming from 0.x you will find a lot of breaking changes, and the biggest change will be pgmg's very opinionated automatic teardown --dev workflow. We were hesitant to build something so "magic" into the library, but it really does make writing migrations so much more enjoyable so this feature has become a core part of what pgmg is now.

If you are coming from a prior gitref on the next branch, not much will have changed, you will have to rename a few exports but conceptually not much has changed.

Overall we've removed a lot of special features that we never really used in a production context, if there was a simple way to achieve the same thing with little effort in userland, we defaulted to removing the feature.

We're taking the next few weeks as a chance to do a few more in production tests and then we'll merge next into main and release as v1.0.

New features

• --dry skips migration hooks but not pgmg table set up
• Defaults to explicit search path, opt out via set search_path='...' in your migration
• Can opt out of dev loop for a migration via export dev = false
• Debug logging via --debug
• We now export createRole, createRoleFromUrl and dropRole as simple helpers that only perform actions if the role does/doesn't exist
• You can now configure postgres.js connection options via export const connection = { ... }

Breaking changes from 0.x

• sql.raw is gone, need to use sql.unsafe (part of postgres.js)
• no more transaction hook, use sql.begin instead (part of postgres.js)
• Removed special connection options, instead should be specified in the connection url
• Can optionally enable more connections by export connection = { ... }
• Need to explicitly opt in to --dev or --prod
• $HOSTNAME is no longer used as a precondition for production migrations or cluster hooks to run. We no longer have cluster hooks and we instead recommend users use pg_dumpall to capture / replay global objects when restoring dumps locally.
• The internal slugify function now handles any and all punctuation, but as a result its possible pgmg may think a migration hasn't run because the slugify function returns a different value to the old one. This is another good reason to archive old 0.x migrations.

Breaking changes from next

You may have been on the bleeding edge using next before it was released. Heads up there are some recent changes that you should be aware of

• --restore is gone, we think it is better people become familiar with pg_dump, pg_dumpall and pg_restore. "owning" that part of the process doesn't have a lot of long term payoff and hiding the details of these tools carries risks. We'd rather just focus on the migrations.
• --dry-complete is gone, this was there to ease migration, but instead we're making a clean break
• cluster hooks are gone, we now have pre hooks that always run and we auto detect and replay create role and grant global statements in --dev that were run in --prod mode
• always is now called post
• --teardown is gone, the use case for this is easily replaced by just commenting out your WIP action hook and let teardown run
• --env-file is gone, this is not pgmg's job, you can use node.js / docker's built in support for configuring the env
• --search_path and --keep-default-search-path are gone, we always set it to '' because its more secure and if you want to opt out just run set search_path='public,etc' in your migration
• $HOSTNAME is no longer used as a precondition for production migrations or cluster hooks to run. We no longer have cluster hooks and we instead recommend users use pg_dumpall to capture / replay global objects when restoring dumps locally.
• We no longer detect or patch old migration file formats, when switching to v1 you'll need to ensure your files match the documented format in the readme, passing old migration files to v1.x will have undefined behaviour.
• The internal slugify function now handles any and all punctuation, but as a result its possible pgmg may think a migration hasn't run because the slugify function returns a different value to the old one. This is another good reason to archive old 0.x migrations.