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.mdindex 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 deThese commands are for operators: they need the shared token. A per-agent tokencan 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 authoritative1. Run every node in shadow mode and import every repository@@ -594,14 +628,8 @@ or re-import the repository from scratch (seeA kept copy whose history files cannot be read cannot be imported: repairthem, or extract what is readable by hand. Removing a kept copy loses onlyits 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 dirtyrepository durable and removes its marker, so a clean reboot hydratesnothing.diff --git a/internal/graft/corestore/sqlstore/migrations_unknown_test.go b/internal/graft/corestore/sqlstore/migrations_unknown_test.gonew file mode 100644index 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.goindex 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 intset := migrate.MigrationSet{TableName: migrationTable}source := &migrate.MemoryMigrationSource{Migrations: migrations}+ if err := refuseUnknownMigrations(set, db, name, dialect); err != nil {+ return err+ }+var err errorfor 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 intreturn 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 }