About

Bootstrapping keeps the reference data an application ships with in step with its database. Roles, permissions, plan tiers, workflow states, country lists: the rows a fresh install needs before anyone can use it. Bootstrapping loads them the first time, and on every release after that it brings them up to date without undoing what each customer’s admins changed.

Why the Project Exists

Every application with users has this data, and almost every team handles upgrades the same way: a migration script per release, written by hand, that either overwrites what customers edited or leaves out what the release meant to change. Upserting from a seed file looks like a fix, but it can’t tell an admin’s edit from a stale value. It overwrites both.

The missing piece is memory. If the database remembers what was applied last time, every value can be compared three ways: the new seed, the live row and the last-applied seed. Then the rules are simple. A value only the seed changed gets updated. A value only the admin changed stays. A value both changed, differently, waits for a person to decide. The explainer goes through it with an example.

What Is Built

Version 0.2 has:

  • Seed files. One TOML file per table, readable in code review, with per-column ownership (merge, seed or local), rules for rows dropped from the seed (keep, delete or retire), renames that keep a row’s id, and links between tables written by name. Long lists can keep their rows in a CSV file.
  • SQLite and PostgreSQL. The same seeds, the same merge and the same ledger on both. On PostgreSQL, values are compared the way the server stores them, so 7 in a numeric(10,2) column is 7.00 and a jsonb document matches however its keys were ordered.
  • A Go library. It works with any database/sql driver for SQLite or PostgreSQL, and seeds can be embedded in the application binary and applied at startup.
  • A command. bootstrapping, or bst for short, plans, applies, explains one row value by value and lists the history, with JSON output, exit codes a deploy script can use, and a Markdown plan a CI step can post on a pull request.
  • A ledger in your database. Four small tables written in the same transaction as the data, so they never disagree with it.
  • A demo. An application’s roles and permissions through three seed versions, with an admin’s edits, a conflict, and an apply killed halfway through, every result checked.
  • Case studies. Four more example programs in the repository, each written up on this site: plan tiers, countries and currencies in CSV, helpdesk ticket states and email templates.
  • Tests aimed at the promise. Random histories checked against the merge rules, applies killed with SIGKILL, eight processes on one file, and value types checked against SQLite and PostgreSQL themselves. How it was tested has the figures.

What It Leaves Out

Bootstrapping fills tables; it doesn’t create them. Schema migrations stay with whatever tool you use for them, and Bootstrapping runs after. It supports SQLite and PostgreSQL, not other databases. And it’s built for reference data, thousands of rows rather than millions, since every managed table is read in full on each plan.

How the Project Works

Bootstrapping is open source under the Apache License 2.0. The code, the tests, the recorded test results and the documentation are on GitHub. Releases are built and checked by the project’s release workflow, and ready-built binaries for Linux, macOS and Windows are on the download page.