## Ask Set `lock_timeout` on the migration **Up** pass, provider-side, with a bounded retry. The decision half of this issue is discharged; the implementation is what remains. The value has to arrive as a **connection startup option** (DSN parameter or `PGOPTIONS`), not as a SQL `SET`. Two migrations carry their own `RESET lock_timeout` in the Down, and `RESET` restores the session-start value, so a SQL-set provider value is wiped for the remainder of that pass. Through `migrations.Down`/`DownTo` the goose provider pins one `*sql.Conn` for the whole pass, so the wipe reaches every migration rolled back after the one that reset it. A startup option survives it. ## What is decided, and what is not - **Decided.** Migrations should set `lock_timeout`, provider-side at 5-10s, with a bounded retry on top of the existing advisory session lock. Recorded in the 2026-08-10 comment on this issue. - **Settled for the Down, landing in !2159.** That MR adds guidance to `docs/dev/database-migrations.md`: a Down taking a wide lock carries the `SET`/`RESET` pair itself, on which rollback entrypoints that works, and where it stops working. `20260829134210_create_npm_virtual_upstream_rules` already bounds its Down that way on `main`, and `20260831055729_create_container_virtual_repositories` does it in !2159. While !2159 is open the doc guidance is not on `main`; once it merges, the Down half of this decision is documented and only the Up half is left. - **Not landed: the Up.** No provider-side bound exists in the tree. While that is true, an Up of this shape waits unbounded on every lock it takes. Once a provider bound exists, no migration file needs an edit for it, because the value arrives as a startup option rather than in the SQL. This issue was closed on 2026-09-01 against its original ask, which was to *decide and record*. It is reopened re-scoped to the Up-side implementation, because 25 migrations point here for that and the pointer would otherwise resolve to a closed issue. Nothing about the closure was wrong for the original ask; the re-scope is what gives the remaining work a home. ## Why Migrations defer to a schema-wide `lock_timeout` decision. At the time this issue was filed, seven did and the decision had no home. Each carries a variant of: > No migration in this repo sets lock_timeout; that is a schema-wide decision this file does not re-open `lock_timeout` appears in no doc, no config, and no Go code. `WithLockTimeout(1, 300)` in `internal/datastore/migrations/migrations.go` is goose's advisory-lock wait, which is a different mechanism. So the sentence reads as a reference to a settled decision and points at nothing, and every reviewer who reaches it rediscovers that. Migrations carrying the deferral, as filed (25 cite this issue's URL as of `d07a7714e`, 8 of them creating a partitioned parent; match `PARTITION BY` on DDL lines only, since the phrase also appears in these files' comments): - `internal/datastore/migrations/sql/20260728120000_create_maven_remote_repositories.sql` - `internal/datastore/migrations/sql/20260730120000_create_maven_remote_packages.sql` - `internal/datastore/migrations/sql/20260731130000_create_maven_remote_versions.sql` - `internal/datastore/migrations/sql/20260804120000_create_container_remote_repositories.sql` - `internal/datastore/migrations/sql/20260805120000_create_maven_remote_files.sql` - `internal/datastore/migrations/sql/20260806120000_create_container_remote_images.sql` - `internal/datastore/migrations/sql/20260807130000_create_container_remote_manifests.sql` ## What the decision is about These migrations create a partitioned parent plus 64 partitions. Each `CREATE` takes `ShareRowExclusiveLock` on every FK target and, where a target is itself hash-partitioned, on all 64 of its partitions. That conflicts with the `RowExclusiveLock` every `INSERT` holds, so a migration is a bounded write stall across the referenced tables. On the container and maven remote tables those targets include `blob_storage_attachments` and `blob_storage_blobs`, which every blob upload writes. Without `lock_timeout`, a `CREATE` that cannot get its lock queues behind a long-running transaction and blocks every writer that arrives after it for as long as that transaction runs. With `lock_timeout`, the statement fails instead, and the migration has to be retried, which is a different operational trade-off rather than a strictly better one. That trade-off is the decision. ## Done when - The migration provider supplies `lock_timeout` on the Up pass as a connection startup option, at the decided 5-10s, with a bounded retry on top of the existing advisory session lock. - `docs/dev/database-migrations.md` states the Up-side behaviour alongside the Down-side guidance !2159 adds, including that a `RESET` in any Down cannot wipe a startup-option value. - The deferrals that still read as pointing at an open *decision* are reworded to state the exposure instead. `20260831055729_create_container_virtual_repositories` is the worked example: it states the decision and what it means for that file, rather than pointing here for an answer. `scripts/ci/check-migration-immutability.sh` freezes a merged migration's text, so rewording a shipped deferral needs an `Allow-Migration-Edit` trailer. That is the reason this issue's own pointer matters: it is cheaper to keep this issue resolvable than to edit 25 frozen files. ## Notes Raised in review on https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1354. That MR points its own deferral at this issue; the other six are left for whoever closes this one. --- ## Triage note This issue has been automatically triaged and labelled as `type::maintenance`. **Reasoning:** This issue is about resolving undocumented tech debt — specifically, making and recording an architectural decision around `lock_timeout` in database migrations, and updating seven migration files and developer documentation accordingly. There is no broken functionality (not a bug) and no new user-facing capability being added (not a feature). It is squarely a maintenance/tech-debt task. The following labels have been applied: - `type::maintenance` - `Category:Artifact Registry` - `devops::package` - `group::package registry` If this classification doesn't look right to you, please feel free to update the labels and let the team know. 🙂