Skip to content

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

perf: persist access grant query hashes (#21565)

p0ny4482ca696213
diff --git a/backend/api/v1/sql_service.go b/backend/api/v1/sql_service.go
index 727f79d939..84415b9c1b 100644
--- a/backend/api/v1/sql_service.go
+++ b/backend/api/v1/sql_service.go
@@ -231,7 +231,7 @@ func (s *SQLService) preCheckAccess(ctx context.Context, statement string, insta
ProjectID: database.ProjectID,
Creator: user.Email,
Target: formatDatabaseResourceName(instance, database),
- Statement: strings.Trim(statement, " \t\n\r\v\f"),
+ Statement: statement,
Schema: requestSchema,
Container: container,
RequireExport: requireExport,
diff --git a/backend/api/v1/sql_service_access_grant_test.go b/backend/api/v1/sql_service_access_grant_test.go
new file mode 100644
index 0000000000..3ac77954dd
--- /dev/null
+++ b/backend/api/v1/sql_service_access_grant_test.go
@@ -0,0 +1,74 @@
+package v1
+
+import (
+ "context"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common"
+ "github.com/bytebase/bytebase/backend/common/testcontainer"
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/store"
+)
+
+func TestPreCheckAccessQueryHash(t *testing.T) {
+ t.Parallel()
+ longSQL := "SELECT '" + strings.Repeat("x", 110_000) + "' AS v"
+ for _, tc := range []struct {
+ name string
+ approved string
+ statement string
+ dropHash bool
+ want bool
+ }{
+ {name: "plain", approved: "SELECT 1", statement: "SELECT 1", want: true},
+ {name: "boundary whitespace", approved: "\v\fSELECT 1\r\n", statement: " \tSELECT 1\n", want: true},
+ {name: "long SQL", approved: longSQL, statement: longSQL, want: true},
+ {name: "different query", approved: "SELECT 1", statement: "SELECT 2"},
+ {name: "comment newline", approved: "SELECT 1 --\nWHERE false", statement: "SELECT 1 -- WHERE false"},
+ {name: "internal whitespace", approved: "SELECT 'a b'", statement: "SELECT 'a b'"},
+ {name: "Unicode boundary", approved: "\u00a0SELECT 1", statement: "SELECT 1"},
+ {name: "missing stored hash", approved: "SELECT 1", statement: "SELECT 1", dropHash: true},
+ {name: "write statement", approved: "DELETE FROM t", statement: "DELETE FROM t"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := context.WithValue(context.Background(), common.WorkspaceIDContextKey, "default")
+ ctx = context.WithValue(ctx, common.UserContextKey, &store.UserMessage{Email: "[email protected]"})
+ db, stores, _ := testcontainer.NewMetadataDB(t)
+ _, err := db.ExecContext(ctx, `
+ INSERT INTO workspace (resource_id) VALUES ('default');
+ INSERT INTO project (resource_id, workspace, name, setting)
+ VALUES ('grant-project', 'default', 'Grant Project', '{"allowJustInTimeAccess":true}');`)
+ require.NoError(t, err)
+ expires := time.Now().Add(time.Hour)
+ grant, err := stores.CreateAccessGrant(ctx, &store.AccessGrantMessage{
+ ProjectID: "grant-project", Creator: "[email protected]", Status: storepb.AccessGrant_ACTIVE, ExpireTime: &expires,
+ Payload: &storepb.AccessGrantPayload{
+ Query: tc.approved, Targets: []string{"instances/test/databases/db"}, Export: true, Unmask: true,
+ },
+ })
+ require.NoError(t, err)
+ require.NotEmpty(t, grant.Payload.QueryHash)
+ if tc.dropHash {
+ _, err = db.ExecContext(ctx, `UPDATE access_grant SET payload = payload - 'queryHash' WHERE id = $1`, grant.ID)
+ require.NoError(t, err)
+ }
+ service := &SQLService{store: stores}
+ instance := &store.InstanceMessage{ResourceID: "test", Metadata: &storepb.Instance{Engine: storepb.Engine_POSTGRES}}
+ database := &store.DatabaseMessage{ProjectID: "grant-project", InstanceID: "test", DatabaseName: "db"}
+ for _, requireExport := range []bool{false, true} {
+ got := service.preCheckAccess(ctx, tc.statement, instance, database, nil, "", requireExport)
+ if tc.want {
+ require.NotNil(t, got)
+ require.Equal(t, grant.ID, got.ID)
+ } else {
+ require.Nil(t, got)
+ }
+ }
+ })
+ }
+}
diff --git a/backend/generated-go/store/access_grant.pb.go b/backend/generated-go/store/access_grant.pb.go
index ec3b67586f..d3a48b11d2 100644
--- a/backend/generated-go/store/access_grant.pb.go
+++ b/backend/generated-go/store/access_grant.pb.go
@@ -131,7 +131,10 @@ type AccessGrantPayload struct {
// The default schema to execute the query.
Schema string `protobuf:"bytes,8,opt,name=schema,proto3" json:"schema,omitempty"`
// The container name to execute the query against, used for CosmosDB only.
- Container string `protobuf:"bytes,9,opt,name=container,proto3" json:"container,omitempty"`
+ Container string `protobuf:"bytes,9,opt,name=container,proto3" json:"container,omitempty"`
+ // Lowercase hex SHA-256 of query after trimming boundary space, tab, LF, CR,
+ // vertical tab, and form feed. Derived by the store for grant matching.
+ QueryHash string `protobuf:"bytes,10,opt,name=query_hash,json=queryHash,proto3" json:"query_hash,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -229,6 +232,13 @@ func (x *AccessGrantPayload) GetContainer() string {
return ""
}
+func (x *AccessGrantPayload) GetQueryHash() string {
+ if x != nil {
+ return x.QueryHash
+ }
+ return ""
+}
+
var File_store_access_grant_proto protoreflect.FileDescriptor
const file_store_access_grant_proto_rawDesc = "" +
@@ -240,7 +250,7 @@ const file_store_access_grant_proto_rawDesc = "" +
"\aPENDING\x10\x01\x12\n" +
"\n" +
"\x06ACTIVE\x10\x02\x12\v\n" +
- "\aREVOKED\x10\x03\"\xa7\x02\n" +
+ "\aREVOKED\x10\x03\"\xc6\x02\n" +
"\x12AccessGrantPayload\x12\x19\n" +
"\bissue_id\x18\x01 \x01(\x03R\aissueId\x12\x18\n" +
"\atargets\x18\x02 \x03(\tR\atargets\x12\x14\n" +
@@ -250,7 +260,10 @@ const file_store_access_grant_proto_rawDesc = "" +
"\x12requested_duration\x18\x06 \x01(\v2\x19.google.protobuf.DurationR\x11requestedDuration\x12\x16\n" +
"\x06export\x18\a \x01(\bR\x06export\x12\x16\n" +
"\x06schema\x18\b \x01(\tR\x06schema\x12\x1c\n" +
- "\tcontainer\x18\t \x01(\tR\tcontainerB\x93\x01\n" +
+ "\tcontainer\x18\t \x01(\tR\tcontainer\x12\x1d\n" +
+ "\n" +
+ "query_hash\x18\n" +
+ " \x01(\tR\tqueryHashB\x93\x01\n" +
"\x12com.bytebase.storeB\x10AccessGrantProtoP\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 (
diff --git a/backend/generated-go/store/access_grant_equal.pb.go b/backend/generated-go/store/access_grant_equal.pb.go
index 9d8c441380..1703fd6c35 100644
--- a/backend/generated-go/store/access_grant_equal.pb.go
+++ b/backend/generated-go/store/access_grant_equal.pb.go
@@ -52,5 +52,8 @@ func (x *AccessGrantPayload) Equal(y *AccessGrantPayload) bool {
if x.Container != y.Container {
return false
}
+ if x.QueryHash != y.QueryHash {
+ return false
+ }
return true
}
diff --git a/backend/migrator/migration/3.24/0000##access_grant_query_hash.sql b/backend/migrator/migration/3.24/0000##access_grant_query_hash.sql
new file mode 100644
index 0000000000..b461e9cdb3
--- /dev/null
+++ b/backend/migrator/migration/3.24/0000##access_grant_query_hash.sql
@@ -0,0 +1,9 @@
+UPDATE access_grant
+SET payload = jsonb_set(
+ payload,
+ '{queryHash}',
+ to_jsonb(encode(sha256(convert_to(btrim(payload->>'query', E' \t\n\r\x0b\f'), 'UTF8')), 'hex'))
+)
+WHERE payload->>'query' IS NOT NULL;
+
+CREATE INDEX idx_access_grant_project_creator_query_hash ON access_grant(project, creator, (payload->>'queryHash'));
diff --git a/backend/migrator/migration/LATEST.sql b/backend/migrator/migration/LATEST.sql
index 9ac55a974d..493e806334 100644
--- a/backend/migrator/migration/LATEST.sql
+++ b/backend/migrator/migration/LATEST.sql
@@ -520,6 +520,7 @@ CREATE TABLE access_grant (
);
CREATE INDEX idx_access_grant_project_creator_expire_time ON access_grant(project, creator, expire_time);
+CREATE INDEX idx_access_grant_project_creator_query_hash ON access_grant(project, creator, (payload->>'queryHash'));
CREATE TABLE query_history (
-- global unique
diff --git a/backend/migrator/migrator_test.go b/backend/migrator/migrator_test.go
index 947a13f7b4..d1b6a45e03 100644
--- a/backend/migrator/migrator_test.go
+++ b/backend/migrator/migrator_test.go
@@ -10,8 +10,8 @@ import (
func TestLatestVersion(t *testing.T) {
files, err := getSortedVersionedFiles()
require.NoError(t, err)
- require.Equal(t, semver.MustParse("3.23.5"), *files[len(files)-1].version)
- require.Equal(t, "migration/3.23/0005##issue_comment_creator_nullable.sql", files[len(files)-1].path)
+ require.Equal(t, semver.MustParse("3.24.0"), *files[len(files)-1].version)
+ require.Equal(t, "migration/3.24/0000##access_grant_query_hash.sql", files[len(files)-1].path)
}
func TestVersionUnique(t *testing.T) {
diff --git a/backend/store/access_grant.go b/backend/store/access_grant.go
index 6006681bfe..304321b9cb 100644
--- a/backend/store/access_grant.go
+++ b/backend/store/access_grant.go
@@ -2,6 +2,8 @@ package store
import (
"context"
+ "crypto/sha256"
+ "encoding/hex"
"fmt"
"strings"
"time"
@@ -50,8 +52,6 @@ type FindAccessGrantMessage struct {
}
// FindActiveAccessGrantMessage scopes a statement-bound JIT grant lookup.
-// It deliberately uses structured fields rather than a CEL filter so a large
-// statement can be passed directly to PostgreSQL as a parameter.
type FindActiveAccessGrantMessage struct {
Workspace string
ProjectID string
@@ -73,7 +73,7 @@ type UpdateAccessGrantMessage struct {
// CreateAccessGrant creates a new access grant.
func (s *Store) CreateAccessGrant(ctx context.Context, create *AccessGrantMessage) (*AccessGrantMessage, error) {
- payload, err := protojson.Marshal(create.Payload)
+ payload, err := marshalAccessGrantPayload(create.Payload)
if err != nil {
return nil, errors.Wrapf(err, "failed to marshal payload")
}
@@ -103,6 +103,21 @@ func (s *Store) CreateAccessGrant(ctx context.Context, create *AccessGrantMessag
return create, nil
}
+func marshalAccessGrantPayload(payload *storepb.AccessGrantPayload) ([]byte, error) {
+ if payload != nil {
+ payload.QueryHash = ""
+ if payload.Query != "" {
+ payload.QueryHash = hashAccessGrantQuery(payload.Query)
+ }
+ }
+ return protojson.Marshal(payload)
+}
+
+func hashAccessGrantQuery(query string) string {
+ digest := sha256.Sum256([]byte(strings.Trim(query, " \t\n\r\v\f")))
+ return hex.EncodeToString(digest[:])
+}
+
// GetAccessGrant gets an access grant.
func (s *Store) GetAccessGrant(ctx context.Context, find *FindAccessGrantMessage) (*AccessGrantMessage, error) {
grants, err := s.ListAccessGrants(ctx, find)
@@ -221,7 +236,7 @@ func getActiveAccessGrantFilter(find *FindActiveAccessGrantMessage) *qb.Query {
And("access_grant.status = ?", storepb.AccessGrant_ACTIVE.String()).
And("access_grant.expire_time > ?", find.ExpireTime).
And("access_grant.payload->'targets' @> jsonb_build_array(to_jsonb(?::text))", find.Target).
- And("btrim(access_grant.payload->>'query', E' \\t\\n\\r\\x0b\\f') = ?", find.Statement).
+ And("access_grant.payload->>'queryHash' = ?", hashAccessGrantQuery(find.Statement)).
And("COALESCE(access_grant.payload->>'schema', '') = ?", find.Schema).
And("COALESCE(access_grant.payload->>'container', '') = ?", find.Container)
if find.RequireExport {
@@ -254,7 +269,7 @@ func (s *Store) UpdateAccessGrant(ctx context.Context, id string, update *Update
set.Comma("expire_time = ?", *v)
}
if v := update.Payload; v != nil {
- p, err := protojson.Marshal(v)
+ p, err := marshalAccessGrantPayload(v)
if err != nil {
return nil, errors.Wrapf(err, "failed to marshal payload")
}
@@ -412,7 +427,7 @@ func GetListAccessGrantFilter(filter string) (*qb.Query, error) {
if !ok || len(hash) != 64 || strings.Trim(hash, "0123456789abcdef") != "" {
return nil, errors.New("query_hash must be a lowercase hexadecimal SHA-256 digest")
}
- return qb.Q().Space("encode(sha256(convert_to(btrim(access_grant.payload->>'query', E' \\t\\n\\r\\x0b\\f'), 'UTF8')), 'hex') = ?", hash), nil
+ return qb.Q().Space("access_grant.payload->>'queryHash' = ?", hash), nil
case "schema", "container":
contextValue, ok := value.(string)
if !ok {
diff --git a/backend/store/access_grant_filter_test.go b/backend/store/access_grant_filter_test.go
index 0c8a76fe17..4fb036bf83 100644
--- a/backend/store/access_grant_filter_test.go
+++ b/backend/store/access_grant_filter_test.go
@@ -12,7 +12,7 @@ func TestGetActiveAccessGrantFilter(t *testing.T) {
expireTime := time.Date(2026, time.September, 3, 0, 0, 0, 0, time.UTC)
q := getActiveAccessGrantFilter(&FindActiveAccessGrantMessage{
Target: "instances/prod/databases/app",
- Statement: "SELECT 1",
+ Statement: " \t\n\r\v\fSELECT 1\r\n",
Schema: "public",
Container: "orders",
ExpireTime: expireTime,
@@ -21,10 +21,10 @@ func TestGetActiveAccessGrantFilter(t *testing.T) {
sql, args, err := q.ToSQL()
require.NoError(t, err)
require.Contains(t, sql, "access_grant.payload->'targets' @> jsonb_build_array(to_jsonb($3::text))")
- require.Contains(t, sql, "btrim(access_grant.payload->>'query', E' \\t\\n\\r\\x0b\\f') = $4")
+ require.Contains(t, sql, "access_grant.payload->>'queryHash' = $4")
require.Contains(t, sql, "COALESCE(access_grant.payload->>'schema', '') = $5")
require.Contains(t, sql, "COALESCE(access_grant.payload->>'container', '') = $6")
- require.Equal(t, []any{"ACTIVE", expireTime, "instances/prod/databases/app", "SELECT 1", "public", "orders"}, args)
+ require.Equal(t, []any{"ACTIVE", expireTime, "instances/prod/databases/app", "e004ebd5b5532a4b85984a62f8ad48a81aa3460c1ca07701f386135d72cdecf5", "public", "orders"}, args)
}
func TestGetListAccessGrantFilter(t *testing.T) {
diff --git a/backend/store/access_grant_query_hash_test.go b/backend/store/access_grant_query_hash_test.go
index a39054d976..4313c8ee0d 100644
--- a/backend/store/access_grant_query_hash_test.go
+++ b/backend/store/access_grant_query_hash_test.go
@@ -12,6 +12,7 @@ import (
"time"
"github.com/stretchr/testify/require"
+ "google.golang.org/protobuf/encoding/protojson"
"github.com/bytebase/bytebase/backend/common/testcontainer"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
@@ -27,14 +28,7 @@ func TestAccessGrantQueryHash(t *testing.T) {
INSERT INTO project (resource_id, workspace, name) VALUES ('hash', 'default', 'Hash');
`)
require.NoError(t, err)
- data, err := os.ReadFile("../../testdata/access_grant_query_hash.json")
- require.NoError(t, err)
- var vectors []struct {
- Name string
- Input string
- Hash string
- }
- require.NoError(t, json.Unmarshal(data, &vectors))
+ vectors := readAccessGrantQueryHashVectors(t)
expires := time.Now().Add(time.Hour)
project, creator := "hash", "[email protected]"
for i, vector := range vectors {
@@ -46,22 +40,24 @@ func TestAccessGrantQueryHash(t *testing.T) {
target := fmt.Sprintf("instances/hash/databases/db%d", i)
grant, err := stores.CreateAccessGrant(ctx, &store.AccessGrantMessage{
ProjectID: project, Creator: creator, Status: storepb.AccessGrant_ACTIVE, ExpireTime: &expires,
- Payload: &storepb.AccessGrantPayload{Query: vector.Input, Targets: []string{target}, Export: true},
+ Payload: &storepb.AccessGrantPayload{Query: vector.Input, QueryHash: "untrusted", Targets: []string{target}, Export: true},
})
require.NoError(t, err)
+ require.Equal(t, vector.Hash, grant.Payload.QueryHash)
filter, err := store.GetListAccessGrantFilter(fmt.Sprintf(`query_hash == %q && target == %q && schema == "" && container == "" && status == "ACTIVE" && export == true`, vector.Hash, target))
require.NoError(t, err)
grants, err := stores.ListAccessGrants(ctx, &store.FindAccessGrantMessage{Workspace: "default", ProjectID: &project, Creator: &creator, FilterQ: filter})
require.NoError(t, err)
require.Len(t, grants, 1)
require.Equal(t, grant.ID, grants[0].ID)
+ require.Equal(t, vector.Hash, grants[0].Payload.QueryHash)
wrongDigest := sha256.Sum256([]byte(normalized + "v"))
wrongFilter, err := store.GetListAccessGrantFilter(fmt.Sprintf(`query_hash == %q && target == %q`, hex.EncodeToString(wrongDigest[:]), target))
require.NoError(t, err)
grants, err = stores.ListAccessGrants(ctx, &store.FindAccessGrantMessage{Workspace: "default", ProjectID: &project, Creator: &creator, FilterQ: wrongFilter})
require.NoError(t, err)
require.Empty(t, grants)
- runtimeFind := &store.FindActiveAccessGrantMessage{Workspace: "default", ProjectID: project, Creator: creator, Target: target, Statement: normalized, RequireExport: true, ExpireTime: time.Now()}
+ runtimeFind := &store.FindActiveAccessGrantMessage{Workspace: "default", ProjectID: project, Creator: creator, Target: target, Statement: vector.Input, RequireExport: true, ExpireTime: time.Now()}
grants, err = stores.ListActiveAccessGrants(ctx, runtimeFind)
require.NoError(t, err)
require.Len(t, grants, 1)
@@ -83,6 +79,138 @@ func TestAccessGrantQueryHash(t *testing.T) {
}
}
+func TestAccessGrantQueryHashUpdates(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ db, stores, _ := testcontainer.NewMetadataDB(t)
+ _, err := db.ExecContext(ctx, `
+ INSERT INTO workspace (resource_id) VALUES ('default');
+ INSERT INTO project (resource_id, workspace, name) VALUES ('hash', 'default', 'Hash');
+ `)
+ require.NoError(t, err)
+ grant, err := stores.CreateAccessGrant(ctx, &store.AccessGrantMessage{
+ ProjectID: "hash", Creator: "[email protected]", Status: storepb.AccessGrant_PENDING,
+ Payload: &storepb.AccessGrantPayload{Query: "SELECT 0"},
+ })
+ require.NoError(t, err)
+ for _, vector := range readAccessGrantQueryHashVectors(t) {
+ oldHash := grant.Payload.QueryHash
+ grant.Payload.Query = vector.Input
+ grant, err = stores.UpdateAccessGrant(ctx, grant.ID, &store.UpdateAccessGrantMessage{Payload: grant.Payload})
+ require.NoError(t, err)
+ require.Equal(t, vector.Input, grant.Payload.Query)
+ require.Equal(t, vector.Hash, grant.Payload.QueryHash)
+ filter, err := store.GetListAccessGrantFilter(fmt.Sprintf(`query_hash == %q`, vector.Hash))
+ require.NoError(t, err)
+ matched, err := stores.GetAccessGrant(ctx, &store.FindAccessGrantMessage{ID: &grant.ID, FilterQ: filter})
+ require.NoError(t, err)
+ require.NotNil(t, matched)
+ if oldHash != vector.Hash {
+ filter, err = store.GetListAccessGrantFilter(fmt.Sprintf(`query_hash == %q`, oldHash))
+ require.NoError(t, err)
+ matched, err = stores.GetAccessGrant(ctx, &store.FindAccessGrantMessage{ID: &grant.ID, FilterQ: filter})
+ require.NoError(t, err)
+ require.Nil(t, matched)
+ }
+ }
+
+ wantHash := grant.Payload.QueryHash
+ grant.Payload.IssueId = 123
+ grant.Payload.QueryHash = "untrusted"
+ grant, err = stores.UpdateAccessGrant(ctx, grant.ID, &store.UpdateAccessGrantMessage{Payload: grant.Payload})
+ require.NoError(t, err)
+ require.Equal(t, wantHash, grant.Payload.QueryHash)
+ require.Equal(t, int64(123), grant.Payload.IssueId)
+ for _, status := range []storepb.AccessGrant_Status{storepb.AccessGrant_ACTIVE, storepb.AccessGrant_REVOKED} {
+ expires := time.Now().Add(time.Hour)
+ grant, err = stores.UpdateAccessGrant(ctx, grant.ID, &store.UpdateAccessGrantMessage{Status: &status, ExpireTime: &expires})
+ require.NoError(t, err)
+ require.Equal(t, wantHash, grant.Payload.QueryHash)
+ }
+
+ grant.Payload.Query = ""
+ grant, err = stores.UpdateAccessGrant(ctx, grant.ID, &store.UpdateAccessGrantMessage{Payload: grant.Payload})
+ require.NoError(t, err)
+ require.Empty(t, grant.Payload.QueryHash)
+ filter, err := store.GetListAccessGrantFilter(fmt.Sprintf(`query_hash == %q`, wantHash))
+ require.NoError(t, err)
+ matched, err := stores.GetAccessGrant(ctx, &store.FindAccessGrantMessage{ID: &grant.ID, FilterQ: filter})
+ require.NoError(t, err)
+ require.Nil(t, matched)
+}
+
+func TestAccessGrantQueryHashMigration(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ db, stores, _ := testcontainer.NewMetadataDB(t)
+ _, err := db.ExecContext(ctx, `
+ INSERT INTO workspace (resource_id) VALUES ('default');
+ INSERT INTO project (resource_id, workspace, name) VALUES ('hash', 'default', 'Hash');
+ DROP INDEX idx_access_grant_project_creator_query_hash;
+ `)
+ require.NoError(t, err)
+ vectors := readAccessGrantQueryHashVectors(t)
+ timestamp := time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)
+ statuses := []string{"PENDING", "ACTIVE", "REVOKED"}
+ for i, vector := range vectors {
+ payload, err := protojson.Marshal(&storepb.AccessGrantPayload{
+ Query: vector.Input, Targets: []string{"instances/hash/databases/db"}, Export: true,
+ Schema: "public", Container: "orders", IssueId: 123,
+ })
+ require.NoError(t, err)
+ _, err = db.ExecContext(ctx, `INSERT INTO access_grant (id, project, creator, status, expire_time, payload, created_at, updated_at)
+ VALUES ($1, 'hash', '[email protected]', $2, $3, $4, $3, $3)`, vector.Name, statuses[i%len(statuses)], timestamp, payload)
+ require.NoError(t, err)
+ }
+ _, err = db.ExecContext(ctx, `INSERT INTO access_grant (id, project, creator, payload)
+ VALUES ('missing-query', 'hash', '[email protected]', '{"reason":"preserved"}'),
+ ('null-query', 'hash', '[email protected]', '{"query":null,"reason":"preserved"}')`)
+ require.NoError(t, err)
+ statement, err := os.ReadFile("../migrator/migration/3.24/0000##access_grant_query_hash.sql")
+ require.NoError(t, err)
+ _, err = db.ExecContext(ctx, string(statement))
+ require.NoError(t, err)
+ for i, vector := range vectors {
+ t.Run(vector.Name, func(t *testing.T) {
+ t.Parallel()
+ filter, err := store.GetListAccessGrantFilter(fmt.Sprintf(`query_hash == %q`, vector.Hash))
+ require.NoError(t, err)
+ grant, err := stores.GetAccessGrant(ctx, &store.FindAccessGrantMessage{ID: &vector.Name, FilterQ: filter})
+ require.NoError(t, err)
+ require.NotNil(t, grant)
+ require.Equal(t, vector.Input, grant.Payload.Query)
+ require.Equal(t, vector.Hash, grant.Payload.QueryHash)
+ require.Equal(t, []string{"instances/hash/databases/db"}, grant.Payload.Targets)
+ require.True(t, grant.Payload.Export)
+ require.Equal(t, "public", grant.Payload.Schema)
+ require.Equal(t, "orders", grant.Payload.Container)
+ require.Equal(t, int64(123), grant.Payload.IssueId)
+ require.Equal(t, statuses[i%len(statuses)], grant.Status.String())
+ require.True(t, timestamp.Equal(*grant.ExpireTime))
+ require.True(t, timestamp.Equal(grant.CreatedAt))
+ require.True(t, timestamp.Equal(grant.UpdatedAt))
+ })
+ }
+ for _, id := range []string{"missing-query", "null-query"} {
+ var payload string
+ require.NoError(t, db.QueryRowContext(ctx, `SELECT payload FROM access_grant WHERE id = $1`, id).Scan(&payload))
+ want := `{"reason":"preserved"}`
+ if id == "null-query" {
+ want = `{"query":null,"reason":"preserved"}`
+ }
+ require.JSONEq(t, want, payload)
+ }
+}
+
+func readAccessGrantQueryHashVectors(t *testing.T) []struct{ Name, Input, Hash string } {
+ t.Helper()
+ data, err := os.ReadFile("../../testdata/access_grant_query_hash.json")
+ require.NoError(t, err)
+ var vectors []struct{ Name, Input, Hash string }
+ require.NoError(t, json.Unmarshal(data, &vectors))
+ return vectors
+}
+
func TestAccessGrantHashDiscoveryScope(t *testing.T) {
t.Parallel()
ctx := context.Background()
@@ -119,6 +247,12 @@ func TestAccessGrantHashDiscoveryScope(t *testing.T) {
require.NoError(t, err)
grants, err := stores.ListAccessGrants(ctx, &store.FindAccessGrantMessage{Workspace: "first", ProjectID: &project, Creator: &creator, FilterQ: filter})
require.NoError(t, err)
+ runtimeGrants, err := stores.ListActiveAccessGrants(ctx, &store.FindActiveAccessGrantMessage{
+ Workspace: "first", ProjectID: project, Creator: creator, Target: target, Statement: query,
+ Schema: tc.schema, Container: tc.container, RequireExport: true, ExpireTime: time.Now(),
+ })
+ require.NoError(t, err)
+ require.Equal(t, grants, runtimeGrants)
if tc.want == "" {
require.Empty(t, grants)
} else {
diff --git a/docs/adr/0005-discover-access-grants-by-query-hash.md b/docs/adr/0005-discover-access-grants-by-query-hash.md
index 73f6619dc0..2687bf1bd6 100644
--- a/docs/adr/0005-discover-access-grants-by-query-hash.md
+++ b/docs/adr/0005-discover-access-grants-by-query-hash.md
@@ -7,24 +7,32 @@ feed, and sends lowercase hexadecimal. Internal whitespace, case, comments,
Unicode whitespace, and Unicode composition remain unchanged. This explicit
contract avoids differences between JavaScript, Go, and PostgreSQL trimming.
-The metadata query computes the same hash from the stored grant query during
-lookup, so existing grants require no backfill or additional stored state.
-This version accepts repeated hashing cost. A local PostgreSQL check with 100
-eligible 110-KB queries among 1,000 grants used the existing
-project/creator/expiry index and took 43–44 ms per lookup; this synthetic result
-does not establish production latency. A future version will persist hashes
-directly in the database. Hash storage, maintenance on writes,
-and backfilling existing grants are outside this version's scope; the CEL field
-and normalization contract must remain compatible with that future change.
+The store computes the same hash on grant creation and every payload replacement,
+persisting it as `AccessGrantPayload.query_hash` (`queryHash` in JSONB). The hash
+and query are written atomically, and caller-supplied hashes are overwritten.
+This follows the existing convention for content hashes in payloads. An
+expression index on project, creator, and `payload->>'queryHash'` supports
+discovery without repeatedly hashing stored SQL. Status and expiry updates leave
+the payload unchanged.
+
+A metadata migration backfills existing queries with the same normalization
+before creating the index. It updates all grant statuses without changing their
+timestamps. Grants without a query remain without a hash. The backfill and index
+creation run in the normal migration transaction; upgrade time depends on stored
+SQL volume. All writers must run the new code before relying on stored hashes:
+older writers can omit the hash or discard it when replacing a payload.
Discovery includes exact target, schema, and container predicates along with
active status and export capability. Empty schema and container values match
only empty values. The server retains caller, project, and workspace scoping.
-Hashes serve discovery only: actual export authorization retains full-statement
-comparison using the same ASCII boundary normalization and rechecks eligibility.
+`SQLService.preCheckAccess` also matches the request's query hash against the
+stored hash when authorizing query or export access. Store writes and runtime
+lookups share one normalization and hashing helper. The server derives the hash
+from the submitted statement, rechecks grant eligibility, and verifies that the
+statement is read-only; it never accepts a caller-supplied authorization hash.
Single and batch export controls distinguish lookup errors from missing grants
and offer retry. They cannot enable export through a grant whose lookup failed.
Regression coverage must exercise shared normalization vectors across browser
-hashing, metadata hashing, and runtime matching, including vertical tabs,
-boundary letters `v`, Unicode, and long SQL.
+hashing, store writes, migration backfill, and runtime matching, including
+vertical tabs, boundary letters `v`, Unicode, and long SQL.
diff --git a/proto/gen/grpc-doc/store/README.md b/proto/gen/grpc-doc/store/README.md
index ab93fb3eb5..a96c90d3f9 100644
--- a/proto/gen/grpc-doc/store/README.md
+++ b/proto/gen/grpc-doc/store/README.md
@@ -382,6 +382,7 @@
| export | [bool](#bool) | | Whether export the query result. |
| schema | [string](#string) | | The default schema to execute the query. |
| container | [string](#string) | | The container name to execute the query against, used for CosmosDB only. |
+| query_hash | [string](#string) | | Lowercase hex SHA-256 of query after trimming boundary space, tab, LF, CR, vertical tab, and form feed. Derived by the store for grant matching. |
diff --git a/proto/gen/grpc-doc/store/index.html b/proto/gen/grpc-doc/store/index.html
index 48a60f8a05..1ea281785d 100644
--- a/proto/gen/grpc-doc/store/index.html
+++ b/proto/gen/grpc-doc/store/index.html
@@ -1650,6 +1650,14 @@ The server computes expire_time from this value at activation time. </p></td>
<td><p>The container name to execute the query against, used for CosmosDB only. </p></td>
</tr>
+ <tr>
+ <td>query_hash</td>
+ <td><a href="#string">string</a></td>
+ <td></td>
+ <td><p>Lowercase hex SHA-256 of query after trimming boundary space, tab, LF, CR,
+vertical tab, and form feed. Derived by the store for grant matching. </p></td>
+ </tr>
+
</tbody>
</table>
diff --git a/proto/store/store/access_grant.proto b/proto/store/store/access_grant.proto
index 7f9aebe7c8..e35a9268d7 100644
--- a/proto/store/store/access_grant.proto
+++ b/proto/store/store/access_grant.proto
@@ -44,4 +44,8 @@ message AccessGrantPayload {
// The container name to execute the query against, used for CosmosDB only.
string container = 9;
+
+ // Lowercase hex SHA-256 of query after trimming boundary space, tab, LF, CR,
+ // vertical tab, and form feed. Derived by the store for grant matching.
+ string query_hash = 10;
}