## :dart: Why Today only `namespaces.id` is a UUID (UUIDv7, globally unique across deployments). Every other table uses a `bigint` primary key that is unique only within a single database. We want all tables on UUIDv7 primary keys, except an internal blob-storage tier that is never exposed through the API. **Why now:** the role-assignment flow behind [#181](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/181) authorizes against the IAM Relationships API, whose resource is `Object { id: UUIDv7 }`. An AR resource can only be a role-assignment target if it has a stable, globally-unique UUID — a local `bigint` PK cannot serve as that identifier. See [ADR-007](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/007_database_schema.md) for the current design. ## :compass: Scope Strictly the primary-key type. Composite PK shape, `HASH` partitioning, partition counts, and FK relationships are unchanged. - Every `id` column **except the blob-storage tier** (`blob_storage_attachments`, `blob_storage_blobs`, `upload_sessions`): `bigint` → `uuid` (UUIDv7). - **The blob-storage tier keeps its `bigint` sequence-backed `id`.** These tables are internal storage, never exposed through the API, and carry the highest-volume rows. `upload_sessions` is internal storage-session state (keyed by `upload_id`), so it joins that tier. - Every FK column referencing a **converted** id: `bigint` → `uuid`. FK columns referencing the blob-storage tier (for example `blob_storage_attachment_id`) stay `bigint`. Note: `upload_sessions.repository_id` is `uuid` because it holds a `repositories.id`, even though the table keeps a `bigint` PK. - Composite PKs stay as they are: `namespace_id` (or `sha256` on the two blob tables) remains in the PK because Postgres requires the partition key in every unique constraint. - Drop the per-table sequences (`CREATE SEQUENCE`, `OWNED BY`, `DEFAULT nextval(...)`) **on the converted tables only**; the blob-storage tier keeps its sequences. - Edit the existing migrations in place — nothing is deployed, so rewrite the `CREATE TABLE` bodies instead of adding `ALTER TABLE` migrations. - Regenerate `structure.sql` and the go-jet packages under `internal/datastore/jet/`. ## :open_book: Decisions 1. **ID generation: same as `namespaces.id`** — column is `uuid NOT NULL` with no DB default, generated app-side as UUIDv7 (can move to native `uuidv7()` later). Real ids use `uuid.NewV7()` (`github.com/google/uuid`, already a dependency); a shared `newID()` helper centralizes this. 1. **No new spec.** PK design lives in ADR-007 and `docs/dev/database.md` (referenced by S04); amend those. 1. **Scope rule:** only the blob-storage tier (`blob_storage_attachments`, `blob_storage_blobs`, `upload_sessions`) keeps a `bigint` PK; every other table uses UUIDv7. Decided on this issue (the "API-exposed only" spike showed FK pressure pulls in almost every table, so the clean line is "blob-storage tier stays `bigint`, everything else `uuid`"). ## :scroll: ADR changes ADRs sync from the [handbook repo](https://gitlab.com/gitlab-com/content-sites/handbook/-/tree/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions), so these land as a **handbook MR**, not here. - **ADR-007 (Database schema):** - Update the Context line stating all non-namespace ids are `bigint`. - Replace the "Namespace ID type" rationale with the new rule: UUIDv7 for all tables except the blob-storage tier. - Update each Mermaid ER entry for converted tables: `bigint id PK` → `uuid id PK`, and `bigint <table>_id FK` → `uuid` (FKs to the blob-storage tier stay `bigint`). - Revise the `blob_storage_attachments` / `blob_storage_blobs` / `upload_sessions` PK paragraphs to state they **keep** a `bigint` id (internal, highest-volume, never API-exposed), while everything else moves to UUIDv7. Note that app-side UUIDv7 removes the server-side sequence that was the logical-replication desync concern. - **ADR-022 (Namespace decoupling):** update any cross-deployment migration text that assumes `bigint` child ids. ## :books: Spec / doc changes - **`docs/dev/database.md`:** rewrite "Primary key types" (the `bigint`/`nextval` convention and the three-statement sequence pattern) to the new rule. - **`docs/specs/S04-database.md`:** confirm it is consistent and fix any `bigint` examples. - No new spec. ## :card_index_dividers: Tables `namespaces` already uses UUIDv7 — no change. The `river_*` tables (vendored third-party background-job schema) are excluded. ### :twisted_rightwards_arrows: Migrate to `uuid` (edit migrations in place) — 19 tables - [x] `repositories` - [x] `repository_collections` - [x] `repository_collection_repositories` (join — FKs `repository_collection_id`, `repository_id`; no own `id`) - [x] `container_repositories` - [x] `container_images` - [x] `container_blobs` - [x] `container_manifests` - [x] `container_manifest_relationships` - [x] `container_tags` - [x] `npm_repositories` - [x] `npm_packages` - [x] `npm_versions` - [x] `npm_tags` - [x] `npm_files` - [x] `npm_metadata_files` - [x] `maven_repositories` - [x] `maven_packages` - [x] `maven_versions` - [x] `maven_files` FK columns that flip to `uuid`: `repository_id`, `repository_collection_id`, `container_repository_id`, `container_image_id`, `container_manifest_id`, `parent_container_manifest_id`, `child_container_manifest_id`, `npm_repository_id`, `npm_package_id`, `npm_version_id`, `maven_repository_id`, `maven_package_id`, `maven_version_id`. (`blob_storage_attachment_id` stays `bigint`.) ### :lock: Keep `bigint` id (blob-storage tier) - `blob_storage_attachments` (PK `(id, namespace_id, sha256)`) - `blob_storage_blobs` (PK `(id, namespace_id, sha256)`) - `upload_sessions` (PK `(id, namespace_id)`; `repository_id` is `uuid`) ### :scroll: ADR-only / not-yet-built tables (handbook doc update only) Defined in ADR-007's diagrams but without migrations yet — update the ADR for consistency, no migration work now: `lifecycle_policy_settings`, `lifecycle_rules`, `artifact_type_repository_lifecycle_policy_settings`, `artifact_type_repository_lifecycle_rules`, the `container_remote_*` / `virtual_container_*` families, the maven **remote/virtual** families (the hosted `maven_*` tables now exist and are in the migrate list above), and the `npm_remote_*` / `npm_virtual_*` families. ## :hammer: Go code impact Models and stores type these ids as `int64` (e.g. `ID int64`) across `internal/datastore` and `internal/storage`, plus test fixtures that build ids as `int64` literals. The converted ids become `uuid.UUID`, with updated store signatures and a shared UUIDv7 helper (`internal/datastore/ids.go`). The go-jet `model`/`table` packages are regenerated, not hand-edited. The management API serializes `Repository.id` as a `uuid` string (was `int64`). ## :triangular_ruler: Size and delivery Large but mostly mechanical — most of the diff is regenerated code and test-fixture updates, not logic. It can't be split cleanly: a FK column's type must match the PK it references, and migrations are edited in place, so every merged commit must leave the schema consistent and `main` green. - **Plan MR: waived** — agreed on this issue that a single mechanical change is easier to review as one code diff. - One **implementation MR**: [!705](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/705), ordered migrations → regenerate `structure.sql`/jet → model & store types → tests. ## :white_check_mark: Acceptance criteria - [x] Listed migrations rewritten in place; converted `id` and referencing FK columns are `uuid`; per-table sequences removed on converted tables; the blob-storage tier keeps `bigint`. - [x] `structure.sql` and go-jet packages regenerated and consistent. - [x] Migrations run up and down cleanly. - [x] Go models/stores and tests updated; full suite green. - [x] ADR-007 (and ADR-022 if needed) amended via handbook MR (linked here). - [x] `docs/dev/database.md` and S04 updated. ## :link: Relationships - **Blocks** [#181](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/181) (batch resource-to-organization resolution endpoint). - Parent epic: [Artifact Registry Closed Beta](https://gitlab.com/groups/gitlab-org/-/epics/21052) (same as #181).