Building dbshift: a boring tool people actually use

The itch

"In early 2023 I was working on Caspian and needed to add a column to a table. I reached for the migration tool we were using and spent twenty minutes reading documentation before I'd written a single line of SQL. The tool had opinions about folder structure, a config file I didn't have, and a migration DSL I didn't know. I wrote the SQL migration by hand and ran it manually. Then again for staging. Then forgot to run it in one environment and spent an afternoon debugging something that wasn't an issue. There had to be a better way. The better way was, apparently, something I had to build myself."

The weekend build

"The constraints I set were: one command to create a migration file, one to apply pending migrations, one to check status. Plain SQL files, no DSL. State tracked in the database itself, not a separate lockfile. Zero config. I built the first version on a Saturday. It did those five things and nothing else. I used it on Caspian the following Monday."

$ npx dbshift create add-user-roles
✓ Created: migrations/20250112_add-user-roles.sql

$ npx dbshift up
✓ Applied: 20250112_add-user-roles.sql

$ npx dbshift status
✓ 3 applied · 0

$ npx dbshift create add-user-roles
✓ Created: migrations/20250112_add-user-roles.sql

$ npx dbshift up
✓ Applied: 20250112_add-user-roles.sql

$ npx dbshift status
✓ 3 applied · 0

$ npx dbshift create add-user-roles
✓ Created: migrations/20250112_add-user-roles.sql

$ npx dbshift up
✓ Applied: 20250112_add-user-roles.sql

$ npx dbshift status
✓ 3 applied · 0

Posting it

"I put the code on GitHub, wrote a README, and posted it in a few places — r/node, a couple of Discord servers I was in. I expected maybe 50 stars if I was lucky. I got 200 in the first week. The comments were mostly 'I've been looking for exactly this.' I found that more validating than the number. It meant the problem was real and I wasn't the only one who'd found the existing tools frustrating."

The use case I hadn't anticipated

"Two months after launch I started getting issues from people running dbshift in CI pipelines — teams spinning up ephemeral Postgres databases for integration tests and applying the schema before the tests ran. I hadn't designed for this. The original version had a small connection handling problem that didn't matter in normal use but caused flaky behaviour in fast-spinning CI environments. Three contributors I'd never spoken to diagnosed the issue, submitted PRs, and reviewed each other's solutions before I'd looked at the thread. That experience reshaped how I thought about the project."

What 1.4k stars means

"Not much on its own. Stars are cheap — people star things they find interesting and never use. What matters more: the npm download numbers are consistent. The issues filed are specific and reproducible, which means people are using it in production and hitting real edge cases. A team at a company I'd never heard of filed an issue referencing dbshift in their production deployment. That's the number I actually care about."

What I'd build differently

"The configuration API is slightly inconsistent between CLI flags and config file options. I shipped v1 without a config file at all — pure CLI — and added config file support in v1.2 in a way that doesn't quite mirror the CLI surface. It's a small thing that becomes load-bearing when someone has 200 migration files and needs to change their database URL. I'd design the config surface first next time."