Skip to content

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

feat(plan): filter plans by release and task status (#21635)

boojack9f527dd1489c
diff --git a/backend/api/mcp/gen/openapi.yaml b/backend/api/mcp/gen/openapi.yaml
index 0a88f2aede..324a33a48e 100644
--- a/backend/api/mcp/gen/openapi.yaml
+++ b/backend/api/mcp/gen/openapi.yaml
@@ -16073,6 +16073,9 @@ components:
- title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match.
- spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config".
- state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".
+ - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false".
+ - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator.
+ - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
For example:
creator == "users/[email protected]" && create_time >= "2025-01-02T15:04:05Z07:00"
@@ -16080,6 +16083,8 @@ components:
title.contains("database migration")
spec_type == "change_database_config"
state == "ACTIVE"
+ has_release == true && task_status in ["FAILED", "RUNNING"]
+ release == "projects/my-project/releases/release_20260115-RC00"
title: ListPlansRequest
required:
- parent
diff --git a/backend/generated-go/v1/plan_service.pb.go b/backend/generated-go/v1/plan_service.pb.go
index 510fc9b560..8a050e02f8 100644
--- a/backend/generated-go/v1/plan_service.pb.go
+++ b/backend/generated-go/v1/plan_service.pb.go
@@ -205,6 +205,9 @@ type ListPlansRequest struct {
// - title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match.
// - spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config".
// - state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".
+ // - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false".
+ // - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator.
+ // - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
//
// For example:
// creator == "users/[email protected]" && create_time >= "2025-01-02T15:04:05Z07:00"
@@ -212,6 +215,8 @@ type ListPlansRequest struct {
// title.contains("database migration")
// spec_type == "change_database_config"
// state == "ACTIVE"
+ // has_release == true && task_status in ["FAILED", "RUNNING"]
+ // release == "projects/my-project/releases/release_20260115-RC00"
Filter string `protobuf:"bytes,4,opt,name=filter,proto3" json:"filter,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
diff --git a/backend/store/plan.go b/backend/store/plan.go
index c836f80dae..5283e7ce4f 100644
--- a/backend/store/plan.go
+++ b/backend/store/plan.go
@@ -242,6 +242,11 @@ func (s *Store) ListPlans(ctx context.Context, find *FindPlanMessage) ([]*PlanMe
return plans, nil
}
+// planReleaseSpecQuery selects the plan's change database specs that reference a release.
+func planReleaseSpecQuery() *qb.Query {
+ return qb.Q().Space("SELECT 1 FROM jsonb_array_elements(plan.config->'specs') AS spec WHERE NULLIF(spec->'changeDatabaseConfig'->>'release', '') IS NOT NULL")
+}
+
// GetListPlanFilter parses a CEL filter expression into a query builder query for listing plans.
func GetListPlanFilter(filter string) (*qb.Query, error) {
if filter == "" {
@@ -290,6 +295,24 @@ func GetListPlanFilter(filter string) (*qb.Query, error) {
return qb.Q().Space("plan.config->>'hasRollout' = ?", "true"), nil
case "title":
return qb.Q().Space("plan.name = ?", value), nil
+ case "has_release":
+ hasRelease, ok := value.(bool)
+ if !ok {
+ return nil, errors.Errorf(`"has_release" should be bool`)
+ }
+ if hasRelease {
+ return qb.Q().Space("EXISTS (?)", planReleaseSpecQuery()), nil
+ }
+ return qb.Q().Space("NOT EXISTS (?)", planReleaseSpecQuery()), nil
+ case "release":
+ release, ok := value.(string)
+ if !ok {
+ return nil, errors.Errorf("release value must be a string")
+ }
+ if _, _, err := common.GetProjectReleaseID(release); err != nil {
+ return nil, errors.Wrapf(err, "invalid release %q", release)
+ }
+ return qb.Q().Space("EXISTS (SELECT 1 FROM jsonb_array_elements(plan.config->'specs') AS spec WHERE spec->'changeDatabaseConfig'->>'release' = ?)", release), nil
case "spec_type":
specType, ok := value.(string)
if !ok {
@@ -322,6 +345,36 @@ func GetListPlanFilter(filter string) (*qb.Query, error) {
default:
return nil, errors.Errorf("unsupported variable %q", variable)
}
+ case celoperators.In:
+ variable, _ := getVariableAndValueFromExpr(expr)
+ if variable != "task_status" {
+ return nil, errors.Errorf(`"in" is only supported for "task_status", but found %q`, variable)
+ }
+ // Read the list from the AST: getVariableAndValueFromExpr drops non-literal elements.
+ args := expr.AsCall().Args()
+ if len(args) != 2 || args[1].Kind() != celast.ListKind {
+ return nil, errors.Errorf("invalid list value for filter %v", variable)
+ }
+ elements := args[1].AsList().Elements()
+ if len(elements) == 0 {
+ return nil, errors.Errorf("empty list value for filter %v", variable)
+ }
+ var statuses []string
+ for _, element := range elements {
+ if element.Kind() != celast.LiteralKind {
+ return nil, errors.Errorf("task_status value must be a string")
+ }
+ status, ok := element.AsLiteral().Value().(string)
+ if !ok {
+ return nil, errors.Errorf("task_status value must be a string")
+ }
+ if v, ok := v1pb.Task_Status_value[status]; !ok || v1pb.Task_Status(v) == v1pb.Task_STATUS_UNSPECIFIED {
+ return nil, errors.Errorf("invalid task_status value: %s", status)
+ }
+ statuses = append(statuses, status)
+ }
+ tasks := taskStatusQuery(qb.Q().Space("task.project = plan.project AND task.plan_id = plan.id"))
+ return qb.Q().Space("EXISTS (SELECT 1 FROM (?) AS t WHERE t.status = ANY(?))", tasks, statuses), nil
case celoperators.GreaterEquals, celoperators.LessEquals:
variable, rawValue := getVariableAndValueFromExpr(expr)
value, ok := rawValue.(string)
diff --git a/backend/store/plan_filter_test.go b/backend/store/plan_filter_test.go
index 87edf20d25..3e4a4052f1 100644
--- a/backend/store/plan_filter_test.go
+++ b/backend/store/plan_filter_test.go
@@ -1,6 +1,7 @@
package store
import (
+ "strings"
"testing"
"time"
@@ -84,6 +85,78 @@ func TestGetListPlanFilter(t *testing.T) {
wantErr: true,
errContains: "invalid spec_type value",
},
+ {
+ name: "has_release filter - true",
+ filter: `has_release == true`,
+ wantSQL: "(EXISTS (SELECT 1 FROM jsonb_array_elements(plan.config->'specs') AS spec WHERE NULLIF(spec->'changeDatabaseConfig'->>'release', '') IS NOT NULL))",
+ wantArgs: []any{},
+ },
+ {
+ name: "has_release filter - false",
+ filter: `has_release == false`,
+ wantSQL: "(NOT EXISTS (SELECT 1 FROM jsonb_array_elements(plan.config->'specs') AS spec WHERE NULLIF(spec->'changeDatabaseConfig'->>'release', '') IS NOT NULL))",
+ wantArgs: []any{},
+ },
+ {
+ name: "has_release with non-bool value",
+ filter: `has_release == "true"`,
+ wantErr: true,
+ errContains: `"has_release" should be bool`,
+ },
+ {
+ name: "release filter",
+ filter: `release == "projects/p1/releases/release_20261022-RC01"`,
+ wantSQL: "(EXISTS (SELECT 1 FROM jsonb_array_elements(plan.config->'specs') AS spec WHERE spec->'changeDatabaseConfig'->>'release' = $1))",
+ wantArgs: []any{"projects/p1/releases/release_20261022-RC01"},
+ },
+ {
+ name: "release filter with a non-release name",
+ filter: `release == "release_20261022-RC01"`,
+ wantErr: true,
+ errContains: "invalid release",
+ },
+ {
+ name: "task_status with an unknown value",
+ filter: `task_status in ["BROKEN"]`,
+ wantErr: true,
+ errContains: "invalid task_status value: BROKEN",
+ },
+ {
+ name: "task_status with the unspecified value",
+ filter: `task_status in ["STATUS_UNSPECIFIED"]`,
+ wantErr: true,
+ errContains: "invalid task_status value",
+ },
+ {
+ name: "task_status with a non-literal entry",
+ filter: `task_status in ["FAILED", typo]`,
+ wantErr: true,
+ errContains: "task_status value must be a string",
+ },
+ {
+ name: "task_status with a non-string entry",
+ filter: `task_status in ["FAILED", 1]`,
+ wantErr: true,
+ errContains: "task_status value must be a string",
+ },
+ {
+ name: "task_status with a non-list value",
+ filter: `task_status in "FAILED"`,
+ wantErr: true,
+ errContains: "invalid list value",
+ },
+ {
+ name: "task_status with an empty list",
+ filter: `task_status in []`,
+ wantErr: true,
+ errContains: "empty list value",
+ },
+ {
+ name: "in on an unsupported field",
+ filter: `title in ["a"]`,
+ wantErr: true,
+ errContains: `"in" is only supported for "task_status"`,
+ },
{
name: "state filter - ACTIVE",
filter: `state == "STATE_ACTIVE"`,
@@ -205,3 +278,15 @@ func TestGetListPlanFilter(t *testing.T) {
})
}
}
+
+func TestGetListPlanFilterTaskStatus(t *testing.T) {
+ t.Parallel()
+ q, err := GetListPlanFilter(`task_status in ["FAILED", "PENDING"] && has_rollout == true`)
+ require.NoError(t, err)
+ sql, args, err := q.ToSQL()
+ require.NoError(t, err)
+ require.True(t, strings.HasPrefix(sql, "((EXISTS (SELECT 1 FROM ("), sql)
+ require.Contains(t, sql, "WHERE task.project = plan.project AND task.plan_id = plan.id")
+ require.Contains(t, sql, "AS t WHERE t.status = ANY($5))")
+ require.Equal(t, []any{"SKIPPED", "NOT_STARTED", "AVAILABLE", "PENDING", []string{"FAILED", "PENDING"}, "true"}, args)
+}
diff --git a/backend/store/plan_list_filter_test.go b/backend/store/plan_list_filter_test.go
new file mode 100644
index 0000000000..a57aecfd4d
--- /dev/null
+++ b/backend/store/plan_list_filter_test.go
@@ -0,0 +1,93 @@
+package store_test
+
+import (
+ "context"
+ "fmt"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common/testcontainer"
+ "github.com/bytebase/bytebase/backend/store"
+)
+
+// TestListPlansSourceAndTaskStatusFilters runs the has_release, release, and
+// task_status filters against PostgreSQL. Both projects hold a plan 101 so a
+// filter that drops the project from its task join would match across them.
+func TestListPlansSourceAndTaskStatusFilters(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ db, s, _ := testcontainer.NewMetadataDB(t)
+ _, err := db.ExecContext(ctx, `
+ INSERT INTO workspace (resource_id) VALUES ('default');
+ INSERT INTO project (resource_id, workspace, name) VALUES
+ ('project-a', 'default', 'Project A'),
+ ('project-b', 'default', 'Project B');
+ INSERT INTO instance (resource_id, workspace) VALUES ('instance-a', 'default');
+ INSERT INTO plan (id, creator, project, name, description, config, deleted) VALUES
+ (101, '[email protected]', 'project-a', 'gitops failed', '', '{"hasRollout": true, "specs": [{"id": "s1", "changeDatabaseConfig": {"release": "projects/project-a/releases/r1"}}]}', FALSE),
+ (102, '[email protected]', 'project-a', 'gitops done', '', '{"hasRollout": true, "specs": [{"id": "s1", "changeDatabaseConfig": {"release": "projects/project-a/releases/r2"}}]}', FALSE),
+ (103, '[email protected]', 'project-a', 'gitops closed', '', '{"specs": [{"id": "s1", "changeDatabaseConfig": {"release": "projects/project-a/releases/r3"}}]}', TRUE),
+ (104, '[email protected]', 'project-a', 'clickops waiting', '', '{"hasRollout": true, "specs": [{"id": "s1", "changeDatabaseConfig": {"sheet": "projects/project-a/sheets/1"}}]}', FALSE),
+ (105, '[email protected]', 'project-a', 'clickops no rollout', '', '{"specs": [{"id": "s1", "changeDatabaseConfig": {"sheet": "projects/project-a/sheets/2", "release": ""}}]}', FALSE),
+ (101, '[email protected]', 'project-b', 'project b running', '', '{"hasRollout": true, "specs": [{"id": "s1", "changeDatabaseConfig": {"release": "projects/project-b/releases/r1"}}]}', FALSE);
+ INSERT INTO task (id, project, plan_id, instance, environment, type, payload) VALUES
+ (201, 'project-a', 101, 'instance-a', 'test', 'DATABASE_MIGRATE', '{}'),
+ (202, 'project-a', 101, 'instance-a', 'prod', 'DATABASE_MIGRATE', '{}'),
+ (203, 'project-a', 102, 'instance-a', 'test', 'DATABASE_MIGRATE', '{}'),
+ (204, 'project-a', 102, 'instance-a', 'prod', 'DATABASE_MIGRATE', '{"skipped": true}'),
+ (205, 'project-a', 104, 'instance-a', 'test', 'DATABASE_MIGRATE', '{}'),
+ (201, 'project-b', 101, 'instance-a', 'test', 'DATABASE_MIGRATE', '{}');
+ INSERT INTO task_run (id, project, task_id, attempt, status) VALUES
+ (301, 'project-a', 201, 0, 'DONE'),
+ (302, 'project-a', 202, 0, 'RUNNING'),
+ (303, 'project-a', 202, 1, 'FAILED'),
+ (304, 'project-a', 203, 0, 'DONE'),
+ (305, 'project-a', 205, 0, 'AVAILABLE'),
+ (301, 'project-b', 201, 0, 'RUNNING');
+ `)
+ require.NoError(t, err)
+
+ list := func(projectID, filter string) []string {
+ t.Helper()
+ filterQ, err := store.GetListPlanFilter(filter)
+ require.NoError(t, err)
+ plans, err := s.ListPlans(ctx, &store.FindPlanMessage{Workspace: "default", ProjectID: projectID, FilterQ: filterQ})
+ require.NoError(t, err)
+ var got []string
+ for _, plan := range plans {
+ got = append(got, plan.Name)
+ }
+ return got
+ }
+
+ require.ElementsMatch(t, []string{"gitops failed", "gitops done", "gitops closed"}, list("project-a", `has_release == true`))
+ require.ElementsMatch(t, []string{"clickops waiting", "clickops no rollout"}, list("project-a", `has_release == false`))
+
+ require.Equal(t, []string{"gitops done"}, list("project-a", `release == "projects/project-a/releases/r2"`))
+ require.Empty(t, list("project-a", `release == "projects/project-b/releases/r1"`))
+
+ // The latest run decides a task's status, so the earlier RUNNING run of task 202 does not match.
+ require.Equal(t, []string{"gitops failed"}, list("project-a", `task_status in ["FAILED"]`))
+ require.Empty(t, list("project-a", `task_status in ["RUNNING"]`))
+ require.Equal(t, []string{"clickops waiting"}, list("project-a", `task_status in ["PENDING"]`))
+ require.Equal(t, []string{"gitops done"}, list("project-a", `task_status in ["SKIPPED"]`))
+ require.ElementsMatch(t, []string{"gitops failed", "gitops done"}, list("project-a", `has_release == true && task_status in ["DONE"]`))
+
+ // Project B's plan 101 is running; project A's plan 101 is not.
+ require.Equal(t, []string{"project b running"}, list("project-b", `task_status in ["RUNNING"]`))
+ require.Empty(t, list("project-b", `task_status in ["FAILED"]`))
+
+ // The stage summaries read the same task statuses the filter matches.
+ counts, err := s.ListTaskStatusCountByPlanIDs(ctx, []string{"project-a"}, []int64{101, 102, 104})
+ require.NoError(t, err)
+ var got []string
+ for _, c := range counts {
+ got = append(got, fmt.Sprintf("%d/%s/%s/%d", c.PlanID, c.Environment, c.Status, c.Count))
+ }
+ require.ElementsMatch(t, []string{
+ "101/test/DONE/1", "101/prod/FAILED/1",
+ "102/test/DONE/1", "102/prod/SKIPPED/1",
+ "104/test/PENDING/1",
+ }, got)
+}
diff --git a/backend/store/task.go b/backend/store/task.go
index 51573b1f34..5705c6047a 100644
--- a/backend/store/task.go
+++ b/backend/store/task.go
@@ -425,39 +425,10 @@ func (s *Store) ListTaskStatusCountByPlanIDs(ctx context.Context, projectIDs []s
t.environment,
t.status,
COUNT(*)::INT
- FROM (
- SELECT
- task.project,
- task.plan_id,
- COALESCE(task.environment, '') AS environment,
- CASE
- WHEN COALESCE((task.payload->>'skipped')::BOOLEAN, FALSE) THEN ?
- WHEN latest_task_run.status IS NULL THEN ?
- WHEN latest_task_run.status = ? THEN ?
- ELSE latest_task_run.status
- END AS status
- FROM task
- LEFT JOIN LATERAL (
- SELECT task_run.status
- FROM task_run
- WHERE task_run.project = task.project
- AND task_run.task_id = task.id
- ORDER BY task_run.id DESC
- LIMIT 1
- ) AS latest_task_run ON TRUE
- WHERE task.project = ANY(?)
- AND task.plan_id = ANY(?)
- ) AS t
+ FROM (?) AS t
GROUP BY t.project, t.plan_id, t.environment, t.status
ORDER BY t.project, t.plan_id, t.environment
- `,
- storepb.TaskRun_SKIPPED.String(),
- storepb.TaskRun_NOT_STARTED.String(),
- storepb.TaskRun_AVAILABLE.String(),
- storepb.TaskRun_PENDING.String(),
- projectIDs,
- planIDs,
- )
+ `, taskStatusQuery(qb.Q().Space("task.project = ANY(?) AND task.plan_id = ANY(?)", projectIDs, planIDs)))
query, args, err := q.ToSQL()
if err != nil {
return nil, errors.Wrapf(err, "failed to build sql")
@@ -483,6 +454,39 @@ func (s *Store) ListTaskStatusCountByPlanIDs(ctx context.Context, projectIDs []s
return results, nil
}
+// taskStatusQuery selects the API-visible status of each task matching where.
+// Plan stage summaries and the plan task_status filter share it so they cannot disagree.
+func taskStatusQuery(where *qb.Query) *qb.Query {
+ return qb.Q().Space(`
+ SELECT
+ task.project,
+ task.plan_id,
+ COALESCE(task.environment, '') AS environment,
+ CASE
+ WHEN COALESCE((task.payload->>'skipped')::BOOLEAN, FALSE) THEN ?
+ WHEN latest_task_run.status IS NULL THEN ?
+ WHEN latest_task_run.status = ? THEN ?
+ ELSE latest_task_run.status
+ END AS status
+ FROM task
+ LEFT JOIN LATERAL (
+ SELECT task_run.status
+ FROM task_run
+ WHERE task_run.project = task.project
+ AND task_run.task_id = task.id
+ ORDER BY task_run.id DESC
+ LIMIT 1
+ ) AS latest_task_run ON TRUE
+ WHERE ?
+ `,
+ storepb.TaskRun_SKIPPED.String(),
+ storepb.TaskRun_NOT_STARTED.String(),
+ storepb.TaskRun_AVAILABLE.String(),
+ storepb.TaskRun_PENDING.String(),
+ where,
+ )
+}
+
// BatchSkipTasks batch skip tasks.
func (s *Store) BatchSkipTasks(ctx context.Context, projectID string, taskUIDs []int64, comment string) error {
if len(taskUIDs) == 0 {
diff --git a/frontend/src/types/proto-es/v1/plan_service_pb.d.ts b/frontend/src/types/proto-es/v1/plan_service_pb.d.ts
index 04a214d4fc..1978bd2a38 100644
--- a/frontend/src/types/proto-es/v1/plan_service_pb.d.ts
+++ b/frontend/src/types/proto-es/v1/plan_service_pb.d.ts
@@ -78,6 +78,9 @@ export declare type ListPlansRequest = Message<"bytebase.v1.ListPlansRequest"> &
* - title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match.
* - spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config".
* - state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".
+ * - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false".
+ * - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator.
+ * - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
*
* For example:
* creator == "users/[email protected]" && create_time >= "2025-01-02T15:04:05Z07:00"
@@ -85,6 +88,8 @@ export declare type ListPlansRequest = Message<"bytebase.v1.ListPlansRequest"> &
* title.contains("database migration")
* spec_type == "change_database_config"
* state == "ACTIVE"
+ * has_release == true && task_status in ["FAILED", "RUNNING"]
+ * release == "projects/my-project/releases/release_20260115-RC00"
*
* @generated from field: string filter = 4;
*/
diff --git a/proto/gen/grpc-doc/openapi.yaml b/proto/gen/grpc-doc/openapi.yaml
index cec8e98fac..6ba5fadd27 100644
--- a/proto/gen/grpc-doc/openapi.yaml
+++ b/proto/gen/grpc-doc/openapi.yaml
@@ -11607,6 +11607,9 @@ paths:
- title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match.
- spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config".
- state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".
+ - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false".
+ - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator.
+ - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
For example:
creator == "users/[email protected]" && create_time >= "2025-01-02T15:04:05Z07:00"
@@ -11614,6 +11617,8 @@ paths:
title.contains("database migration")
spec_type == "change_database_config"
state == "ACTIVE"
+ has_release == true && task_status in ["FAILED", "RUNNING"]
+ release == "projects/my-project/releases/release_20260115-RC00"
schema:
type: string
title: filter
@@ -23571,6 +23576,9 @@ components:
- title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match.
- spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config".
- state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".
+ - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false".
+ - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator.
+ - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
For example:
creator == "users/[email protected]" && create_time >= "2025-01-02T15:04:05Z07:00"
@@ -23578,6 +23586,8 @@ components:
title.contains("database migration")
spec_type == "change_database_config"
state == "ACTIVE"
+ has_release == true && task_status in ["FAILED", "RUNNING"]
+ release == "projects/my-project/releases/release_20260115-RC00"
title: ListPlansRequest
required:
- parent
diff --git a/proto/gen/grpc-doc/v1/README.md b/proto/gen/grpc-doc/v1/README.md
index c3e17a5a3c..482a8bf3ab 100644
--- a/proto/gen/grpc-doc/v1/README.md
+++ b/proto/gen/grpc-doc/v1/README.md
@@ -3024,9 +3024,9 @@ SQLService executes SQL queries and manages query operations.
When paginating, all other parameters provided to `ListPlans` must match the call that provided the page token. |
| filter | [string](#string) | | Filter is used to filter plans returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec
-Supported filters: - creator: the plan creator full name in &#34;users/{email or id}&#34; format, support &#34;==&#34; operator. - create_time: the plan create time in &#34;2006-01-02T15:04:05Z07:00&#34; format, support &#34;&gt;=&#34; or &#34;&lt;=&#34; operator. - has_rollout: whether the plan has rollout, support &#34;==&#34; operator, the value should be &#34;true&#34; or &#34;false&#34;. - title: the plan title, support &#34;==&#34; operator for exact match and &#34;.contains()&#34; operator for case-insensitive substring match. - spec_type: the plan spec config type, support &#34;==&#34; operator, the value should be &#34;create_database_config&#34; or &#34;change_database_config&#34;. - state: the plan state, support &#34;==&#34; operator, the value should be &#34;ACTIVE&#34; or &#34;DELETED&#34;.
+Supported filters: - creator: the plan creator full name in &#34;users/{email or id}&#34; format, support &#34;==&#34; operator. - create_time: the plan create time in &#34;2006-01-02T15:04:05Z07:00&#34; format, support &#34;&gt;=&#34; or &#34;&lt;=&#34; operator. - has_rollout: whether the plan has rollout, support &#34;==&#34; operator, the value should be &#34;true&#34; or &#34;false&#34;. - title: the plan title, support &#34;==&#34; operator for exact match and &#34;.contains()&#34; operator for case-insensitive substring match. - spec_type: the plan spec config type, support &#34;==&#34; operator, the value should be &#34;create_database_config&#34; or &#34;change_database_config&#34;. - state: the plan state, support &#34;==&#34; operator, the value should be &#34;ACTIVE&#34; or &#34;DELETED&#34;. - has_release: whether a spec references a release, support &#34;==&#34; operator, the value should be &#34;true&#34; or &#34;false&#34;. - release: the release a spec references, in &#34;projects/{project}/releases/{release}&#34; format, support &#34;==&#34; operator. - task_status: the current status of any task in the plan, support &#34;in&#34; operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
-For example: creator == &#34;users/[email protected]&#34; &amp;&amp; create_time &gt;= &#34;2025-01-02T15:04:05Z07:00&#34; title == &#34;My Plan&#34; title.contains(&#34;database migration&#34;) spec_type == &#34;change_database_config&#34; state == &#34;ACTIVE&#34; |
+For example: creator == &#34;users/[email protected]&#34; &amp;&amp; create_time &gt;= &#34;2025-01-02T15:04:05Z07:00&#34; title == &#34;My Plan&#34; title.contains(&#34;database migration&#34;) spec_type == &#34;change_database_config&#34; state == &#34;ACTIVE&#34; has_release == true &amp;&amp; task_status in [&#34;FAILED&#34;, &#34;RUNNING&#34;] release == &#34;projects/my-project/releases/release_20260115-RC00&#34; |
diff --git a/proto/gen/grpc-doc/v1/index.html b/proto/gen/grpc-doc/v1/index.html
index 6bc0a31756..3256e2936a 100644
--- a/proto/gen/grpc-doc/v1/index.html
+++ b/proto/gen/grpc-doc/v1/index.html
@@ -9398,13 +9398,18 @@ Supported filters:
- title: the plan title, support &#34;==&#34; operator for exact match and &#34;.contains()&#34; operator for case-insensitive substring match.
- spec_type: the plan spec config type, support &#34;==&#34; operator, the value should be &#34;create_database_config&#34; or &#34;change_database_config&#34;.
- state: the plan state, support &#34;==&#34; operator, the value should be &#34;ACTIVE&#34; or &#34;DELETED&#34;.
+- has_release: whether a spec references a release, support &#34;==&#34; operator, the value should be &#34;true&#34; or &#34;false&#34;.
+- release: the release a spec references, in &#34;projects/{project}/releases/{release}&#34; format, support &#34;==&#34; operator.
+- task_status: the current status of any task in the plan, support &#34;in&#34; operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
For example:
creator == &#34;users/[email protected]&#34; &amp;&amp; create_time &gt;= &#34;2025-01-02T15:04:05Z07:00&#34;
title == &#34;My Plan&#34;
title.contains(&#34;database migration&#34;)
spec_type == &#34;change_database_config&#34;
-state == &#34;ACTIVE&#34; </p></td>
+state == &#34;ACTIVE&#34;
+has_release == true &amp;&amp; task_status in [&#34;FAILED&#34;, &#34;RUNNING&#34;]
+release == &#34;projects/my-project/releases/release_20260115-RC00&#34; </p></td>
</tr>
</tbody>
diff --git a/proto/v1/v1/plan_service.proto b/proto/v1/v1/plan_service.proto
index e651e11ad3..584208dcc2 100644
--- a/proto/v1/v1/plan_service.proto
+++ b/proto/v1/v1/plan_service.proto
@@ -151,6 +151,9 @@ message ListPlansRequest {
// - title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match.
// - spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config".
// - state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".
+ // - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false".
+ // - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator.
+ // - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED.
//
// For example:
// creator == "users/[email protected]" && create_time >= "2025-01-02T15:04:05Z07:00"
@@ -158,6 +161,8 @@ message ListPlansRequest {
// title.contains("database migration")
// spec_type == "change_database_config"
// state == "ACTIVE"
+ // has_release == true && task_status in ["FAILED", "RUNNING"]
+ // release == "projects/my-project/releases/release_20260115-RC00"
string filter = 4;
}