Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(store): make every offset-paginated list sort on a total order (T14) (#21267)

Danny Xu944956ff873c
diff --git a/AGENTS.md b/AGENTS.md
index eb38e26bd4..7251aab6d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,14 @@ This repo uses a single-context domain-doc layout. See `docs/agents/domain.md`.
- `./backend/migrator/migration/LATEST.sql` should be updated for DDL migrations
- Files in `./backend/store` are mappings to the database tables
+Anything that writes SQL against the metadata database is governed by
+[`backend/store/AGENTS.md`](backend/store/AGENTS.md): composite-primary-key
+predicates, pagination ordering, and transaction row-lock ordering. That means
+all of `backend/store/` — including the CEL-to-SQL filter builders, which live
+there and not in the service layer — plus the raw metadata reads in the
+`backend/tests/` collision tests. Read it before adding or modifying a query, a
+paginated list, or a multi-row transaction.
+
## Development Workflow
**ALWAYS follow these steps after making code changes:**
@@ -194,61 +202,6 @@ The canonical frontend ownership map is in `./frontend/AGENTS.md`. In summary:
- React app state lives under `./frontend/src/stores/` — the core slices are in `stores/app/`, consumed via the `useAppStore` hook. Routing helpers live in `./frontend/src/app/router/`
- React `.tsx` is compiled by esbuild (`react-tsx-transform` Vite plugin) and type-checked with `tsc --build` via `pnpm --dir frontend type-check`
-## Naming
-
-- Use American English
-- Avoid plurals like "xxxList" for simplicity and to prevent singular/plural ambiguity stemming from poor design
-
-## Composite Primary Keys
-
-Several tables use composite primary keys (e.g., `(project, id)`). Check
-`backend/migrator/migration/LATEST.sql` for the full list — any table with a
-multi-column PRIMARY KEY. `task_run_log` deliberately has no primary key (it is
-an append-only log whose entries can share a `created_at` microsecond,
-BYT-10035) but is equally project-scoped, so the same predicate rules apply to
-it.
-
-When writing or modifying queries on these tables:
-- Every WHERE, JOIN, USING, DELETE, and UPDATE predicate must include every
- project/tenant scope column. Identify rows with either the full primary key or
- a full declared non-partial UNIQUE key that contains the same scope columns;
- verify alternate keys in `LATEST.sql`. Never filter by `id` or another locally
- unique identifier alone
-- When adding a new store method touching a composite-PK table, add a corresponding
- `TestCollision_*` test in `backend/tests/`. The existing `setupCollidingProjects`
- fixture and `assertProjectUnchanged` helper cover `plan`, `issue`, `task`, `task_run`,
- `plan_check_run`, `task_run_log`, `db_group`, `release`, and `sheet_blob_ref` (the
- snapshot reads the last four through public APIs where one exists). `plan_webhook_delivery`
- has no public read API and uses a table-specific raw metadata-DB read; its rows are
- claimed asynchronously after rollout completion, so raw-read collision tests
- must stabilize before snapshotting and compare the table separately (see
- `backend/tests/README.md`). `sheet_blob_ref` also has no public read API and is
- read raw, but its rows are written synchronously, so `assertProjectUnchanged`
- compares them directly. For any future composite-PK table outside that set,
- write table-specific seed and assertion helpers — or extend the shared helper
- first
-- Collision tests use `setupCollidingProjects` + `fixture.completeRolloutB` for setup
- and `snapshotProject` / `assertProjectUnchanged` for assertions — all going through
- the public gRPC API, no store access. Run with:
- `go test -v -count=1 ./backend/tests/ -run "^(TestClaim|TestCollision)" -timeout 5m`
-
-## Transaction Lock Ordering
-
-Before adding or modifying a transaction that locks multiple rows or tables, follow the canonical [store row-lock ordering](backend/store/README.md#transaction-row-lock-ordering). Lock existing child rows before parents, lock batches in full primary-key order, and treat upserts as existing-row locks. Add the deterministic real-PostgreSQL regression tests required below for new multi-row or multi-table coordination paths.
-
-Row ordering prevents wait-for cycles on existing rows, but it cannot protect a
-child row that does not exist yet. `nextProjectID` closes that gap for its callers:
-it locks the project and requires the project to be active before allocating an ID,
-so creation is rejected when the project is missing or deleted. This is not a
-repository-wide purge fence because some writers bypass `nextProjectID`.
-
-Every new or modified writer of purge-managed data must define whether its
-lifecycle policy requires an active project or merely an existing project, then
-serialize and validate that policy against project deletion. Add deterministic
-real-PostgreSQL tests for both lock-acquisition directions. Assert the terminal
-outcomes, including that neither direction ends in a foreign-key failure; merely
-checking for the absence of SQLSTATE `40P01` is insufficient.
-
### Imports
- Use organized imports (sorted by the import path)
@@ -261,6 +214,11 @@ checking for the absence of SQLSTATE `40P01` is insufficient.
- Be explicit but concise about error cases
+## Naming
+
+- Use American English
+- Avoid plurals like "xxxList" for simplicity and to prevent singular/plural ambiguity stemming from poor design
+
## Pull Request Guidelines
**Before running `gh pr create`, walk through [`docs/pre-pr-checklist.md`](docs/pre-pr-checklist.md).** It covers the breaking-change review, composite-PK query safety, lint/test gates, and SonarCloud properties — the checks that lint and CI can't catch on their own.
diff --git a/backend/store/AGENTS.md b/backend/store/AGENTS.md
new file mode 100644
index 0000000000..69da6d8a78
--- /dev/null
+++ b/backend/store/AGENTS.md
@@ -0,0 +1,206 @@
+# Bytebase storage package
+
+This file provides additional guidance to AI coding assistants working under
+`./backend/store/`, the mapping between Go and the metadata database.
+
+## Inheritance
+
+- Follow the repository-wide guidance in `../../AGENTS.md`.
+- Treat this file as store-specific additions, not a replacement for the root instructions.
+
+For schema update, please follow [Bytebase Schema Update Guide](https://github.com/bytebase/bytebase/blob/main/docs/schema-update-guide.md)
+
+## Composite primary keys
+
+Several tables use composite primary keys (e.g., `(project, id)`). Check
+`backend/migrator/migration/LATEST.sql` for the full list — any table with a
+multi-column PRIMARY KEY. `task_run_log` deliberately has no primary key (it is
+an append-only log whose entries can share a `created_at` microsecond,
+BYT-10035) but is equally project-scoped, so the same predicate rules apply to
+it.
+
+When writing or modifying queries on these tables:
+- Every WHERE, JOIN, USING, DELETE, and UPDATE predicate must include every
+ project/tenant scope column. Identify rows with either the full primary key or
+ a full declared non-partial UNIQUE key that contains the same scope columns;
+ verify alternate keys in `LATEST.sql`. Never filter by `id` or another locally
+ unique identifier alone
+- When adding a new store method touching a composite-PK table, add a
+ corresponding `TestCollision_*` test in `backend/tests/`, built on
+ `setupCollidingProjects` + `fixture.completeRolloutB` for setup and
+ `snapshotProject` / `assertProjectUnchanged` for assertions — all going through
+ the public gRPC API, no store access. Run with:
+ `go test -v -count=1 ./backend/tests/ -run "^(TestClaim|TestCollision)" -timeout 5m`
+- Which tables the shared snapshot already covers, and the two (`plan_webhook_delivery`,
+ `sheet_blob_ref`) that need table-specific handling because they have no public
+ read API, are listed in [`docs/pre-pr-checklist.md`](../../docs/pre-pr-checklist.md)
+ step 3c. That is the copy kept in step with the fixture — read it there rather
+ than trusting a restatement here
+
+## Pagination ordering
+
+Every paginated v1 list reads its pages with `LIMIT`/`OFFSET`: the page token
+carries `{limit, offset}` (`backend/api/v1/common.go`), so each page is a
+separate query against a table that other transactions are still writing.
+
+PostgreSQL only guarantees the order the `ORDER BY` specifies. When the sort key
+is not unique under the query's scope, tied rows may come back in a different
+order in each of those queries — different effective `LIMIT` values pick top-N
+heapsort or a full sort, and parallel gather-merge interleaves workers
+independently. A tied row then crosses the page boundary between two reads, and
+the caller skips it or receives it twice. This is not a concurrency artifact: it
+happens on completely static data. Measured on 10,000 issues across 40 projects
+by issuing the 100 page queries separately, exactly as the API does: ordering by
+`issue.id` alone returned 10,000 rows of which only 9,764 were distinct — 236
+duplicated and 236 never returned at all. Adding `issue.project` makes it
+10,000 of 10,000.
+
+**Every offset-paginated query must sort on a total order.** Write the clause
+out — the tiebreak columns are part of the SQL, not something to build:
+
+```go
+// created_at defaults to now() and is not unique; resource_id is the primary key.
+q.Space("ORDER BY changelog.created_at DESC, changelog.resource_id DESC")
+```
+
+Where a caller-supplied `order_by` leads, append the same columns after it:
+
+```go
+orderBy := []string{}
+for _, v := range find.OrderByKeys {
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
+}
+if len(orderBy) == 0 {
+ orderBy = append(orderBy, "access_grant.created_at DESC")
+}
+orderBy = append(orderBy, "access_grant.id DESC")
+q.Space("ORDER BY " + strings.Join(orderBy, ", "))
+```
+
+There is deliberately no shared helper for this. One existed and was removed in
+review: it put four lines of ceremony on the ten lists whose clause is a
+constant, and the SQL reads better written out. If a caller's key repeats a
+tiebreak column, leave it — PostgreSQL ignores a redundant sort key.
+
+Rules for choosing the tiebreak:
+
+1. Take it from the table's primary key or a declared **non-partial** unique key
+ in `LATEST.sql`. A partial unique index (`... WHERE deleted_at IS NULL`)
+ constrains nothing outside its predicate, so it does not qualify whenever the
+ query can return rows outside it.
+2. Include **every** column of a composite key. `id` alone does not identify a
+ row in a `(project, id)` table, and IDs are allocated per project by
+ `nextProjectID` — every project's first row is `101` — so cross-project lists
+ collide constantly. `(project, train, iteration)` needs all three.
+3. A column is only a valid tiebreak if it is `NOT NULL`. `user_group.email` is
+ nullable, so groups without one all tie.
+4. `created_at` is never a tiebreak. It defaults to `now()`, which is the
+ *transaction* timestamp, so every row written by one batch insert shares it
+ exactly.
+5. A mandatory `WHERE` predicate that pins a scope column to one value already
+ supplies that column, so the rest of the key is total on its own and needs no
+ tiebreak. `ListPlans` is total under `WHERE plan.project = ?` with nothing but
+ `ORDER BY id DESC`, because `(project, id)` is the primary key. Naming the
+ pinned column anyway is free in the plan — PostgreSQL folds a
+ constant-equality column out of the pathkeys — but it is not a fix, and adding
+ it to a query that is already total is churn. What matters is the reverse: if
+ you ever relax such a predicate into a cross-scope list, the ordering stops
+ being total that moment and the tiebreak becomes mandatory.
+6. A user-supplied `order_by` replaces the default *sort key* — that is correct
+ AIP-132 behavior — but it must never replace the *tiebreak*. Append the
+ tiebreak after the caller's keys, as in the snippet above. `ListDatabases`,
+ `ListInstances` and `ListProjects` each used to drop the whole clause,
+ tiebreak included, the moment a caller passed `order_by`.
+7. Check what the clause costs. Appending a tiebreak can turn an ordered index
+ scan into an incremental sort, so `EXPLAIN` against the query's *real*
+ predicate shape, not an idealized one, and keep the tiebreak's direction
+ matching any index you rely on — `ListSavedQueries` does, so that
+ `order_by: update_time desc` still reads
+ `idx_saved_query_creator_updated_at_resource_id` in order. Then decide
+ deliberately: widen the index with a migration, or accept the cost and say
+ so. Accepted here: `SearchAuditLogs` costs ~16 ms more per 5000-row export
+ page because `resource_id` falls outside
+ `idx_audit_log_workspace_created_at`; judged not worth a migration.
+
+### What is and is not enforced
+
+`TestPaginationStabilityAcrossProjects` pages through a deliberately tied
+cross-project issue list against a real PostgreSQL and asserts every row comes
+back exactly once; `TestIssueCommentBatchKeepsInsertionOrder` pins the batch
+ordering. Both fail against the pre-fix behavior. Add a case when a new list's
+tiebreak is not obviously total.
+
+Nothing checks this statically. An earlier revision routed all 17 lists through
+a shared helper so an AST test could require it; review judged that ceremony,
+the helper is gone, and the guard had no chokepoint left to police. So the rules above are
+enforced by the pre-PR checklist and by review, not by a test — which means a
+new paginated list added without a tiebreak will not fail CI. Step 4 of
+[`docs/pre-pr-checklist.md`](../../docs/pre-pr-checklist.md) is the gate.
+
+A total order fixes misordering, not drift: rows inserted or deleted between two
+page reads still shift the offset window. Fixing that needs keyset pagination
+and a page-token format change, which is out of scope here.
+
+## Transaction row-lock ordering
+
+PostgreSQL holds row locks until a transaction ends. Transactions that acquire the same locks in different orders can deadlock, so every store transaction must follow these rules:
+
+1. Acquire transaction-scoped advisory locks before row locks.
+2. Lock existing related rows from the deepest child to its parents. The project workflow chains are:
+ - `issue_comment -> issue -> plan -> project`
+ - `review_run -> issue -> plan -> project`
+ - `plan_webhook_delivery -> plan -> project`
+ - `plan_check_run -> plan -> project`
+ - `task_run_log -> task_run -> task -> plan -> project`
+ - `saved_query_organizer -> saved_query -> project`
+ - `changelog -> sync_history -> db -> instance -> project`
+ - `revision -> db -> instance -> project`
+ - `db_schema -> db -> instance -> project`
+3. Identify project-scoped rows with every scope column plus either the remaining primary-key columns or every remaining column of a declared non-partial unique key. Verify alternate keys in `LATEST.sql`. Lock batches in full primary-key order; project-scoped `(project, id)` batches therefore use that order, not `id` alone.
+4. Treat locks acquired by `UPDATE`, `DELETE`, foreign-key checks, and `INSERT ... ON CONFLICT DO UPDATE` as part of the order. An upsert that can update an existing row is not a new-row-only insert.
+5. `nextProjectID` locks `project` and requires it to be active before allocating an ID. Call it after locking any existing descendants, and do not lock an existing descendant afterward. Creation is rejected when the project is missing or deleted.
+
+Row ordering prevents wait-for cycles on existing rows. It cannot protect an
+absent child row because there is no row to lock before a concurrent purge passes
+that branch. The active-project check in `nextProjectID` covers this case only for
+writers that call it; it is not a repository-wide purge fence because other
+writers bypass `nextProjectID`.
+
+Database creation, database-sync, batch database updates, task-run creation,
+sheet creation, and Query History writers, together with direct instance
+archive and direct project/instance purge, additionally take the matching
+transaction-scoped purge fence before any row lock. This closes absent-descendant gaps; writers then
+retain the normal child-to-parent row-lock order. Database sync may continue for
+an archived project while its row exists, but never through a soft-deleted
+instance. Direct instance archive and restore fail while any targeting task run
+is pending, available, or running.
+
+Every new or modified writer of purge-managed data must define its project
+lifecycle policy: require an active project for new resources, or require only an
+existing project when deleted-project continuation is intentional. Serialize and
+validate that policy against project deletion before writing the managed data.
+
+Transactions spanning project- or instance-owned sibling branches follow this canonical order:
+
+```text
+query_history -> policy -> saved_query_organizer -> saved_query
+-> issue_comment -> review_run -> issue -> plan_webhook_delivery -> plan_check_run
+-> task_run_log -> task_run -> task -> plan -> access_grant -> release
+-> db_group -> changelog -> sync_history -> revision -> db_schema -> db
+-> sheet_blob_ref -> project_webhook -> service_account -> workload_identity -> instance -> project
+```
+
+Update this list, `DeleteProject`, and `DeleteInstance` together. A transaction that needs another sibling branch must establish its position here before implementation. When one table is touched by multiple predicates, keep those mutations contiguous at that table's position. Keep transactions short and preserve this order whether locks are acquired explicitly or by `UPDATE` and `DELETE` statements.
+
+Examples:
+
+- Pending Task Run creation: existing `task` rows ordered by `(project, id)`, then `project`, then new `task_run` rows.
+- Plan Check Run refresh: existing `plan_check_run`, then `plan`, then `project`, then the upsert.
+- Issue creation: existing `plan`, then `project`, then the new `issue` row.
+- Task skipping: existing `task` rows ordered by `(project, id)`; it does not lock `task_run` rows.
+
+When adding or changing a transaction that coordinates multiple rows or tables,
+add deterministic real-PostgreSQL regression tests for both lock-acquisition
+directions. Assert the terminal outcomes, including that neither direction ends
+in a foreign-key failure; merely checking for the absence of SQLSTATE `40P01` is
+insufficient.
diff --git a/backend/store/CLAUDE.md b/backend/store/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/backend/store/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/backend/store/README.md b/backend/store/README.md
deleted file mode 100644
index 279c0935ff..0000000000
--- a/backend/store/README.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Bytebase storage package
-
-For schema update, please follow [Bytebase Schema Update Guide](https://github.com/bytebase/bytebase/blob/main/docs/schema-update-guide.md)
-
-## Transaction row-lock ordering
-
-PostgreSQL holds row locks until a transaction ends. Transactions that acquire the same locks in different orders can deadlock, so every store transaction must follow these rules:
-
-1. Acquire transaction-scoped advisory locks before row locks.
-2. Lock existing related rows from the deepest child to its parents. The project workflow chains are:
- - `issue_comment -> issue -> plan -> project`
- - `review_run -> issue -> plan -> project`
- - `plan_webhook_delivery -> plan -> project`
- - `plan_check_run -> plan -> project`
- - `task_run_log -> task_run -> task -> plan -> project`
- - `saved_query_organizer -> saved_query -> project`
- - `changelog -> sync_history -> db -> instance -> project`
- - `revision -> db -> instance -> project`
- - `db_schema -> db -> instance -> project`
-3. Identify project-scoped rows with every scope column plus either the remaining primary-key columns or every remaining column of a declared non-partial unique key. Verify alternate keys in `LATEST.sql`. Lock batches in full primary-key order; project-scoped `(project, id)` batches therefore use that order, not `id` alone.
-4. Treat locks acquired by `UPDATE`, `DELETE`, foreign-key checks, and `INSERT ... ON CONFLICT DO UPDATE` as part of the order. An upsert that can update an existing row is not a new-row-only insert.
-5. `nextProjectID` locks `project` and requires it to be active before allocating an ID. Call it after locking any existing descendants, and do not lock an existing descendant afterward. Creation is rejected when the project is missing or deleted.
-
-Row ordering prevents wait-for cycles on existing rows. It cannot protect an
-absent child row because there is no row to lock before a concurrent purge passes
-that branch. The active-project check in `nextProjectID` covers this case only for
-writers that call it; it is not a repository-wide purge fence because other
-writers bypass `nextProjectID`.
-
-Database creation, database-sync, batch database updates, task-run creation,
-sheet creation, and Query History writers, together with direct instance
-archive and direct project/instance purge, additionally take the matching
-transaction-scoped purge fence before any row lock. This closes absent-descendant gaps; writers then
-retain the normal child-to-parent row-lock order. Database sync may continue for
-an archived project while its row exists, but never through a soft-deleted
-instance. Direct instance archive and restore fail while any targeting task run
-is pending, available, or running.
-
-Every new or modified writer of purge-managed data must define its project
-lifecycle policy: require an active project for new resources, or require only an
-existing project when deleted-project continuation is intentional. Serialize and
-validate that policy against project deletion before writing the managed data.
-
-Transactions spanning project- or instance-owned sibling branches follow this canonical order:
-
-```text
-query_history -> policy -> saved_query_organizer -> saved_query
--> issue_comment -> review_run -> issue -> plan_webhook_delivery -> plan_check_run
--> task_run_log -> task_run -> task -> plan -> access_grant -> release
--> db_group -> changelog -> sync_history -> revision -> db_schema -> db
--> sheet_blob_ref -> project_webhook -> service_account -> workload_identity -> instance -> project
-```
-
-Update this list, `DeleteProject`, and `DeleteInstance` together. A transaction that needs another sibling branch must establish its position here before implementation. When one table is touched by multiple predicates, keep those mutations contiguous at that table's position. Keep transactions short and preserve this order whether locks are acquired explicitly or by `UPDATE` and `DELETE` statements.
-
-Examples:
-
-- Pending Task Run creation: existing `task` rows ordered by `(project, id)`, then `project`, then new `task_run` rows.
-- Plan Check Run refresh: existing `plan_check_run`, then `plan`, then `project`, then the upsert.
-- Issue creation: existing `plan`, then `project`, then the new `issue` row.
-- Task skipping: existing `task` rows ordered by `(project, id)`; it does not lock `task_run` rows.
-
-When adding or changing a transaction that coordinates multiple rows or tables,
-add deterministic real-PostgreSQL regression tests for both lock-acquisition
-directions. Assert the terminal outcomes, including that neither direction ends
-in a foreign-key failure; merely checking for the absence of SQLSTATE `40P01` is
-insufficient.
diff --git a/backend/store/access_grant.go b/backend/store/access_grant.go
index d6a1dc99f4..d4a24a6eaf 100644
--- a/backend/store/access_grant.go
+++ b/backend/store/access_grant.go
@@ -137,15 +137,17 @@ func (s *Store) ListAccessGrants(ctx context.Context, find *FindAccessGrantMessa
q.And("creator = ?", *v)
}
- if len(find.OrderByKeys) > 0 {
- orderBy := []string{}
- for _, v := range find.OrderByKeys {
- orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
- }
- q.Space(fmt.Sprintf("ORDER BY %s", strings.Join(orderBy, ", ")))
- } else {
- q.Space("ORDER BY created_at DESC")
+ // created_at defaults to now() and is not unique; id is the primary key and
+ // makes the ordering total, so offset pages cannot skip or repeat.
+ orderBy := []string{}
+ for _, v := range find.OrderByKeys {
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
+ }
+ if len(orderBy) == 0 {
+ orderBy = append(orderBy, "access_grant.created_at DESC")
}
+ orderBy = append(orderBy, "access_grant.id DESC")
+ q.Space("ORDER BY " + strings.Join(orderBy, ", "))
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/audit_log.go b/backend/store/audit_log.go
index 41a534fe96..da396dc712 100644
--- a/backend/store/audit_log.go
+++ b/backend/store/audit_log.go
@@ -72,15 +72,17 @@ func (s *Store) SearchAuditLogs(ctx context.Context, find *AuditLogFind) ([]*Aud
q.And("payload->>'parent' = ?", *v)
}
- if len(find.OrderByKeys) > 0 {
- orderBy := []string{}
- for _, v := range find.OrderByKeys {
- orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
- }
- q.Space(fmt.Sprintf("ORDER BY %s", strings.Join(orderBy, ", ")))
- } else {
- q.Space("ORDER BY created_at DESC")
+ // created_at defaults to now() and is not unique; resource_id is the
+ // primary key. Audit exports page through this at 5000 rows a time.
+ orderBy := []string{}
+ for _, v := range find.OrderByKeys {
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
+ }
+ if len(orderBy) == 0 {
+ orderBy = append(orderBy, "created_at DESC")
}
+ orderBy = append(orderBy, "audit_log.resource_id DESC")
+ q.Space("ORDER BY " + strings.Join(orderBy, ", "))
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/changelog.go b/backend/store/changelog.go
index 893359fba3..a18b23bd57 100644
--- a/backend/store/changelog.go
+++ b/backend/store/changelog.go
@@ -192,6 +192,8 @@ func buildListChangelogsQuery(find *FindChangelogMessage) (string, []any, error)
q.And("changelog.created_at < ?", *v)
}
+ // created_at defaults to now() and is not unique; resource_id is the
+ // primary key, and completes the ordering so offset pages stay stable.
q.Space("ORDER BY changelog.created_at DESC, changelog.resource_id DESC")
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
diff --git a/backend/store/database.go b/backend/store/database.go
index 1aea384f87..6f7a807910 100644
--- a/backend/store/database.go
+++ b/backend/store/database.go
@@ -192,15 +192,23 @@ func (s *Store) ListDatabases(ctx context.Context, find *FindDatabaseMessage) ([
WHERE ?
`, from, where)
- if len(find.OrderByKeys) > 0 {
- orderBy := []string{}
- for _, v := range find.OrderByKeys {
- orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
- }
- q.Space(fmt.Sprintf("ORDER BY %s", strings.Join(orderBy, ", ")))
- } else {
- q.Space("ORDER BY db.project, db.instance, db.name")
- }
+ // Neither project nor name identifies a database; (instance, name) is the
+ // primary key. That stays unique in the result only because every join
+ // above is at most 1:1 — db_schema is joined on its own full primary key,
+ // and instance.resource_id is a primary key. A one-to-many join added here
+ // would duplicate rows and silently un-stabilize paging again.
+ //
+ // A caller sorting by instance or name repeats that column below, which
+ // PostgreSQL ignores as a redundant sort key.
+ orderBy := []string{}
+ for _, v := range find.OrderByKeys {
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
+ }
+ if len(orderBy) == 0 {
+ orderBy = append(orderBy, "db.project ASC")
+ }
+ orderBy = append(orderBy, "db.instance ASC", "db.name ASC")
+ q.Space("ORDER BY " + strings.Join(orderBy, ", "))
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
diff --git a/backend/store/group.go b/backend/store/group.go
index e4a39e0ed3..c64ca7b4a9 100644
--- a/backend/store/group.go
+++ b/backend/store/group.go
@@ -141,9 +141,14 @@ func (s *Store) ListGroups(ctx context.Context, find *FindGroupMessage) ([]*Grou
user_group.payload
FROM ?
WHERE ?
- ORDER BY email
`, from, where)
+ // email is nullable — CreateGroup writes NULL for an empty one — and its
+ // unique index is partial, so it does not identify a group. id is the
+ // primary key, and stays unique in the result because the project filter
+ // joins a single-row ARRAY_AGG CTE rather than the member rows themselves.
+ q.Space("ORDER BY user_group.email ASC, user_group.id ASC")
+
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/id.go b/backend/store/id.go
index 17bb457417..0b25ccd5de 100644
--- a/backend/store/id.go
+++ b/backend/store/id.go
@@ -18,7 +18,7 @@ const idMinValue int64 = 101
// lockActiveProject locks the project row and requires it to be active,
// serializing the caller with project deletion. Creation is rejected with
// NotFound when the project is missing or deleted. This is the "requires an
-// active project" lifecycle policy from backend/store/README.md; call it
+// active project" lifecycle policy from backend/store/AGENTS.md; call it
// after locking any existing child rows.
func lockActiveProject(ctx context.Context, tx *sql.Tx, projectID string) error {
var deleted bool
@@ -38,7 +38,7 @@ func lockActiveProject(ctx context.Context, tx *sql.Tx, projectID string) error
// nextProjectID returns the next per-project auto-increment ID for the given table.
// Must be called within a transaction. Locks and validates the active project row to
// serialize concurrent inserts with project deletion.
-// Callers must first lock existing child rows as described in backend/store/README.md.
+// Callers must first lock existing child rows as described in backend/store/AGENTS.md.
// Returns at least idMinValue (101) for new projects.
func nextProjectID(ctx context.Context, tx *sql.Tx, table, projectID string) (int64, error) {
if err := lockActiveProject(ctx, tx, projectID); err != nil {
diff --git a/backend/store/instance.go b/backend/store/instance.go
index 3219905fc8..d6c31a3f06 100644
--- a/backend/store/instance.go
+++ b/backend/store/instance.go
@@ -137,15 +137,13 @@ func (s *Store) ListInstances(ctx context.Context, find *FindInstanceMessage) ([
WHERE ?
`, where)
- if len(find.OrderByKeys) > 0 {
- orderBy := []string{}
- for _, v := range find.OrderByKeys {
- orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
- }
- q.Space(fmt.Sprintf("ORDER BY %s", strings.Join(orderBy, ", ")))
- } else {
- q.Space("ORDER BY resource_id ASC")
+ // Titles and environments are not unique; resource_id is the primary key.
+ orderBy := []string{}
+ for _, v := range find.OrderByKeys {
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
}
+ orderBy = append(orderBy, "instance.resource_id ASC")
+ q.Space("ORDER BY " + strings.Join(orderBy, ", "))
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
diff --git a/backend/store/issue.go b/backend/store/issue.go
index 27343615fe..624c326e1f 100644
--- a/backend/store/issue.go
+++ b/backend/store/issue.go
@@ -320,7 +320,10 @@ func updateIssue(ctx context.Context, executor issueUpdateExecutor, projectID st
// ListIssues returns the list of issues by find query.
func (s *Store) ListIssues(ctx context.Context, find *FindIssueMessage) ([]*IssueMessage, error) {
- orderByClause := "ORDER BY issue.id DESC"
+ // Relevance ranking is derived from the query text rather than requested by
+ // the caller, so it is tracked apart from find.OrderByKeys. Set when the
+ // caller supplied query text that produced a tsquery.
+ var rankOrder string
from := qb.Q().Space("issue")
where := qb.Q()
@@ -371,7 +374,7 @@ func (s *Store) ListIssues(ctx context.Context, find *FindIssueMessage) ([]*Issu
if tsQuery := getTSQuery(*v); tsQuery != "" {
from.Space("LEFT JOIN CAST(? AS tsquery) AS query ON TRUE", tsQuery)
searchCondition.Or("issue.ts_vector @@ query")
- orderByClause = "ORDER BY ts_rank(issue.ts_vector, query) DESC, issue.id DESC"
+ rankOrder = "ts_rank(issue.ts_vector, query) DESC"
}
searchCondition.Or("issue.name ILIKE ?", "%"+*v+"%")
where.And("(?)", searchCondition)
@@ -397,14 +400,24 @@ func (s *Store) ListIssues(ctx context.Context, find *FindIssueMessage) ([]*Issu
where.And("COALESCE(issue.payload->>'draft', 'false') = 'false'")
}
- if len(find.OrderByKeys) > 0 && orderByClause == "ORDER BY issue.id DESC" {
- parts := make([]string, 0, len(find.OrderByKeys)+1)
+ // issue.id alone is not unique across projects — nextProjectID floors every
+ // project's first issue at 101 — so issue.project completes the
+ // (project, id) primary key and makes the ordering total.
+ //
+ // Which key leads is unchanged: relevance ranking still replaces the
+ // caller's order_by outright, and issue.id is still a per-project counter
+ // rather than a recency ordering across projects. Both are real problems,
+ // and both are separate ones.
+ orderBy := []string{}
+ if rankOrder != "" {
+ orderBy = append(orderBy, rankOrder)
+ } else {
for _, v := range find.OrderByKeys {
- parts = append(parts, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
}
- parts = append(parts, "issue.id DESC")
- orderByClause = fmt.Sprintf("ORDER BY %s", strings.Join(parts, ", "))
}
+ orderBy = append(orderBy, "issue.id DESC", "issue.project DESC")
+ orderByClause := "ORDER BY " + strings.Join(orderBy, ", ")
q := qb.Q().Space(`
SELECT
diff --git a/backend/store/issue_comment.go b/backend/store/issue_comment.go
index ae9200d768..628c8a12d3 100644
--- a/backend/store/issue_comment.go
+++ b/backend/store/issue_comment.go
@@ -74,7 +74,11 @@ func (s *Store) ListIssueComment(ctx context.Context, find *FindIssueCommentMess
q.And("issue_id = ?", *v)
}
- q.Space("ORDER BY created_at ASC")
+ // resource_id is the primary key. created_at alone would not be total —
+ // it defaults to now(), the transaction timestamp — so CreateIssueComments
+ // offsets each row of a batch by its ordinal to keep insertion order; see
+ // the comment there.
+ q.Space("ORDER BY issue_comment.created_at ASC, issue_comment.resource_id ASC")
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
@@ -146,9 +150,19 @@ func (s *Store) CreateIssueComments(ctx context.Context, creator string, creates
}
// Use UNNEST to insert all comments in one query.
+ //
+ // created_at defaults to now(), which is the transaction timestamp, so a
+ // batch would otherwise land on one instant and ListIssueComment could only
+ // fall back to its resource_id tiebreak — a random UUID, which scrambles the
+ // activity feed of a multi-field UpdateIssue. Offsetting each row by its
+ // ordinal keeps the batch in insertion order and makes created_at unique
+ // within it, at a cost of microseconds.
q := qb.Q().Space(`
- INSERT INTO issue_comment (creator, project, issue_id, payload)
- SELECT ?, unnest(?::TEXT[]), unnest(?::INT[]), unnest(?::JSONB[])
+ INSERT INTO issue_comment (creator, project, issue_id, payload, created_at, updated_at)
+ SELECT ?, c.project, c.issue_id, c.payload, t.at, t.at
+ FROM unnest(?::TEXT[], ?::INT[], ?::JSONB[])
+ WITH ORDINALITY AS c(project, issue_id, payload, ordinality),
+ LATERAL (SELECT now() + ((c.ordinality - 1) * interval '1 microsecond')) AS t(at)
`, creator, projectIDs, issueIDs, payloads)
// For single comment, use RETURNING to get the created comment details.
diff --git a/backend/store/pagination_integration_test.go b/backend/store/pagination_integration_test.go
new file mode 100644
index 0000000000..674bf338b5
--- /dev/null
+++ b/backend/store/pagination_integration_test.go
@@ -0,0 +1,182 @@
+package store_test
+
+import (
+ "context"
+ "database/sql"
+ "fmt"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common/testcontainer"
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/migrator"
+ "github.com/bytebase/bytebase/backend/store"
+
+ _ "github.com/bytebase/bytebase/backend/plugin/db/pg"
+)
+
+// TestPaginationStabilityAcrossProjects pages through a cross-project issue list
+// whose rows are deliberately tied on every sort key that is not a full primary
+// key, and asserts every issue is returned exactly once.
+//
+// Nothing checks this statically — see backend/store/AGENTS.md#pagination-ordering.
+// Against the pre-fix ordering (`ORDER BY issue.id DESC` alone) this fails:
+// issue IDs restart per project, so every id below is tied three ways and rows
+// cross the page boundary between reads.
+func TestPaginationStabilityAcrossProjects(t *testing.T) {
+ const (
+ workspaceID = "pagination-ws"
+ projectCount = 3
+ perProject = 60
+ pageSize = 7
+ )
+
+ ctx := context.Background()
+ container := testcontainer.GetTestPgContainer(ctx, t)
+ t.Cleanup(func() { container.Close(ctx) })
+ db := container.GetDB()
+ require.NoError(t, migrator.MigrateSchema(ctx, db))
+
+ projectIDs := make([]string, 0, projectCount)
+ for i := range projectCount {
+ projectIDs = append(projectIDs, fmt.Sprintf("pagination-p%d", i))
+ }
+ seedTiedIssues(ctx, t, db, workspaceID, projectIDs, perProject)
+
+ pgURL := fmt.Sprintf(
+ "host=%s port=%s user=postgres password=root-password database=postgres",
+ container.GetHost(), container.GetPort(),
+ )
+ stores, err := store.New(ctx, pgURL, false)
+ require.NoError(t, err)
+ t.Cleanup(func() { require.NoError(t, stores.Close()) })
+
+ // Walk the list the way the API does: a fresh LIMIT/OFFSET query per page.
+ seen := map[string]int{}
+ total := projectCount * perProject
+ for offset := 0; offset < total+pageSize; offset += pageSize {
+ limit, off := pageSize, offset
+ issues, err := stores.ListIssues(ctx, &store.FindIssueMessage{
+ ProjectIDs: projectIDs,
+ Limit: &limit,
+ Offset: &off,
+ })
+ require.NoErrorf(t, err, "page at offset %d", offset)
+ for _, issue := range issues {
+ seen[fmt.Sprintf("%s/%d", issue.ProjectID, issue.UID)]++
+ }
+ }
+
+ var duplicated []string
+ for key, count := range seen {
+ if count > 1 {
+ duplicated = append(duplicated, fmt.Sprintf("%s seen %d times", key, count))
+ }
+ }
+ require.Emptyf(t, duplicated, "offset paging returned the same issue more than once: %v", duplicated)
+ require.Lenf(t, seen, total,
+ "offset paging returned %d distinct issues, want %d — %d were skipped entirely",
+ len(seen), total, total-len(seen))
+}
+
+// seedTiedIssues writes projectCount projects each holding perProject issues,
+// all in one transaction so every row shares a created_at (now() is the
+// transaction timestamp) and IDs collide across projects.
+func seedTiedIssues(ctx context.Context, t *testing.T, db *sql.DB, workspaceID string, projectIDs []string, perProject int) {
+ t.Helper()
+
+ tx, err := db.BeginTx(ctx, nil)
+ require.NoError(t, err)
+ defer tx.Rollback() //nolint:errcheck
+
+ _, err = tx.ExecContext(ctx, `INSERT INTO workspace (resource_id) VALUES ($1)`, workspaceID)
+ require.NoError(t, err)
+
+ for _, projectID := range projectIDs {
+ _, err = tx.ExecContext(ctx,
+ `INSERT INTO project (resource_id, workspace, name) VALUES ($1, $2, $3)`,
+ projectID, workspaceID, projectID)
+ require.NoError(t, err)
+
+ // Start at 101 exactly as nextProjectID does, so ids collide across
+ // projects the way real data does.
+ _, err = tx.ExecContext(ctx, `
+ INSERT INTO issue (id, project, creator, name, status, type, description)
+ SELECT g, $1, 'users/[email protected]', 'issue ' || g, 'OPEN', 'DATABASE_CHANGE', ''
+ FROM generate_series(101, $2::int) g`,
+ projectID, 100+perProject)
+ require.NoError(t, err)
+ }
+ require.NoError(t, tx.Commit())
+}
+
+// TestIssueCommentBatchKeepsInsertionOrder pins the ordering of comments written
+// by one CreateIssueComments batch — the several activity events a multi-field
+// UpdateIssue produces.
+//
+// created_at is the transaction timestamp, so without the per-row ordinal offset
+// in CreateIssueComments the whole batch lands on one instant and
+// ListIssueComment falls through to its resource_id tiebreak, a random UUID.
+// The feed would then be stably scrambled: "labels changed" above "title
+// changed", permanently, for that issue.
+func TestIssueCommentBatchKeepsInsertionOrder(t *testing.T) {
+ ctx := context.Background()
+ container := testcontainer.GetTestPgContainer(ctx, t)
+ t.Cleanup(func() { container.Close(ctx) })
+ db := container.GetDB()
+ require.NoError(t, migrator.MigrateSchema(ctx, db))
+
+ const (
+ workspaceID = "comment-ws"
+ projectID = "comment-p"
+ issueUID = int64(101)
+ )
+ // One statement per Exec: a parameterized Exec goes through the extended
+ // query protocol, and a prepared statement cannot carry several commands.
+ _, err := db.ExecContext(ctx,
+ `INSERT INTO workspace (resource_id) VALUES ($1)`, workspaceID)
+ require.NoError(t, err)
+ _, err = db.ExecContext(ctx,
+ `INSERT INTO project (resource_id, workspace, name) VALUES ($1, $2, $1)`,
+ projectID, workspaceID)
+ require.NoError(t, err)
+ _, err = db.ExecContext(ctx, `
+ INSERT INTO issue (id, project, creator, name, status, type, description)
+ VALUES ($1, $2, 'users/[email protected]', 'issue', 'OPEN', 'DATABASE_CHANGE', '')`,
+ issueUID, projectID)
+ require.NoError(t, err)
+
+ pgURL := fmt.Sprintf(
+ "host=%s port=%s user=postgres password=root-password database=postgres",
+ container.GetHost(), container.GetPort(),
+ )
+ stores, err := store.New(ctx, pgURL, false)
+ require.NoError(t, err)
+ t.Cleanup(func() { require.NoError(t, stores.Close()) })
+
+ want := []string{"title", "description", "labels", "status", "assignee"}
+ creates := make([]*store.IssueCommentMessage, 0, len(want))
+ for _, comment := range want {
+ creates = append(creates, &store.IssueCommentMessage{
+ ProjectID: projectID,
+ IssueUID: issueUID,
+ Payload: &storepb.IssueCommentPayload{Comment: comment},
+ })
+ }
+ _, err = stores.CreateIssueComments(ctx, "users/[email protected]", creates...)
+ require.NoError(t, err)
+
+ uid := issueUID
+ got, err := stores.ListIssueComment(ctx, &store.FindIssueCommentMessage{
+ ProjectID: projectID,
+ IssueUID: &uid,
+ })
+ require.NoError(t, err)
+
+ order := make([]string, 0, len(got))
+ for _, comment := range got {
+ order = append(order, comment.Payload.Comment)
+ }
+ require.Equal(t, want, order, "a batch of issue comments must read back in insertion order")
+}
diff --git a/backend/store/principal.go b/backend/store/principal.go
index 96f3365b02..7fbbbe6bdf 100644
--- a/backend/store/principal.go
+++ b/backend/store/principal.go
@@ -271,9 +271,14 @@ func listUserImpl(ctx context.Context, txn *sql.Tx, find *FindUserMessage) ([]*U
principal.created_at
FROM ?
WHERE ?
- ORDER BY created_at ASC
`, from, where)
+ // created_at defaults to now(), so users provisioned by one SCIM sync
+ // share it; principal.id is the primary key, and stays unique in the result
+ // because the project and workspace filters join single-row ARRAY_AGG CTEs
+ // rather than the member rows themselves.
+ q.Space("ORDER BY principal.created_at ASC, principal.id ASC")
+
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/project.go b/backend/store/project.go
index 0ed6cee7bc..698f833176 100644
--- a/backend/store/project.go
+++ b/backend/store/project.go
@@ -122,15 +122,13 @@ func (s *Store) ListProjects(ctx context.Context, find *FindProjectMessage) ([]*
q.And("deleted = ?", false)
}
- if len(find.OrderByKeys) > 0 {
- orderBy := []string{}
- for _, v := range find.OrderByKeys {
- orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
- }
- q.Space(fmt.Sprintf("ORDER BY %s", strings.Join(orderBy, ", ")))
- } else {
- q.Space("ORDER BY project.resource_id")
+ // Titles are not unique; resource_id is the primary key.
+ orderBy := []string{}
+ for _, v := range find.OrderByKeys {
+ orderBy = append(orderBy, fmt.Sprintf("%s %s", v.Key, v.SortOrder.String()))
}
+ orderBy = append(orderBy, "project.resource_id ASC")
+ q.Space("ORDER BY " + strings.Join(orderBy, ", "))
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/release.go b/backend/store/release.go
index 821cbeabae..bfbbf4d455 100644
--- a/backend/store/release.go
+++ b/backend/store/release.go
@@ -163,7 +163,9 @@ func (s *Store) ListReleases(ctx context.Context, find *FindReleaseMessage) ([]*
q.And("deleted = ?", false)
}
- q.Space("ORDER BY release.created_at DESC")
+ // created_at defaults to now() and is not unique; (project, train,
+ // iteration) is the primary key.
+ q.Space("ORDER BY release.created_at DESC, release.project DESC, release.train DESC, release.iteration DESC")
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/revision.go b/backend/store/revision.go
index c4a3ca9ea6..0fc4d302e8 100644
--- a/backend/store/revision.go
+++ b/backend/store/revision.go
@@ -76,7 +76,10 @@ func (s *Store) ListRevisions(ctx context.Context, find *FindRevisionMessage) ([
if !find.ShowDeleted {
q.And("deleted_at IS NULL")
}
- q.Space("ORDER BY version DESC")
+ // version is unique only per (instance, db_name, type) and only while
+ // deleted_at IS NULL, so it does not identify a row on its own — least of
+ // all under ShowDeleted. resource_id is the primary key.
+ q.Space("ORDER BY revision.version DESC, revision.resource_id DESC")
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/service_account.go b/backend/store/service_account.go
index 8126129e67..6097fa5742 100644
--- a/backend/store/service_account.go
+++ b/backend/store/service_account.go
@@ -127,9 +127,11 @@ func (s *Store) ListServiceAccounts(ctx context.Context, find *FindServiceAccoun
project
FROM service_account
WHERE ?
- ORDER BY created_at ASC
`, where)
+ // created_at defaults to now() and is not unique; email is the primary key.
+ q.Space("ORDER BY service_account.created_at ASC, service_account.email ASC")
+
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/store/workload_identity.go b/backend/store/workload_identity.go
index 7ef6aeac0d..eed49dd0ca 100644
--- a/backend/store/workload_identity.go
+++ b/backend/store/workload_identity.go
@@ -138,9 +138,11 @@ func (s *Store) ListWorkloadIdentities(ctx context.Context, find *FindWorkloadId
config
FROM workload_identity
WHERE ?
- ORDER BY created_at ASC
`, where)
+ // created_at defaults to now() and is not unique; email is the primary key.
+ q.Space("ORDER BY workload_identity.created_at ASC, workload_identity.email ASC")
+
if v := find.Limit; v != nil {
q.Space("LIMIT ?", *v)
}
diff --git a/backend/tests/CLAUDE.md b/backend/tests/CLAUDE.md
new file mode 100644
index 0000000000..cbf28fbe9e
--- /dev/null
+++ b/backend/tests/CLAUDE.md
@@ -0,0 +1 @@
+@../store/AGENTS.md
diff --git a/backend/tests/collision_helper_test.go b/backend/tests/collision_helper_test.go
index e9b99d7620..a56f0cf07e 100644
--- a/backend/tests/collision_helper_test.go
+++ b/backend/tests/collision_helper_test.go
@@ -594,8 +594,8 @@ type projectSnapshot struct {
// planWebhookDelivery is one row of the plan_webhook_delivery table, which
// has no public gRPC read API. The collision suite snapshots it with the
-// table-specific direct DB read below (see AGENTS.md's allowance for
-// tables without public read APIs).
+// table-specific direct DB read below (see backend/store/AGENTS.md's
+// allowance for tables without public read APIs).
type planWebhookDelivery struct {
PlanID int64
EventType string
diff --git a/backend/tests/login_attempt_collision_test.go b/backend/tests/login_attempt_collision_test.go
index ebf4c0358b..b45f8cc466 100644
--- a/backend/tests/login_attempt_collision_test.go
+++ b/backend/tests/login_attempt_collision_test.go
@@ -15,8 +15,8 @@ import (
)
// TestCollision_LoginAttempt is the composite-PK collision gate for
-// login_attempt (PRIMARY KEY (identity, kind)) — see AGENTS.md and
-// docs/pre-pr-checklist.md step 3. The table is not project-scoped: identity
+// login_attempt (PRIMARY KEY (identity, kind)) — see
+// backend/store/AGENTS.md and docs/pre-pr-checklist.md step 3. The table is not project-scoped: identity
// is itself the scope column, so the shared project fixture does not apply.
// What collision safety means here is that no store operation may cross
// buckets: rows sharing an identity (other kind) or sharing a kind (other
diff --git a/docs/design/reauthenticate-credential-changes.md b/docs/design/reauthenticate-credential-changes.md
index 03602f3126..c7fb304139 100644
--- a/docs/design/reauthenticate-credential-changes.md
+++ b/docs/design/reauthenticate-credential-changes.md
@@ -195,7 +195,7 @@ the factor itself to change the factor closes both. (`ChangePassword` is unaffec
`current_password` with or without MFA, since changing the password is not touching the factor, and a
password change already revokes sessions so it cannot be a step toward one.) "Check, then mutate"
has to be one transaction with the account row locked (`SELECT ... FOR UPDATE`) from before the check
-to after the write, per this repo's own [row-lock ordering](../../backend/store/README.md#transaction-row-lock-ordering)
+to after the write, per this repo's own [row-lock ordering](../../backend/store/AGENTS.md#transaction-row-lock-ordering)
convention — not a read-verify-then-later-write sequence against a row nothing is holding. Without the
lock, two concurrent calls against the *same* still-current credential (an attacker who separately
obtained it, and the legitimate owner racing to rotate away from it) can both pass verification before
@@ -328,7 +328,7 @@ keeps working until it expires regardless (see G7).
Ordered wrong, though, as first written — [a sixth finding](https://github.com/bytebase/bytebase/pull/21235):
locking the principal row and only then deleting its `web_refresh_token` rows is parent-then-child,
backwards from this repo's mandatory rule of locking existing related rows child-to-parent
-(`backend/store/README.md#transaction-row-lock-ordering`), and `web_refresh_token.user_email` is a
+(`backend/store/AGENTS.md#transaction-row-lock-ordering`), and `web_refresh_token.user_email` is a
real foreign key to `principal.email` (`LATEST.sql:715-720`) — a `DELETE` on those rows counts as
acquiring a lock on them, same as an explicit `SELECT ... FOR UPDATE` would. Corrected order: lock the
account's *existing* `web_refresh_token` rows first (in primary-key order, if there's more than one),
diff --git a/docs/design/sheet-blob-scoping.md b/docs/design/sheet-blob-scoping.md
index 97ae98b5cb..5e1f94a60b 100644
--- a/docs/design/sheet-blob-scoping.md
+++ b/docs/design/sheet-blob-scoping.md
@@ -561,7 +561,7 @@ unreadable statements.
## Transaction lock ordering
`sheet_blob_ref` is a project-owned branch and takes a position in the canonical sibling order in
-`backend/store/README.md`, updating that list, `DeleteProject`, and `DeleteInstance` together. It is
+`backend/store/AGENTS.md`, updating that list, `DeleteProject`, and `DeleteInstance` together. It is
a direct child of `project` with no descendants, and every table that can reference a hash sits
earlier, so it belongs immediately after `db` and before `project_webhook` — the same position as
the purge delete.
@@ -671,7 +671,7 @@ decision, plus the migration matrix and the lock-order pair:
abort-hazard guard (dangling blob, ghost project, bigint overflow, stale stamp, JSON null and
malformed array shapes).
- **Create versus purge** — the deterministic lock-order pair mandated by
- `backend/store/README.md`: `CreateSheets` concurrent with a purge of its project ends in a
+ `backend/store/AGENTS.md`: `CreateSheets` concurrent with a purge of its project ends in a
controlled NotFound, not a foreign-key error, in both lock-acquisition directions.
- **Gate confinement** — a static AST test asserts nothing under `backend/api/v1/` calls
`GetSheetFull`; the rest of the split is compiler-enforced by unexported store internals.
diff --git a/docs/design/v1-api-audit-2026-08.md b/docs/design/v1-api-audit-2026-08.md
index e09d6412d3..66c257cb11 100644
--- a/docs/design/v1-api-audit-2026-08.md
+++ b/docs/design/v1-api-audit-2026-08.md
@@ -12,7 +12,6 @@ noted. Fixed findings are removed and listed at the end.
|---|---|---|
| T15 | Rotating a leaked cloud credential can silently do nothing | HIGH |
| T13 | "Waiting for my approval" can show an empty page with a live Load More | HIGH |
-| T14 | Paging through issues across projects skips some and repeats others | HIGH |
| T18a | Test-environment rights can cancel a running production migration | MED |
| T12 | Anonymous callers can enumerate emails, relay mail, and read your LDAP config | MED |
| T16 | Four `BatchGet` RPCs behave four different ways when an item is missing | MED |
@@ -120,15 +119,6 @@ This is the default My Issues view, and there's no empty-page workaround on the
(Same shape as the `SearchProjects` bug that parked patch `03` fixes — also still unmerged.)
-### T14 · Paging issues across projects skips and repeats rows — HIGH
-
-Issue IDs restart from 1 in each project, but the cross-project list sorts by ID alone. Issues from
-different projects constantly share an ID, and tied rows can land in a different order on each query
-— so paging forward drops some issues entirely and shows others twice. My Issues always queries
-across all projects, so this is the common path, not an edge case.
-
-**Fix:** sort by `(project, id)`, which is the primary key. `store/issue.go:323`
-
### T16 · Four `BatchGet` RPCs, four behaviors — MED
Ask for five databases and get three back, with no way to tell which two are missing. Ask for five
@@ -239,6 +229,7 @@ constraints.
| T13 `SearchWorksheets` | [#21160](https://github.com/bytebase/bytebase/pull/21160) + [#21178](https://github.com/bytebase/bytebase/pull/21178) — visibility predicate pushed into SQL before `LIMIT` |
| T18 worksheet write/delete | [#21169](https://github.com/bytebase/bytebase/pull/21169) + [#21181](https://github.com/bytebase/bytebase/pull/21181) — per-verb permissions; SQL Editor Read User can no longer rewrite or delete |
| T9 | [#21189](https://github.com/bytebase/bytebase/pull/21189) (self-hosted audit rows) + [#21234](https://github.com/bytebase/bytebase/pull/21234) — one `login_attempt` table bounds password, email-code, and MFA guessing per identity on both deployments, replacing the audit-log counter and the per-code attempt column (which bypassed the resend cooldown). Accepted with it: no per-tenant failed-login record on Cloud, and lockout-as-denial-of-service — see [`login-attempt-lockout.md`](login-attempt-lockout.md) |
+| T14 | [#21267](https://github.com/bytebase/bytebase/pull/21267) — filed as issue paging; the sweep it prompted found the same defect across the class, so it was fixed as a class. Counting endpoints, **17 of the 22** offset-paginated v1 list RPCs were affected; counting the store functions behind them, **14 of 17**. The three already sorting on a total order were `ListQueryHistories` and `ListSavedQueries` (both from one commit, [#21203](https://github.com/bytebase/bytebase/pull/21203), that was never swept across the other lists) and `ListPlans`, which is total only because a mandatory `WHERE plan.project = ?` pins its scope column. Every store list now names tiebreak columns that are unique under its own scope — written into the SQL, and appended after the caller's keys at the six affected lists that accept an `order_by`. The three that were already total are left untouched. Nothing enforces this statically: an earlier revision routed all seventeen through a `buildStableOrderBy` helper so an AST test could require it, but review judged that ceremony and both were removed, so a new paginated list added without a tiebreak will not fail CI. Enforcement is step 4 of `docs/pre-pr-checklist.md` plus review, with `TestPaginationStabilityAcrossProjects` and `TestIssueCommentBatchKeepsInsertionOrder` covering the behavior against a real PostgreSQL. The rules, and the five traps that produced the class — `id` alone in a `(project, id)` table, `created_at` (the *transaction* timestamp, identical across a batch insert), a nullable column, a partial unique index, and an `order_by` that replaces the default ordering rather than adding to it — are in [`backend/store/AGENTS.md`](../../backend/store/AGENTS.md#pagination-ordering). One adjacent bug fixed with it: `ListDatabases`, `ListInstances` and `ListProjects` each threw away the whole clause, tiebreak included, the moment a caller passed `order_by` — which is what broke their paging. Accepted with them: offset paging still drifts under concurrent inserts and deletes (that needs keyset pagination and a page-token change). `ListIssueComment` needed a second fix: its `resource_id` tiebreak is a random UUID, which would have scrambled the activity feed of a multi-field `UpdateIssue`, so `CreateIssueComments` now offsets each row of a batch by its ordinal to keep `created_at` unique and in insertion order. Deliberately out of scope, and worth its own change: `issue.id` is a per-project counter, so ordering a cross-project list by it is not recency — seeded with a three-year-old project and one created today, the newest issue in the new project ranked 4962nd on the default list. Making `create_time` the cross-project default is a product decision. Also left alone: issue search still discards an explicit `order_by` outright when the caller supplied query text |
| T10 | [#21252](https://github.com/bytebase/bytebase/pull/21252) + [#21258](https://github.com/bytebase/bytebase/pull/21258) — password change and MFA lifecycle move off `UpdateUser` onto their own methods, each requiring a `CredentialProof`: current password, live OTP, recovery code, or a Cloud-only emailed re-auth code. Every proof claims a T9 login-attempt slot, so no proof channel is an unbounded guessing oracle, and a factor-touching method refuses the password while a live factor exists. Accepted with it: **the stolen access token still answers until it expires (≤1h)** — credential generation and the fenced transaction were cut or deferred, password change revokes only the account's web refresh tokens (best-effort, OAuth grants untouched), and an MFA change revokes nothing. What this closes is the credential being *spent* on its own replacement, not the session. Design, and the shipped-vs-designed delta: [`reauthenticate-credential-changes.md`](reauthenticate-credential-changes.md) |
**`AIService.Chat` — accepted, not fixed** (2026-08-18). `Chat` requires an authenticated workspace
diff --git a/docs/pre-pr-checklist.md b/docs/pre-pr-checklist.md
index 770dd1fec2..bebeb9428d 100644
--- a/docs/pre-pr-checklist.md
+++ b/docs/pre-pr-checklist.md
@@ -41,7 +41,9 @@ cause existing users, integrations, or deployments to fail after upgrading.
## 3. Composite-PK Query Safety
-**Skip if:** diff does not touch `backend/store/` or `backend/migrator/`.
+**Skip if:** diff does not touch `backend/store/`, `backend/migrator/`, or `backend/tests/`.
+The CEL-to-SQL filter builders live in `backend/store/`, so a filter change is in
+scope; the collision tests in `backend/tests/` read the metadata DB raw and are too.
Composite primary keys (e.g., `(project, id)`) mean that `id` alone is NOT unique.
Filtering by `id` without `project` causes cross-project data corruption — the exact
@@ -168,11 +170,33 @@ spots — they document what helpers exist and what guarantees they make.
Stale references don't break the build but they actively mislead future
contributors and AI agents that read these docs at session start.
-## 4. Transaction Lock Ordering
+## 4. Pagination Ordering
+
+**Skip if:** the diff does not add or modify a paginated list query in `backend/store/`.
+
+Every offset-paginated list must sort on a total order, or its pages skip and
+repeat rows. Nothing checks this statically — this step is the gate. Read the
+canonical
+[pagination ordering](../backend/store/AGENTS.md#pagination-ordering) rules, then
+for each paginated list in the diff:
+
+- Open `LATEST.sql` and confirm the tiebreak is a primary key or a **non-partial**
+ unique key, that it is `NOT NULL`, and that every column of a composite key is
+ named
+- Confirm no join in the query can duplicate a row, which would break the
+ tiebreak's uniqueness in the result even though it holds in the table
+- Confirm a caller-supplied `order_by` still leaves the tiebreak appended
+- `EXPLAIN` the new clause against the query's real predicate shape and add a
+ migration if the tiebreak pushed it off an index
+
+**STOP — do not proceed to PR creation if a tiebreak is not provably unique under
+the query's own scope.**
+
+## 5. Transaction Lock Ordering
**Skip if:** the diff does not add or modify a transaction in `backend/store/`.
-Read the canonical [store row-lock ordering](../backend/store/README.md#transaction-row-lock-ordering), then inspect every explicit and implicit lock in the changed transaction:
+Read the canonical [store row-lock ordering](../backend/store/AGENTS.md#transaction-row-lock-ordering), then inspect every explicit and implicit lock in the changed transaction:
- Transaction-scoped advisory locks are acquired before row locks
- Existing related rows are locked child-to-parent
@@ -201,7 +225,7 @@ SQLSTATE `40P01` is insufficient.
canonical order or lacks the required deterministic lock and lifecycle regression
tests.**
-## 5. Image Compatibility Window
+## 6. Image Compatibility Window
**Skip if:** diff does not touch server version metadata, actuator compatibility
metadata, or `bytebase-action` version/compatibility logic.
@@ -215,7 +239,7 @@ If the diff changes, narrows, or may break the compatibility window, call out
the policy change, compatibility impact, and validation plan in the PR
description.
-## 6. Lint and Format Gate
+## 7. Lint and Format Gate
**Skip if:** no code changes (docs-only PR).
@@ -239,7 +263,7 @@ pnpm --dir frontend type-check
buf lint proto
```
-## 7. Test Gate
+## 8. Test Gate
**Skip if:** no code changes.
@@ -248,7 +272,7 @@ buf lint proto
- For Go changes: `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
- For new migration files: update `TestLatestVersion` in `backend/migrator/migrator_test.go`
-## 8. SonarCloud Properties
+## 9. SonarCloud Properties
**Skip if:** no new files or directories added.
@@ -257,7 +281,7 @@ Update `.sonarcloud.properties` to reflect the latest file structure:
- `sonar.test.inclusions` for test file patterns (e.g., `**/*_test.go`)
- `sonar.cpd.exclusions` to skip copy-paste detection on test files
-## 9. Final Verification
+## 10. Final Verification
Before running `gh pr create`: