Database migrations are important. They’re what allow you to minimize risk and get rid of human error when handling your precious data. Working with database migrations can sometimes be a complex and vague thing to do. Which is exactly why you deserve to know how Wetland deals with this.

In this article, we’ll take a look at a usual migrations flow and go through the steps you’d take to have a smooth development flow, and creating reliable database migration files.

For the sake of this article I’ll assume you’re using wetland with SailsJS with the sails-hook-wetland plugin. You can still follow along if you have devMigrations set up in your project. I’ll also assume you have the wetland-cli installed. Finally, I’ll assume you know what database migrations are, and why it’s one of the many reasons to use Wetland.

Time to be awesome

It’s a Thursday. 11:26AM. You just got your second cup of coffee kicking in ready to start working on the next epic feature for your killer Node.JS app. You put on your headphones. Time to get cracking…

So, you’re on the master branch. You start work on a new feature/bugfix/whatever. What do we do? Create a new branch. Of course.

… So you create a new branch. gco -b feat/article .

Note: I can hear you thinking: “Whaaat? gco? What’s that?”. Well, my dear student, it’s an alias provided by the git plugin for oh-my-zsh. Get it. Use it. Love it, tenderly. Anyway, it’s short for git checkout .

Then you create a new wetland snapshot: wetland snapshot create (this command uses the git branch-name if you don’t provide a name yourself. It’s a convention, which is why you’ll leave out the name for now).

You start developing, do your thing. Every time you start your server, wetland’s dev-migrations kick in, which will update your database automatically. Epic. You don’t have to worry about the database schema. For now.

Side-step: dev-migrations and snapshots

Understanding how these dev-migrations work, will help you understand what snapshots are, and how migrations work.

What is a snapshot? Well, snapshots capture the state of your mappings into a compressed file, which can then later be used for diffing with other snapshots, and restoring state. In other words, it’s what your schema definition looks like, at that moment in time, which can then be used to diff against your schema at another.

What dev-migrations do, is actually create a snapshot with every successful dev migration. Look in the .data/ directory. There’s a snapshots/ directory and a dev_snapshots/ directory.

Dev snapshots get created automatically. You don’t have to do anything for this feature (that is, when using sails-hook-wetland. When setting it up yourself, make sure to call devMigrations upon starting your server).

The next time the server starts, it will diff the previous (dev) snapshot with the new one, calculate which changes to make, update the database, create a new dev-snapshot, and start the server.

Rinse and repeat. This will happen every time you start your server.

Back to kicking ass

So, you develop your feature, make some entities, change some properties, set up some relations… Whatever floats your boat.

Then once it’s time to start committing, you’ll want your migration file to be generated. You’ll need this file when you want to deploy your awesomeness to production.

I know the time doesn’t match the time used in the article. I’m sorry I ruined your story. :(

This is where your snapshot comes in handy. So, to clarify, this is your snapshot, the one you created after creating the branch, and not the dev snapshot.

So now you run wetland migrator create (again, if you don’t provide a name, it will use the branch name and find your snapshot).

This will do the exact same thing dev migrations do. It’ll diff the current (latest) snapshot to the one you created, calculate changes, generate code, and write the file. Then you will want to check your migration file and check if everything it generated is correct.

Verifying the awesome

Besides simply checking the code, you’ll want to run the migration to verify it works as expected.

To kick this off, you can use the revert command provided by wetland-cli. Which is really handy! It will undo all dev_migrations it did while you were coding. Run it: wetland migrator revert (again, if you don’t provide a name, it will use the name of your branch). After running that, your database has the state it had when you started developing on this branch. When you created the snapshot.

Now you can run the migration up using wetland migrator up -r (Check the status first using wetland migrator status and check the queries using wetland migrator up -d ), test it, and if it works, run down using wetland migrator down -r . If that’s all successful, you’re good to go. You should be able to run up once again to keep your schema up to date, or just run your server again to let wetland figure it out.

Oh crap.. I messed up

If you at any point mess up, and your database is updated but your dev_snapshot is still stuck in its old state, you’ll get a weird situation:

Wetland will try to update your database schema based on the diff between the latest dev_snapshot, and the current snapshot. This will result in errors because your database is already up to date.

To resolve this, simply run wetland migrator forward . This will tell Wetland to update the dev_migration file without changing your database schema, to get it up to date with the actual database state again. All good!

Additional information

When working in a team and updating (pulling in the latest changes from upstream), you might, nay, will, run into a situation where a colleague added a new migration. You do not want to run dev migrations then. If you do, this will cause any migrations that you yourself create to not be testable (because you have an un-run migration, being the one from your colleague).

If you find yourself in this situation, you can resolve it by:

1. Running the migration(s) your colleague added: wetland migrator latest

2. Updating your local dev snapshot: wetland migrator forward

Your database will be up to date, and your dev snapshots won’t cause any harm to your database. You’ll be good to go to add more goodness to the project without any problems.

Conclusion

Like I said before, Wetland kicks ass.

I hope this guide helps you manage your migrations the way they were intended to be managed. I found myself having a lot of fun explaining Wetland migrations so I decided to write about it here. Questions? Feel free to ask them!