Skip to content

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

feat(store): add the review_run slot table and store proto for SQL Review V2

rebelice97f8c7d2a399
diff --git a/backend/generated-go/store/review_run.pb.go b/backend/generated-go/store/review_run.pb.go
new file mode 100644
index 0000000000..e8e85b0dcc
--- /dev/null
+++ b/backend/generated-go/store/review_run.pb.go
@@ -0,0 +1,232 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// protoc-gen-go v1.36.12
+// protoc (unknown)
+// source: store/review_run.proto
+
+package store
+
+import (
+ protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+ protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+ reflect "reflect"
+ sync "sync"
+ unsafe "unsafe"
+)
+
+const (
+ // Verify that this generated code is sufficiently up-to-date.
+ _ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+ // Verify that runtime/protoimpl is sufficiently up-to-date.
+ _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// Strictly 1:1 with the status CHECK constraint — no unpersisted values.
+type ReviewRun_Status int32
+
+const (
+ ReviewRun_STATUS_UNSPECIFIED ReviewRun_Status = 0
+ ReviewRun_AVAILABLE ReviewRun_Status = 1
+ ReviewRun_RUNNING ReviewRun_Status = 2
+ ReviewRun_DONE ReviewRun_Status = 3
+ ReviewRun_FAILED ReviewRun_Status = 4
+)
+
+// Enum value maps for ReviewRun_Status.
+var (
+ ReviewRun_Status_name = map[int32]string{
+ 0: "STATUS_UNSPECIFIED",
+ 1: "AVAILABLE",
+ 2: "RUNNING",
+ 3: "DONE",
+ 4: "FAILED",
+ }
+ ReviewRun_Status_value = map[string]int32{
+ "STATUS_UNSPECIFIED": 0,
+ "AVAILABLE": 1,
+ "RUNNING": 2,
+ "DONE": 3,
+ "FAILED": 4,
+ }
+)
+
+func (x ReviewRun_Status) Enum() *ReviewRun_Status {
+ p := new(ReviewRun_Status)
+ *p = x
+ return p
+}
+
+func (x ReviewRun_Status) String() string {
+ return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
+}
+
+func (ReviewRun_Status) Descriptor() protoreflect.EnumDescriptor {
+ return file_store_review_run_proto_enumTypes[0].Descriptor()
+}
+
+func (ReviewRun_Status) Type() protoreflect.EnumType {
+ return &file_store_review_run_proto_enumTypes[0]
+}
+
+func (x ReviewRun_Status) Number() protoreflect.EnumNumber {
+ return protoreflect.EnumNumber(x)
+}
+
+// Deprecated: Use ReviewRun_Status.Descriptor instead.
+func (ReviewRun_Status) EnumDescriptor() ([]byte, []int) {
+ return file_store_review_run_proto_rawDescGZIP(), []int{0, 0}
+}
+
+// ReviewRun is the status slot of one reviewer (rule engine or AI) on one
+// issue. Results live in issue comments; the run carries none.
+type ReviewRun struct {
+ state protoimpl.MessageState `protogen:"open.v1"`
+ unknownFields protoimpl.UnknownFields
+ sizeCache protoimpl.SizeCache
+}
+
+func (x *ReviewRun) Reset() {
+ *x = ReviewRun{}
+ mi := &file_store_review_run_proto_msgTypes[0]
+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+ ms.StoreMessageInfo(mi)
+}
+
+func (x *ReviewRun) String() string {
+ return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ReviewRun) ProtoMessage() {}
+
+func (x *ReviewRun) ProtoReflect() protoreflect.Message {
+ mi := &file_store_review_run_proto_msgTypes[0]
+ if x != nil {
+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+ if ms.LoadMessageInfo() == nil {
+ ms.StoreMessageInfo(mi)
+ }
+ return ms
+ }
+ return mi.MessageOf(x)
+}
+
+// Deprecated: Use ReviewRun.ProtoReflect.Descriptor instead.
+func (*ReviewRun) Descriptor() ([]byte, []int) {
+ return file_store_review_run_proto_rawDescGZIP(), []int{0}
+}
+
+type ReviewRunPayload struct {
+ state protoimpl.MessageState `protogen:"open.v1"`
+ // Fatal execution error for the FAILED status, e.g. "metadata not synced:
+ // instances/prod/databases/db1, db2, db3 (+497 more)". Written by the
+ // executor or by the reaper.
+ Error string `protobuf:"bytes,1,opt,name=error,proto3" json:"error,omitempty"`
+ unknownFields protoimpl.UnknownFields
+ sizeCache protoimpl.SizeCache
+}
+
+func (x *ReviewRunPayload) Reset() {
+ *x = ReviewRunPayload{}
+ mi := &file_store_review_run_proto_msgTypes[1]
+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+ ms.StoreMessageInfo(mi)
+}
+
+func (x *ReviewRunPayload) String() string {
+ return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ReviewRunPayload) ProtoMessage() {}
+
+func (x *ReviewRunPayload) ProtoReflect() protoreflect.Message {
+ mi := &file_store_review_run_proto_msgTypes[1]
+ if x != nil {
+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+ if ms.LoadMessageInfo() == nil {
+ ms.StoreMessageInfo(mi)
+ }
+ return ms
+ }
+ return mi.MessageOf(x)
+}
+
+// Deprecated: Use ReviewRunPayload.ProtoReflect.Descriptor instead.
+func (*ReviewRunPayload) Descriptor() ([]byte, []int) {
+ return file_store_review_run_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *ReviewRunPayload) GetError() string {
+ if x != nil {
+ return x.Error
+ }
+ return ""
+}
+
+var File_store_review_run_proto protoreflect.FileDescriptor
+
+const file_store_review_run_proto_rawDesc = "" +
+ "\n" +
+ "\x16store/review_run.proto\x12\x0ebytebase.store\"_\n" +
+ "\tReviewRun\"R\n" +
+ "\x06Status\x12\x16\n" +
+ "\x12STATUS_UNSPECIFIED\x10\x00\x12\r\n" +
+ "\tAVAILABLE\x10\x01\x12\v\n" +
+ "\aRUNNING\x10\x02\x12\b\n" +
+ "\x04DONE\x10\x03\x12\n" +
+ "\n" +
+ "\x06FAILED\x10\x04\"(\n" +
+ "\x10ReviewRunPayload\x12\x14\n" +
+ "\x05error\x18\x01 \x01(\tR\x05errorB\x91\x01\n" +
+ "\x12com.bytebase.storeB\x0eReviewRunProtoP\x01Z\x12generated-go/store\xa2\x02\x03BSX\xaa\x02\x0eBytebase.Store\xca\x02\x0eBytebase\\Store\xe2\x02\x1aBytebase\\Store\\GPBMetadata\xea\x02\x0fBytebase::Storeb\x06proto3"
+
+var (
+ file_store_review_run_proto_rawDescOnce sync.Once
+ file_store_review_run_proto_rawDescData []byte
+)
+
+func file_store_review_run_proto_rawDescGZIP() []byte {
+ file_store_review_run_proto_rawDescOnce.Do(func() {
+ file_store_review_run_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_store_review_run_proto_rawDesc), len(file_store_review_run_proto_rawDesc)))
+ })
+ return file_store_review_run_proto_rawDescData
+}
+
+var file_store_review_run_proto_enumTypes = make([]protoimpl.EnumInfo, 1)
+var file_store_review_run_proto_msgTypes = make([]protoimpl.MessageInfo, 2)
+var file_store_review_run_proto_goTypes = []any{
+ (ReviewRun_Status)(0), // 0: bytebase.store.ReviewRun.Status
+ (*ReviewRun)(nil), // 1: bytebase.store.ReviewRun
+ (*ReviewRunPayload)(nil), // 2: bytebase.store.ReviewRunPayload
+}
+var file_store_review_run_proto_depIdxs = []int32{
+ 0, // [0:0] is the sub-list for method output_type
+ 0, // [0:0] is the sub-list for method input_type
+ 0, // [0:0] is the sub-list for extension type_name
+ 0, // [0:0] is the sub-list for extension extendee
+ 0, // [0:0] is the sub-list for field type_name
+}
+
+func init() { file_store_review_run_proto_init() }
+func file_store_review_run_proto_init() {
+ if File_store_review_run_proto != nil {
+ return
+ }
+ type x struct{}
+ out := protoimpl.TypeBuilder{
+ File: protoimpl.DescBuilder{
+ GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+ RawDescriptor: unsafe.Slice(unsafe.StringData(file_store_review_run_proto_rawDesc), len(file_store_review_run_proto_rawDesc)),
+ NumEnums: 1,
+ NumMessages: 2,
+ NumExtensions: 0,
+ NumServices: 0,
+ },
+ GoTypes: file_store_review_run_proto_goTypes,
+ DependencyIndexes: file_store_review_run_proto_depIdxs,
+ EnumInfos: file_store_review_run_proto_enumTypes,
+ MessageInfos: file_store_review_run_proto_msgTypes,
+ }.Build()
+ File_store_review_run_proto = out.File
+ file_store_review_run_proto_goTypes = nil
+ file_store_review_run_proto_depIdxs = nil
+}
diff --git a/backend/generated-go/store/review_run_equal.pb.go b/backend/generated-go/store/review_run_equal.pb.go
new file mode 100644
index 0000000000..0745d4674b
--- /dev/null
+++ b/backend/generated-go/store/review_run_equal.pb.go
@@ -0,0 +1,27 @@
+// Code generated by protoc-gen-equal-go. DO NOT EDIT.
+// source: store/review_run.proto
+
+package store
+
+func (x *ReviewRun) Equal(y *ReviewRun) bool {
+ if x == y {
+ return true
+ }
+ if x == nil || y == nil {
+ return x == nil && y == nil
+ }
+ return true
+}
+
+func (x *ReviewRunPayload) Equal(y *ReviewRunPayload) bool {
+ if x == y {
+ return true
+ }
+ if x == nil || y == nil {
+ return x == nil && y == nil
+ }
+ if x.Error != y.Error {
+ return false
+ }
+ return true
+}
diff --git a/backend/migrator/migration/3.23/0000##review_run.sql b/backend/migrator/migration/3.23/0000##review_run.sql
new file mode 100644
index 0000000000..0431a5e6e4
--- /dev/null
+++ b/backend/migrator/migration/3.23/0000##review_run.sql
@@ -0,0 +1,36 @@
+-- SQL Review V2 run status slot: one row per (issue, reviewer type), reset in
+-- place on re-run (created_at = now() on reset — the row is the current run,
+-- not the slot's history). Results live in issue comments; the run carries
+-- none. No standalone id on purpose: nothing may durably reference a run.
+CREATE TABLE review_run (
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ project text NOT NULL REFERENCES project(resource_id),
+ issue_id bigint NOT NULL,
+ -- Reviewer type: 'RULE' (standard rules) or 'GUIDELINE' (natural-language
+ -- guidelines, performed by AI). No CHECK on purpose: the reviewer-id space
+ -- is open.
+ type text NOT NULL,
+ -- Attempt number of the current run, 0-based like task_run.attempt.
+ -- Bumped on every slot reset (issue created / SQL updated / manual
+ -- re-run); it counts triggers, not completed executions. The completion
+ -- transaction is fenced on it, so a superseded execution posts zero
+ -- comments.
+ attempt integer NOT NULL DEFAULT 0,
+ status text NOT NULL CHECK (status IN ('AVAILABLE', 'RUNNING', 'DONE', 'FAILED')),
+ replica_id text,
+ -- Stored as ReviewRunPayload (proto/store/store/review_run.proto)
+ payload jsonb NOT NULL DEFAULT '{}',
+ PRIMARY KEY (project, issue_id, type),
+ FOREIGN KEY (project, issue_id) REFERENCES issue(project, id)
+);
+
+-- Most rows are terminal; schedulers scan only active rows
+-- (cf. idx_task_run_active_status_id).
+CREATE INDEX idx_review_run_active_status ON review_run(status)
+ WHERE status IN ('AVAILABLE', 'RUNNING');
+
+-- For the heartbeat reaper's dead-replica lookup
+-- (cf. idx_task_run_running_replica).
+CREATE INDEX idx_review_run_running_replica ON review_run(replica_id)
+ WHERE status = 'RUNNING' AND replica_id IS NOT NULL;
diff --git a/backend/migrator/migration/LATEST.sql b/backend/migrator/migration/LATEST.sql
index b1f677fa19..f0ef1f8b0e 100644
--- a/backend/migrator/migration/LATEST.sql
+++ b/backend/migrator/migration/LATEST.sql
@@ -371,6 +371,43 @@ CREATE TABLE issue_comment (
CREATE INDEX idx_issue_comment_issue_id ON issue_comment(project, issue_id);
CREATE UNIQUE INDEX idx_issue_comment_unique_resource_id ON issue_comment(resource_id);
+-- SQL Review V2 run status slot: one row per (issue, reviewer type), reset in
+-- place on re-run (created_at = now() on reset — the row is the current run,
+-- not the slot's history). Results live in issue comments; the run carries
+-- none. No standalone id on purpose: nothing may durably reference a run.
+CREATE TABLE review_run (
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ project text NOT NULL REFERENCES project(resource_id),
+ issue_id bigint NOT NULL,
+ -- Reviewer type: 'RULE' (standard rules) or 'GUIDELINE' (natural-language
+ -- guidelines, performed by AI). No CHECK on purpose: the reviewer-id space
+ -- is open.
+ type text NOT NULL,
+ -- Attempt number of the current run, 0-based like task_run.attempt.
+ -- Bumped on every slot reset (issue created / SQL updated / manual
+ -- re-run); it counts triggers, not completed executions. The completion
+ -- transaction is fenced on it, so a superseded execution posts zero
+ -- comments.
+ attempt integer NOT NULL DEFAULT 0,
+ status text NOT NULL CHECK (status IN ('AVAILABLE', 'RUNNING', 'DONE', 'FAILED')),
+ replica_id text,
+ -- Stored as ReviewRunPayload (proto/store/store/review_run.proto)
+ payload jsonb NOT NULL DEFAULT '{}',
+ PRIMARY KEY (project, issue_id, type),
+ FOREIGN KEY (project, issue_id) REFERENCES issue(project, id)
+);
+
+-- Most rows are terminal; schedulers scan only active rows
+-- (cf. idx_task_run_active_status_id).
+CREATE INDEX idx_review_run_active_status ON review_run(status)
+ WHERE status IN ('AVAILABLE', 'RUNNING');
+
+-- For the heartbeat reaper's dead-replica lookup
+-- (cf. idx_task_run_running_replica).
+CREATE INDEX idx_review_run_running_replica ON review_run(replica_id)
+ WHERE status = 'RUNNING' AND replica_id IS NOT NULL;
+
-- saved_query table stores SQL Editor saved queries.
CREATE TABLE saved_query (
-- global unique
diff --git a/backend/migrator/migrator_test.go b/backend/migrator/migrator_test.go
index ef759c26e8..be1b6f4e7d 100644
--- a/backend/migrator/migrator_test.go
+++ b/backend/migrator/migrator_test.go
@@ -21,8 +21,8 @@ import (
func TestLatestVersion(t *testing.T) {
files, err := getSortedVersionedFiles()
require.NoError(t, err)
- require.Equal(t, semver.MustParse("3.22.14"), *files[len(files)-1].version)
- require.Equal(t, "migration/3.22/0014##token_row_created_at.sql", files[len(files)-1].path)
+ require.Equal(t, semver.MustParse("3.23.0"), *files[len(files)-1].version)
+ require.Equal(t, "migration/3.23/0000##review_run.sql", files[len(files)-1].path)
}
func TestVersionUnique(t *testing.T) {
diff --git a/backend/store/README.md b/backend/store/README.md
index 811a1f9032..279c0935ff 100644
--- a/backend/store/README.md
+++ b/backend/store/README.md
@@ -9,6 +9,7 @@ PostgreSQL holds row locks until a transaction ends. Transactions that acquire t
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`
@@ -44,7 +45,7 @@ Transactions spanning project- or instance-owned sibling branches follow this ca
```text
query_history -> policy -> saved_query_organizer -> saved_query
--> issue_comment -> issue -> plan_webhook_delivery -> plan_check_run
+-> 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
diff --git a/backend/store/project.go b/backend/store/project.go
index a4eea576a1..0ed6cee7bc 100644
--- a/backend/store/project.go
+++ b/backend/store/project.go
@@ -553,6 +553,16 @@ func (s *Store) DeleteProject(ctx context.Context, workspace string, resourceID
return errors.Wrapf(err, "failed to delete issue_comment for project %s", resourceID)
}
+ // Delete review_run entries for issues in this project
+ q = qb.Q().Space("DELETE FROM review_run WHERE project = ?", resourceID)
+ sql, args, err = q.ToSQL()
+ if err != nil {
+ return errors.Wrap(err, "failed to build review_run delete query")
+ }
+ if _, err := tx.ExecContext(ctx, sql, args...); err != nil {
+ return errors.Wrapf(err, "failed to delete review_run for project %s", resourceID)
+ }
+
// Delete issues associated with this project
q = qb.Q().Space("DELETE FROM issue WHERE project = ?", resourceID)
sql, args, err = q.ToSQL()
diff --git a/backend/tests/cross_project_delete_test.go b/backend/tests/cross_project_delete_test.go
index 20a8d59777..162ef03c49 100644
--- a/backend/tests/cross_project_delete_test.go
+++ b/backend/tests/cross_project_delete_test.go
@@ -18,7 +18,8 @@ import (
// Scope: covers plan, issue, task_run, plan_check_run isolation via the
// gRPC snapshot. Tables NOT covered here (currently): task, task_run_log,
// plan_webhook_delivery. Add targeted tests if a future change touches
-// their DELETE paths.
+// their DELETE paths. review_run is covered by the targeted purge test in
+// review_run_collision_test.go.
func TestCollisionDeleteProjectCascade(t *testing.T) {
t.Parallel()
a := require.New(t)
diff --git a/backend/tests/review_run_collision_test.go b/backend/tests/review_run_collision_test.go
new file mode 100644
index 0000000000..8beba710a0
--- /dev/null
+++ b/backend/tests/review_run_collision_test.go
@@ -0,0 +1,123 @@
+package tests
+
+import (
+ "context"
+ "database/sql"
+ "testing"
+ "time"
+
+ "connectrpc.com/connect"
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common"
+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
+)
+
+// reviewRun is one row of the review_run table, which has no public gRPC
+// read API yet (the v1 surface lands with the rest of SQL Review V2). This
+// suite reads it with a table-specific direct DB read, the same allowance
+// listPlanWebhookDeliveries uses for tables without a public read API.
+type reviewRun struct {
+ IssueID int64
+ Type string
+ Attempt int64
+ Status string
+ Payload string
+}
+
+// listReviewRuns reads every review_run row for the project directly from
+// the test metadata database, ordered by primary key.
+func listReviewRuns(ctx context.Context, t *testing.T, ctl *controller, projectID string) []*reviewRun {
+ t.Helper()
+ a := require.New(t)
+ db, err := sql.Open("pgx", ctl.profile.PgURL)
+ a.NoError(err, "open metadata DB")
+ defer db.Close()
+
+ rows, err := db.QueryContext(ctx, `
+ SELECT issue_id, type, attempt, status, payload::text
+ FROM review_run
+ WHERE project = $1
+ ORDER BY issue_id, type
+ `, projectID)
+ a.NoError(err, "query review_run for project %s", projectID)
+ defer rows.Close()
+
+ var out []*reviewRun
+ for rows.Next() {
+ var r reviewRun
+ a.NoError(rows.Scan(&r.IssueID, &r.Type, &r.Attempt, &r.Status, &r.Payload))
+ out = append(out, &r)
+ }
+ a.NoError(rows.Err())
+ return out
+}
+
+// seedReviewRun inserts one review_run row directly into the metadata
+// database. review_run has no store writer yet — the trigger/claim/complete
+// methods land with the SQL Review V2 execution work — so the purge
+// collision test seeds rows raw to make the DELETE path observable. Move
+// seeding to the product flow once real writers exist.
+func seedReviewRun(ctx context.Context, t *testing.T, ctl *controller, projectID string, issueID int64, runType string, attempt int64, status string) {
+ t.Helper()
+ a := require.New(t)
+ db, err := sql.Open("pgx", ctl.profile.PgURL)
+ a.NoError(err, "open metadata DB")
+ defer db.Close()
+
+ _, err = db.ExecContext(ctx, `
+ INSERT INTO review_run (project, issue_id, type, attempt, status)
+ VALUES ($1, $2, $3, $4, $5)
+ `, projectID, issueID, runType, attempt, status)
+ a.NoError(err, "seed review_run (%s, %d, %s)", projectID, issueID, runType)
+}
+
+// TestCollision_ReviewRunProjectPurge verifies that purging project A
+// deletes A's review_run rows and leaves project B's rows untouched when
+// both projects hold rows under colliding (issue_id, type) keys.
+func TestCollision_ReviewRunProjectPurge(t *testing.T) {
+ t.Parallel()
+ a := require.New(t)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+ defer cancel()
+ ctl := &controller{}
+ ctx, err := ctl.StartServerWithExternalPg(ctx)
+ a.NoError(err)
+ defer ctl.Close(ctx)
+
+ fixture := setupCollidingProjects(ctx, t, ctl)
+
+ projectAID, issueAUID, err := common.GetProjectIDIssueUID(fixture.IssueA.Name)
+ a.NoError(err)
+ projectBID, issueBUID, err := common.GetProjectIDIssueUID(fixture.IssueB.Name)
+ a.NoError(err)
+ // The fixture's per-project id allocation makes the two issues collide;
+ // assert it so the test cannot silently lose its collision.
+ a.Equal(issueAUID, issueBUID, "fixture issue ids should collide")
+
+ seedReviewRun(ctx, t, ctl, projectAID, issueAUID, "RULE", 2, "DONE")
+ seedReviewRun(ctx, t, ctl, projectAID, issueAUID, "GUIDELINE", 0, "AVAILABLE")
+ seedReviewRun(ctx, t, ctl, projectBID, issueBUID, "RULE", 5, "FAILED")
+ seedReviewRun(ctx, t, ctl, projectBID, issueBUID, "GUIDELINE", 1, "RUNNING")
+
+ // Positive preconditions: an empty list would make the isolation
+ // assertions below vacuously true.
+ beforeA := listReviewRuns(ctx, t, ctl, projectAID)
+ beforeB := listReviewRuns(ctx, t, ctl, projectBID)
+ a.Greater(len(beforeA), 0, "project A should have review_run rows before purge")
+ a.Greater(len(beforeB), 0, "project B should have review_run rows before purge")
+
+ // Project purge is an explicit archive-then-purge lifecycle.
+ _, err = ctl.projectServiceClient.DeleteProject(ctx,
+ connect.NewRequest(&v1pb.DeleteProjectRequest{Name: fixture.ProjectA.Name}))
+ a.NoError(err)
+ _, err = ctl.projectServiceClient.DeleteProject(ctx,
+ connect.NewRequest(&v1pb.DeleteProjectRequest{
+ Name: fixture.ProjectA.Name,
+ Purge: true,
+ }))
+ a.NoError(err)
+
+ a.Empty(listReviewRuns(ctx, t, ctl, projectAID), "project A review_run rows should be purged")
+ a.Equal(beforeB, listReviewRuns(ctx, t, ctl, projectBID), "project B review_run rows should be untouched")
+}
diff --git a/docs/pre-pr-checklist.md b/docs/pre-pr-checklist.md
index 2e1e25c628..770dd1fec2 100644
--- a/docs/pre-pr-checklist.md
+++ b/docs/pre-pr-checklist.md
@@ -50,12 +50,13 @@ bug class behind BYT-9259 (customer data loss from silent task re-execution).
### Step 3a: Identify composite-PK tables in the diff
Read `backend/migrator/migration/LATEST.sql` and find every table with a multi-column
-`PRIMARY KEY`. The known project-scoped set (as of April 2026) includes:
+`PRIMARY KEY`. The known project-scoped set (as of August 2026) includes:
- `plan (project, id)`
- `plan_check_run (project, id)`
- `plan_webhook_delivery (project, plan_id)`
- `issue (project, id)`
+- `review_run (project, issue_id, type)`
- `task (project, id)`
- `task_run (project, id)`
- `db_group (project, resource_id)`
diff --git a/proto/gen/grpc-doc/store/README.md b/proto/gen/grpc-doc/store/README.md
index 369284e4e7..ceab63c542 100644
--- a/proto/gen/grpc-doc/store/README.md
+++ b/proto/gen/grpc-doc/store/README.md
@@ -238,6 +238,12 @@
- [SQLReviewRule.Level](#bytebase-store-SQLReviewRule-Level)
- [SQLReviewRule.Type](#bytebase-store-SQLReviewRule-Type)
+- [store/review_run.proto](#store_review_run-proto)
+ - [ReviewRun](#bytebase-store-ReviewRun)
+ - [ReviewRunPayload](#bytebase-store-ReviewRunPayload)
+
+ - [ReviewRun.Status](#bytebase-store-ReviewRun-Status)
+
- [store/revision.proto](#store_revision-proto)
- [RevisionPayload](#bytebase-store-RevisionPayload)
@@ -4097,6 +4103,63 @@ The severity level for SQL review rules.
+<a name="store_review_run-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## store/review_run.proto
+
+
+
+<a name="bytebase-store-ReviewRun"></a>
+
+### ReviewRun
+ReviewRun is the status slot of one reviewer (rule engine or AI) on one
+issue. Results live in issue comments; the run carries none.
+
+
+
+
+
+
+<a name="bytebase-store-ReviewRunPayload"></a>
+
+### ReviewRunPayload
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| error | [string](#string) | | Fatal execution error for the FAILED status, e.g. &#34;metadata not synced: instances/prod/databases/db1, db2, db3 (&#43;497 more)&#34;. Written by the executor or by the reaper. |
+
+
+
+
+
+
+
+
+<a name="bytebase-store-ReviewRun-Status"></a>
+
+### ReviewRun.Status
+Strictly 1:1 with the status CHECK constraint — no unpersisted values.
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| STATUS_UNSPECIFIED | 0 | |
+| AVAILABLE | 1 | |
+| RUNNING | 2 | |
+| DONE | 3 | |
+| FAILED | 4 | |
+
+
+
+
+
+
+
+
+
+
<a name="store_revision-proto"></a>
<p align="right"><a href="#top">Top</a></p>
diff --git a/proto/gen/grpc-doc/store/index.html b/proto/gen/grpc-doc/store/index.html
index 7577b11da4..bdd30e5ae7 100644
--- a/proto/gen/grpc-doc/store/index.html
+++ b/proto/gen/grpc-doc/store/index.html
@@ -177,15 +177,15 @@
<li>
<a href="#store%2faccess_grant.proto">store/access_grant.proto</a>
<ul>
-
+
<li>
<a href="#bytebase.store.AccessGrant"><span class="badge">M</span>AccessGrant</a>
</li>
-
+
<li>
<a href="#bytebase.store.AccessGrantPayload"><span class="badge">M</span>AccessGrantPayload</a>
</li>
-
+
<li>
<a href="#bytebase.store.AccessGrant.Status"><span class="badge">E</span>AccessGrant.Status</a>
@@ -1124,6 +1124,29 @@
</li>
+ <li>
+ <a href="#store%2freview_run.proto">store/review_run.proto</a>
+ <ul>
+
+ <li>
+ <a href="#bytebase.store.ReviewRun"><span class="badge">M</span>ReviewRun</a>
+ </li>
+
+ <li>
+ <a href="#bytebase.store.ReviewRunPayload"><span class="badge">M</span>ReviewRunPayload</a>
+ </li>
+
+
+ <li>
+ <a href="#bytebase.store.ReviewRun.Status"><span class="badge">E</span>ReviewRun.Status</a>
+ </li>
+
+
+
+ </ul>
+ </li>
+
+
<li>
<a href="#store%2frevision.proto">store/revision.proto</a>
<ul>
@@ -1693,7 +1716,7 @@
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
-
+
<tr>
<td>issue_id</td>
<td><a href="#int64">int64</a></td>
@@ -11672,6 +11695,94 @@ IM integration setting should be set for this function to work. </p></td>
+ <div class="file-heading">
+ <h2 id="store/review_run.proto">store/review_run.proto</h2><a href="#title">Top</a>
+ </div>
+ <p></p>
+
+
+ <h3 id="bytebase.store.ReviewRun">ReviewRun</h3>
+ <p>ReviewRun is the status slot of one reviewer (rule engine or AI) on one</p><p>issue. Results live in issue comments; the run carries none.</p>
+
+
+
+
+
+ <h3 id="bytebase.store.ReviewRunPayload">ReviewRunPayload</h3>
+ <p></p>
+
+
+ <table class="field-table">
+ <thead>
+ <tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
+ </thead>
+ <tbody>
+
+ <tr>
+ <td>error</td>
+ <td><a href="#string">string</a></td>
+ <td></td>
+ <td><p>Fatal execution error for the FAILED status, e.g. &#34;metadata not synced:
+instances/prod/databases/db1, db2, db3 (&#43;497 more)&#34;. Written by the
+executor or by the reaper. </p></td>
+ </tr>
+
+ </tbody>
+ </table>
+
+
+
+
+
+
+
+ <h3 id="bytebase.store.ReviewRun.Status">ReviewRun.Status</h3>
+ <p>Strictly 1:1 with the status CHECK constraint — no unpersisted values.</p>
+ <table class="enum-table">
+ <thead>
+ <tr><td>Name</td><td>Number</td><td>Description</td></tr>
+ </thead>
+ <tbody>
+
+ <tr>
+ <td>STATUS_UNSPECIFIED</td>
+ <td>0</td>
+ <td><p></p></td>
+ </tr>
+
+ <tr>
+ <td>AVAILABLE</td>
+ <td>1</td>
+ <td><p></p></td>
+ </tr>
+
+ <tr>
+ <td>RUNNING</td>
+ <td>2</td>
+ <td><p></p></td>
+ </tr>
+
+ <tr>
+ <td>DONE</td>
+ <td>3</td>
+ <td><p></p></td>
+ </tr>
+
+ <tr>
+ <td>FAILED</td>
+ <td>4</td>
+ <td><p></p></td>
+ </tr>
+
+ </tbody>
+ </table>
+
+
+
+
+
+
+
<div class="file-heading">
<h2 id="store/revision.proto">store/revision.proto</h2><a href="#title">Top</a>
</div>
@@ -11892,7 +12003,7 @@ unreadable and the revision carries no sheet name. </p></td>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
-
+
<tr>
<td>instance_id</td>
<td><a href="#string">string</a></td>
@@ -11941,7 +12052,7 @@ unreadable and the revision carries no sheet name. </p></td>
<td>optional</td>
<td><p> </p></td>
</tr>
-
+
</tbody>
</table>
@@ -15846,3 +15957,4 @@ Used to auto-select workspace on next login instead of requiring a workspace pic
</table>
</body>
</html>
+
diff --git a/proto/store/store/review_run.proto b/proto/store/store/review_run.proto
new file mode 100644
index 0000000000..2e303a02df
--- /dev/null
+++ b/proto/store/store/review_run.proto
@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package bytebase.store;
+
+option go_package = "generated-go/store";
+
+// ReviewRun is the status slot of one reviewer (rule engine or AI) on one
+// issue. Results live in issue comments; the run carries none.
+message ReviewRun {
+ // Strictly 1:1 with the status CHECK constraint — no unpersisted values.
+ enum Status {
+ STATUS_UNSPECIFIED = 0;
+ AVAILABLE = 1;
+ RUNNING = 2;
+ DONE = 3;
+ FAILED = 4;
+ }
+}
+
+message ReviewRunPayload {
+ // Fatal execution error for the FAILED status, e.g. "metadata not synced:
+ // instances/prod/databases/db1, db2, db3 (+497 more)". Written by the
+ // executor or by the reaper.
+ string error = 1;
+}