Skip to content

Git designed for AI agents.

Review M1: refuse a database of a newer version; upgrades and downgrades

Federico Eliadf9d673a6b6e
diff --git a/doc/graft/STORAGE.md b/doc/graft/STORAGE.md
index 6ff3194..346caf6 100644
--- a/doc/graft/STORAGE.md
+++ b/doc/graft/STORAGE.md
@@ -400,6 +400,40 @@ graft storage gc --removed -address unix:/var/opt/graft/gitaly.sock [-storage de
These commands are for operators: they need the shared token. A per-agent token
can never call the storage core service, whatever `agent_rpcs` says.
+### Upgrades
+
+Upgrading from v0.2.x to this release changes the storage core's database
+(migration `20261018000000_graft_storage_gc`) and the keys of the packs in the
+bucket (owned keys, see Packs). A node of the old version cannot work next to
+a node of the new one:
+- **It cannot start.** A v0.2.x node that restarts after the migration
+ refuses the database, with an error about an unknown migration
+ (`20261018000000_graft_storage_gc`).
+- **It cannot read.** A v0.2.x node still running reads only the old 64-hex
+ pack keys, so its reads of a repository that a new node wrote fail with
+ "invalid pack key".
+- **It cannot write.** Its writes carry old keys, and the database refuses
+ them ("the pack key is not an owned key; every node must run the same
+ version").
+
+So upgrade the whole deployment at once:
+1. Stop `gitaly serve` on every node.
+2. Install the new binaries on every node.
+3. Start the nodes. The first one migrates the database; the others find it
+ migrated.
+
+**Downgrade is not supported past this migration.** The database keeps the
+data of the new version (checkpoints, tombstones, owned keys) that a v0.2.x
+binary cannot read, and there is no down migration that would make the
+bucket's owned keys readable to it. Going back means restoring the database and
+the bucket from a backup taken before the upgrade.
+
+A binary that finds a database migrated by a newer version refuses to start:
+"the database was migrated by a newer version of the storage core (unknown
+migrations ...): this binary cannot run on it; every node must run the same
+version, so upgrade this node". This is how a node left on the older release
+shows up after the next upgrade, too.
+
### Switching from shadow to authoritative
1. Run every node in shadow mode and import every repository
@@ -594,14 +628,8 @@ or re-import the repository from scratch (see
A kept copy whose history files cannot be read cannot be imported: repair
them, or extract what is readable by hand. Removing a kept copy loses only
its history that was not imported.
- - *Downgrade*: a release without this rule (v0.2.x) ignores the markers. It
- would serve a repository that is untrusted, or dirty from an unclean
- shutdown. Before a downgrade, stop `gitaly serve` cleanly: the final step
- makes every repository durable. Then check that
- `<storage>/+gitaly/graft-ref-durability/` holds no `*.json` marker. A
- marker left there names a repository that is untrusted or that a live
- process kept. Move that repository out of the storage first; its next
- request after the downgrade hydrates it.
+ - *Downgrade*: not supported past this release's storage migration (see
+ [Upgrades](#upgrades)). A v0.2.x binary would also ignore the markers.
- *Clean stop*: after the servers stopped, `gitaly serve` makes every dirty
repository durable and removes its marker, so a clean reboot hydrates
nothing.
diff --git a/internal/graft/corestore/sqlstore/migrations_unknown_test.go b/internal/graft/corestore/sqlstore/migrations_unknown_test.go
new file mode 100644
index 0000000..24412d4
--- /dev/null
+++ b/internal/graft/corestore/sqlstore/migrations_unknown_test.go
@@ -0,0 +1,31 @@
+package sqlstore_test
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/feder-cr/git-ai/internal/graft/corestore/sqlstore"
+)
+
+// TestOpenRefusesADatabaseOfANewerVersion verifies the startup refusal of a
+// database that a newer version migrated (integrated review M1): Open fails
+// with ErrUnknownMigrations, naming the migration and pointing at the upgrade,
+// instead of the error of the migration library or a schema it cannot read.
+func TestOpenRefusesADatabaseOfANewerVersion(t *testing.T) {
+ forEachDialect(t, func(t *testing.T, ctx context.Context, s *sqlstore.Store) {
+ const future = "29990101000000_from_a_newer_version"
+ var appliedAt any = time.Now().UTC()
+ if s.Dialect() == sqlstore.SQLite {
+ appliedAt = time.Now().UTC().Format("2006-01-02 15:04:05")
+ }
+ execSQL(t, ctx, s, "INSERT INTO graft_storage_migrations (id, applied_at) VALUES (?, ?)", future, appliedAt)
+
+ _, err := sqlstore.Open(ctx, coreDSN(t, s))
+ require.ErrorIs(t, err, sqlstore.ErrUnknownMigrations)
+ require.ErrorContains(t, err, future)
+ require.ErrorContains(t, err, "upgrade this node")
+ })
+}
diff --git a/internal/graft/corestore/sqlstore/store.go b/internal/graft/corestore/sqlstore/store.go
index aee6be1..c7231f3 100644
--- a/internal/graft/corestore/sqlstore/store.go
+++ b/internal/graft/corestore/sqlstore/store.go
@@ -235,6 +235,10 @@ func applyMigrations(ctx context.Context, db *sql.DB, dialect Dialect, limit int
set := migrate.MigrationSet{TableName: migrationTable}
source := &migrate.MemoryMigrationSource{Migrations: migrations}
+ if err := refuseUnknownMigrations(set, db, name, dialect); err != nil {
+ return err
+ }
+
var err error
for attempt := 0; attempt < attempts; attempt++ {
if _, err = set.Exec(db, name, source, migrate.Up); err == nil {
@@ -250,6 +254,41 @@ func applyMigrations(ctx context.Context, db *sql.DB, dialect Dialect, limit int
return err
}
+// ErrUnknownMigrations is returned by Open when the database holds migrations
+// that this binary does not know: a newer version migrated it. This version
+// cannot run on it: its writes and its reads of the newer data are not
+// compatible (doc/graft/STORAGE.md, Upgrades).
+var ErrUnknownMigrations = errors.New("storage core: the database was migrated by a newer version of the storage core")
+
+// refuseUnknownMigrations returns ErrUnknownMigrations, naming the migrations,
+// when the database records a migration that is not among the migrations of
+// this binary for the dialect (all of them, whatever limit applies).
+func refuseUnknownMigrations(set migrate.MigrationSet, db *sql.DB, name string, dialect Dialect) error {
+ records, err := set.GetMigrationRecords(db, name)
+ if err != nil {
+ return fmt.Errorf("read the applied migrations: %w", err)
+ }
+ all := sqliteMigrations
+ if dialect == Postgres {
+ all = postgresMigrations
+ }
+ known := make(map[string]struct{}, len(all))
+ for _, m := range all {
+ known[m.Id] = struct{}{}
+ }
+ var unknown []string
+ for _, r := range records {
+ if _, ok := known[r.Id]; !ok {
+ unknown = append(unknown, r.Id)
+ }
+ }
+ if len(unknown) > 0 {
+ return fmt.Errorf("%w (unknown migrations %s): this binary cannot run on it; every node must run the same version, so upgrade this node (doc/graft/STORAGE.md, Upgrades)",
+ ErrUnknownMigrations, strings.Join(unknown, ", "))
+ }
+ return nil
+}
+
// Dialect returns the dialect of the store.
func (s *Store) Dialect() Dialect { return s.dialect }