So I Wrote a Database Migrations NPM

December 30, 2019 by Steven Ng

I've been working on making Docker containers of my personal Nodejs projects lately, and for those that rely on a relational database (namely Postgresql), I wanted to be able to run database migrations on them locally to make updates easier. To be clear, I'm not talking about data migrations, which are a completely different thing.

For database migrations outside of Ruby on Rails, I've been using Liquibase, and more recently, Flyway. They're both perfectly fine tools, but they also require Java, which means one may need to consider the implications of how Java licenses work.

As it relates to migrations, I subscribe to the forward migrations only philosophy, which means my requirements are relatively simple. All I need to do is scan a pre-specified directory of SQL files and run only the new SQL files. The onus is on me for providing clean, error-free SQL files, so I don't need to make a migration tool very smart.

I did look at existing libraries on NPMJS, but I didn't see any having a workflow similar to Flyway, which has been my tool of choice.

You might be getting the impression that I suffer from NIH (Not Invented Here) syndrome, and you could be right. But my experience with some software is that there are always some elements that I find incredibly frustrating or incompatible with the way I work, and I end up spending significantly more time working around those issues than I would have if I had just written something from scratch.

My NPM, named pg-forward-migrations is designed to do one very specific task well, and took a few hours to write. I spent more time figuring out how to use Liquibase the first time I used it, so in this particular case, the NIH concern is a wash.

All this NPM does is run sequence of SQL statements against a Postgresql database. The workflow is inspired by Flyway in that it uses an easy-to-remember naming convention, and it tracks completed migrations by writing to a migration table in the target database. That's it. It's not rocket science, nor is it attempting to be a replacement for a multi-platform, enterprise-class database migration tool.

At some point, I will probably use this NPM to create command line executable, but at the moment, it's not a priority.

In any case, if you've got a need for a forward migration tool for Postgresql/Node, give the NPM a whirl.