bound migration version allocation

Author: oswalpalash

README.md

@@ -697,6 +697,8 @@ and `gen structs` atomically replace their destination; `migrate new` remains
 exclusive and never overwrites an existing migration. If concurrent creators
 select the same next version, the loser rescans and retries up to a fixed bound
 instead of leaving a partial file or immediately surfacing the filename race.
+The four-digit version field is minimum padding, not a ceiling; exhaustion at
+`u64` maximum returns `MigrationVersionConflict` instead of wrapping to zero.
 
 Generated struct files import `zsql` themselves, map supported SQL domain types
 to `zsql.types.*`, and preserve database nullability with optional Zig fields.

cli/main.zig

@@ -656,6 +656,44 @@ test "migration creation bounds repeated version collisions" {
     try std.testing.expectEqual(max_migration_create_attempts, collisions.attempts);
 }
 
+test "migration creation preserves versions wider than the minimum padding" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    try tmp.dir.createDirPath(std.testing.io, "migrations");
+    try tmp.dir.writeFile(std.testing.io, .{
+        .sub_path = "migrations/V9999__previous.sql",
+        .data = migration_template,
+    });
+
+    const path = try createNextMigrationFile(
+        std.testing.allocator,
+        tmp.dir,
+        std.testing.io,
+        "migrations",
+        "wide_version",
+    );
+    defer std.testing.allocator.free(path);
+    try std.testing.expectEqualStrings("migrations/V10000__wide_version.sql", path);
+
+    const id = try zsql.migrate.parseFilename(path);
+    try std.testing.expectEqual(@as(u64, 10_000), id.version);
+}
+
+test "migration version discovery rejects u64 exhaustion" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    try tmp.dir.createDirPath(std.testing.io, "migrations");
+    try tmp.dir.writeFile(std.testing.io, .{
+        .sub_path = "migrations/V18446744073709551615__last.sql",
+        .data = migration_template,
+    });
+
+    try std.testing.expectError(
+        error.MigrationVersionConflict,
+        nextMigrationVersion(tmp.dir, std.testing.io, "migrations"),
+    );
+}
+
 fn nextMigrationVersion(root: std.Io.Dir, io: std.Io, dir_path: []const u8) !u64 {
     var dir = root.openDir(io, dir_path, .{ .iterate = true }) catch return 1;
     defer dir.close(io);

docs/FEATURE_MATRIX.md

@@ -22,7 +22,7 @@ coverage; PostgreSQL rows marked live also run against PostgreSQL 16 in CI.
 | Explicit owned rows | Complete | `OwnedRow`, `Row.getOwned`, `zsql.freeOwnedRows`; documented invalidation boundary for borrowed values | allocator-backed core/driver tests plus external SQLite survival after rows, connection, and database teardown |
 | Connection pooling | Complete | `Pool(D)`, `Lease(D)`, health-aware consuming release, OOM-safe idle return and owned-result unwind, shutdown draining/wakeup, stats and timeouts | SQLite release-OOM/result-unwind/recovery tests; PostgreSQL live release-OOM/result-unwind/shutdown tests |
 | Transactions and savepoints | Complete | explicit nested/idle/aborted states; PostgreSQL `25P02` mapping; prepared-statement transition safety; failed-state savepoint recovery; `Tx(D)`, `Savepoint(D)`, `withTx` | SQLite state tests and PostgreSQL direct/prepared/pool live tests |
-| Migrations | Complete | transactional apply, durable dirty failures, checksum-guarded API/CLI repair; allocator-owned post-connection `MigrationStatus`; exclusive atomic and collision-retrying `migrate new`; `Migrator(D).up`, `.status` | cross-driver status OOM/teardown tests, SQLite repair workflow, PostgreSQL live repair tests, CLI atomic-create/concurrent-collision/parser tests, migration example |
+| Migrations | Complete | transactional apply, durable dirty failures, checksum-guarded API/CLI repair; allocator-owned post-connection `MigrationStatus`; exclusive atomic and collision-retrying `migrate new`; checked `u64` version discovery; `Migrator(D).up`, `.status` | cross-driver status OOM/teardown tests, SQLite repair workflow, PostgreSQL live repair tests, CLI atomic-create/concurrent-collision/version-boundary/parser tests, migration example |
 | Schema inspection | Complete | allocator-owned post-connection schema graph; driver `inspectSchema`; dialect-tagged CLI `inspect`; atomic schema/codegen replacement; structured PostgreSQL schema/table identity; self-contained nullable struct generation with exact fields and schema-aware collision-free table types | SQLite exhaustive graph OOM tests; PostgreSQL post-connection live test; inspector/codegen syntax and CLI atomic-replacement tests |
 | Optional offline query checks | Complete within documented bounded scope | `zsql.check`, `zsql.checkedQuery`; dialect-aware unquoted lookup and structured `schema.table` / `schema.table.column` PostgreSQL resolution; exact escaped quoted identifiers; SQL-correct alias visibility; exact bind contracts; outer-CTE anchoring with opaque-relation rejection; projection/alias-bound row shapes; portable COUNT/MIN/MAX inference; WHERE/HAVING/JOIN ON/USING/GROUP/ORDER refs; explicit capacity failures; typed domain wrappers; numeric width checks | parser/dialect/schema-qualified/CTE/quoted-identifier/projection/aggregate/clause/join/scope/shape/type/nullability/narrowing tests; `zig build check-sql` |
 | Query builder | Complete | `QueryBuilder`, `ident`, `identPath`, `bind`, `rawUnsafe` | core unit tests |