Skip to content

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

docs: saved-queries model — sharing, permissions, and API design

Dannyeb8a8bc7a1df
diff --git a/docs/design/saved-queries-model.md b/docs/design/saved-queries-model.md
new file mode 100644
index 0000000000..6abedbeafe
--- /dev/null
+++ b/docs/design/saved-queries-model.md
@@ -0,0 +1,584 @@
+# Saved queries: sharing, permissions, and API
+
+2026-08-09. Redesign of the SQL Editor's saved-query model — sharing,
+permissions, API, storage — and a rename from "worksheet" (see Naming).
+Replaces the three-state visibility flag with the industry-consensus model:
+per-object graduated grants to users and groups, private by default, with
+per-project discovery.
+
+## Background
+
+Saved queries (renamed from worksheets) are personal SQL scratchpads in the
+SQL Editor: drafted under a project, optionally shared with teammates,
+autosaved, high-churn. They are not change-management artifacts
+(sheets/releases carry deployed SQL). Every SQL Editor user touches them
+daily.
+
+## Problem
+
+1. **The authorization model has holes and no statable rule** (2026-08 v1
+ API audit, [v1-api-audit-2026-08.md](v1-api-audit-2026-08.md), T7/T8):
+ `CreateWorksheet` had **no permission check** — any authenticated
+ principal could plant a worksheet into any project; the creator
+ short-circuit **outlives project membership implicitly** — flag-derived
+ access with no grant to see, audit, or revoke; the `PROJECT_READ` write
+ path requires a permission no predefined role grants;
+ `bb.worksheets.list` is granted by no role and called by no UI;
+ `bb.worksheets.manage` is an unsurfaced god-mode that reads PRIVATE
+ content. Holes recur because there is no model to check a change against.
+2. **Sharing is all-or-nothing at project scope.** One mode flag per
+ worksheet: no per-person or per-group grants, no read/write split per
+ audience. "Share" means granting the whole project write — the easy path
+ is the unsafe one. Users overshare or don't share.
+3. **The current shape is the industry's deprecated generation.** A
+ project-scoped permission family plus a per-object visibility enum is
+ classic BigQuery — the design its own vendor is retiring. All current
+ peers use per-object grants; even the name "worksheet" is the retiring
+ term.
+
+## Goals
+
+Cited throughout as G1–G8.
+
+1. **One access rule**, statable in eight lines, enforced server-side;
+ every RPC gate derives from it.
+2. **Private by default**; per-object **VIEWER / EDITOR** grants to `user:`
+ and `group:` principals. No grantable owner tier.
+3. **BigQuery-layered gates**: a per-object grant carries content access;
+ *discovery* (Search, always per-project) is gated by a dedicated
+ `bb.savedQueries.search` permission carried by every project role;
+ *running* is gated by the SQL Editor's own database permissions. Leaving
+ a project ends discovery and run; explicit grants persist until
+ revoked.
+4. The **creator is the fixed owner** (no transfer); admins
+ (`bb.savedQueries.manage`) manage any saved query in scope, private
+ included.
+5. **Creation is gated** by `bb.savedQueries.create` on the parent project.
+6. A cross-project **auditor** (`bb.savedQueries.list`) enumerates/filters
+ saved queries (e.g. by creator) independent of grants — offboarding
+ review, incident audit.
+7. **Listing scales**: My / Shared / Starred are separate indexed queries
+ with keyset pagination; group sharing never expands group memberships.
+8. **Rename** worksheet → saved query, bundled with the already-breaking
+ API change.
+
+The frontend mirrors these rules for control visibility only; enforcement is
+server-side.
+
+### Non-goals
+
+- Anonymous public links — never; an *authenticated* link-grant is deferred,
+ not rejected (see Link sharing).
+- Cross-project "shared with me" — no peer has one.
+- Ownership transfer / co-ownership (see Alternatives).
+- Shared folders — Phase 2 (see Folders and stars).
+- A resource-level IAM store — the policy is purpose-built; an IAM-native
+ store can absorb it later (see Alternatives).
+
+## Naming: "worksheet" vs "saved query"
+
+| Term | Products |
+|---|---|
+| **Saved query** | BigQuery (our reference model) |
+| **Query** | Databricks, PopSQL, Redash |
+| **Question** | Metabase (BI framing) |
+| **Worksheet** | Snowflake — and Bytebase (current) |
+
+The industry standardized on **query / saved query**; "worksheet" is
+Snowflake's term, and Snowflake is retiring it (Worksheets → Workspaces,
+June 2026). **Decision: rename to `SavedQuery`** — resource type
+`bytebase.com/SavedQuery`, `SavedQueryService`,
+`projects/{p}/savedQueries/{id}`, `bb.savedQueries.*`, table `saved_query`,
+UI copy "Saved queries". The rename is breaking (proto, permissions, URLs,
+i18n, data) and cheapest paid now, bundled with the redesign's other
+breaking changes. In this document, "worksheet" / `bb.worksheets.*` / the
+`worksheet` table always denote the **current** system this design
+replaces — plus Snowflake's product term in the survey.
+
+## Industry survey
+
+| Product | Private by default | Sharing mechanism | Grant levels |
+|---|---|---|---|
+| BigQuery modern (Dataform-backed) | Yes | **Per-query IAM bindings**, to users/groups/`allAuthenticatedUsers` | Code Viewer / Editor / Owner |
+| Snowflake (Snowsight) | Yes | Per-recipient share on the worksheet | View / View+Run / Edit |
+| Databricks SQL | Yes (creator + admins) | Per-object ACL | CAN VIEW / RUN / EDIT / MANAGE |
+| PopSQL | Yes (personal folder); shared folders team-visible | Per-query / per-folder | Viewer / Editor |
+| BigQuery classic (deprecated) | Yes (Personal) | Visibility tier + project-scoped permission family | Personal / Project / Public-link |
+| Bytebase (current) | Yes (PRIVATE) | Per-worksheet project-wide mode flag | PROJECT_READ / PROJECT_WRITE |
+
+Classic BigQuery — the project-scoped permission family plus visibility
+enum, the model closest to Bytebase's current shape — is **deprecated**
+(proximity is not a direction); modern Dataform-backed saved queries with
+**resource-level IAM** (`dataform.codeViewer/Editor/Owner` on the query) are
+the only path forward. The modern model has no project-members principal, so
+Google's own migration turns Project-visibility queries owner-private for
+manual re-grant. This design accepts the same class of tradeoff — the
+share-with-project snapshot (see Model) — rather than inventing a
+project-derived principal.
+
+### Consensus
+
+All four current-generation products (modern BigQuery, Snowsight,
+Databricks, PopSQL) agree: **private by default** with the creator as
+implicit owner; **sharing = graduated per-object grants**; **shared editing
+standard**, fork as complement; grants ride the platform's own grant system
+where one exists. Team-wide sharing always means **groups** — explicit,
+separately-maintained user lists (Snowflake roles, Google groups, Databricks
+groups) — **never a principal derived from a container's access policy**.
+This design follows: sharing targets `user:`/`group:` only, and accepts
+losing the live project-wide flag deliberately (see Alternatives:
+projectMembers).
+
+## Current Bytebase behavior
+
+The evidence for Problem 1, in pre-rename terms:
+
+- Three visibility states (`PRIVATE`/`PROJECT_READ`/`PROJECT_WRITE`): one
+ project-wide mode flag per worksheet, no per-user grants.
+- Permissions: `bb.worksheets.create` (the interim audit fix),
+ `bb.worksheets.get` (read shared), `bb.worksheets.list` (granted by no
+ role, called by no UI), `bb.worksheets.manage` (workspace god-mode incl.
+ reading PRIVATE, surfaced by no UI).
+- Creator short-circuits before membership: a user removed from a project
+ keeps editing their shared worksheets there.
+- `PROJECT_READ` write expects a project-scoped `manage` no predefined role
+ grants, contradicting the frontend's own comment.
+
+## Design
+
+### Key decisions
+
+Cited throughout as "decision N"; the sections below carry the mechanics,
+Alternatives the rejected options.
+
+1. **Rename worksheet → saved query** (Naming). The industry-standard term;
+ Snowflake is retiring "worksheet"; and the API is already breaking, so
+ the one-time rename cost (proto, URLs, permissions, i18n, table) is at
+ its cheapest.
+2. **Per-object VIEWER/EDITOR grants to `user:`/`group:`.** The consensus
+ model of all four current-generation peers; the sharer scopes both
+ audience and level — this fixes Problem 2. The real cost: "everyone in
+ the project" is no longer a live flag — it is a group, or a
+ share-with-project snapshot of the project's current principals.
+3. **BigQuery-layered gates: the grant carries content, a search
+ permission gates discovery, running needs database permissions** (G3).
+ Exactly new BigQuery's enforcement — `codeViewer` reads the asset while
+ `dataform.repositories.list` gates listing and `bigquery.jobUser` gates
+ running; here, a VIEWER/EDITOR binding reads/edits,
+ `bb.savedQueries.search` gates `SearchSavedQueries` (per-project), and
+ running always passes the SQL Editor's database grants. The real cost:
+ removing a user from a project ends discovery and run but not
+ explicitly granted content access — the grants themselves are the
+ revocation surface (see Model: Offboarding). The stricter
+ membership-AND-grant conjunction was adopted in an earlier revision and
+ dropped as stricter than any peer (see Alternatives).
+4. **Creator = fixed owner, no transfer** (G4). Scratchpad-grade
+ simplicity: no extra tier, no orphan-guard machinery; the admin backstop
+ and fork-a-copy cover the departed-creator case.
+5. **Admin (`manage`) reads private.** Peer parity (`dataform.admin`,
+ Databricks workspace admins), and what makes incident response and
+ orphan cleanup possible. The real tradeoff: admins can read private
+ drafts — accepted, and made accountable by auditing content reads (see
+ API and authorization: Audit events).
+6. **A purpose-built level policy, not the role-based `IamPolicy` proto.**
+ Per-object access is a *capability* (view/edit), as every peer models
+ it; reusing `IamPolicy` would force per-object pseudo-roles and a
+ resource-level role store. The cost — a second policy shape in the API —
+ is softened by both shapes reducing to *(members, capability)*, so the
+ bindings can be re-expressed as `IamPolicy` later without a data change.
+7. **A `bb.savedQueries.list` auditor permission** (G6). Governance needs
+ grant-independent, cross-project enumeration; `list` is the read-only
+ counterpart to `manage`. It can read all content in scope — that is its
+ purpose — so it is granted deliberately, never in default member roles.
+8. **Hard cutover, no legacy shim.** The feature is UI-owned and the
+ frontend ships in-repo the same release; after the rename, a shim is an
+ entire duplicate service to maintain and secure. The cost: external
+ scripts on `/v1/**/worksheets` break loudly at upgrade, with changelog
+ guidance.
+9. **Deep links only — no anonymous links; authenticated link-grant
+ deferred** (Link sharing). The governance-adjacent peers ship exactly
+ this for queries: the URL carries location, IAM/ACL carries access; an
+ anonymous URL is unattributable, ungoverned egress. Given up: the
+ PopSQL/Metabase-style "anyone with the link" convenience; the
+ Snowflake-style authenticated link-grant waits for demand and slots in
+ later as one more binding principal.
+
+### Model and access rules
+
+A saved query carries a policy of per-object grants; the `creator` is the
+immutable owner; a private saved query has no bindings.
+
+```
+Grant levels: VIEWER (open, read) < EDITOR (+ write content/title/database)
+Principals: user:{email} | group:{email}
+```
+
+The whole model (G1); every RPC gate derives from these. Notation: `u` is
+the caller, `P` a project, `s` a saved query, `s.project` its owning
+project; "holds" means any of `u`'s role bindings — project-level (direct
+or via a group) or workspace-level, with CEL conditions satisfied — grants
+the permission:
+
+```
+admin(u, P) = u holds bb.savedQueries.manage on P -- the dataform.admin backstop
+grant(s, u) = max level (VIEWER|EDITOR) among s.bindings whose principal is in principals(u)
+
+create(u, P) = u holds bb.savedQueries.create on P
+discover(u, P) = u holds bb.savedQueries.search on P -- gates Search, not content
+read(s, u) = admin(u, s.project) OR u == s.creator OR grant(s, u) >= VIEWER
+write(s, u) = admin(u, s.project) OR u == s.creator OR grant(s, u) >= EDITOR
+share(s, u) = admin(u, s.project) OR u == s.creator -- manage the policy
+delete(s, u) = admin(u, s.project) OR u == s.creator
+```
+
+The four role permissions the rules reference (G3–G6) — everything between
+them (who reads, edits, re-shares a *specific* saved query) is that query's
+own bindings:
+
+| Permission | Meaning |
+|---|---|
+| `bb.savedQueries.create` | Create saved queries in the project |
+| `bb.savedQueries.search` | Discover: the per-member Search and folder list (results still filtered to `read(s,u)`) |
+| `bb.savedQueries.list` | Auditor: enumerate/filter in scope (project or `projects/-`), read-only, ignoring grants |
+| `bb.savedQueries.manage` | Admin: read/write/re-share/delete any saved query in scope, incl. private |
+
+There is no `get` permission — bindings decide reads (`bb.worksheets.get`
+is dropped, not renamed). `search` is a dedicated permission rather than a
+ride on `bb.projects.get` (see Alternatives) so custom roles can control
+the saved-query surface independently of project visibility; the decoupled
+combos are API-level shapes — the UI needs `bb.projects.get` to render
+project context, and every predefined role carries both. `list` and
+`manage` can read content in scope — that is their purpose — so neither
+belongs in default member roles (decision 7). Role mapping: every project
+role carries `create` and `search`; `projectOwner` carries project-scoped
+`list` + `manage`; `workspaceAdmin`/`workspaceDBA` carry them
+workspace-scoped. A role granting `manage` must also grant `search` (every
+predefined one does): the IAM-gated `SearchSavedQueries` checks it at the
+interceptor, so a manage-only custom role would pass the CUSTOM handlers
+yet be denied there.
+
+The gates are **layered, exactly as new BigQuery enforces them** (G3): the
+per-object grant carries content access (`codeViewer/Editor` on the asset);
+a dedicated permission gates **discovery** — `SearchSavedQueries`
+requires `bb.savedQueries.search`, the exact `dataform.repositories.list`
+analog (likewise a dedicated listing permission), always per-project (no
+cross-project "shared with me"; no peer has one); and
+**running** always passes the SQL Editor's own database grants, the
+`bigquery.jobUser` analog. A grantee who is not a project member opens the
+saved query by its link — BigQuery's own sharing flow, "grant the role,
+then share the link" — but cannot browse the project or run anything in
+it. Databricks and Snowflake enforce their container structurally (an ACL
+can only name a workspace/account user); BigQuery and this design let a
+grant name any workspace identity, expressing the container through the
+discovery and run gates instead.
+
+**Offboarding.** Removing a user from a project ends discovery and run
+immediately (workspace-wide roles aside — those reach every project by
+design). Explicitly granted content access — and the creator's access
+to their own queries — persists until revoked, and the revocation surface
+is explicit: bindings are enumerable (`ListSavedQueries`, filter by
+`member` or `creator`), strippable via `SetIamPolicy` by the creator or an
+admin, and content reads are audited; an admin can delete a departed
+creator's queries, and workspace deactivation ends everything. This is
+precisely BigQuery's behavior. The audit's Problem-1 complaint was never
+retention itself but *implicit* retention — flag-derived access with no
+grant to see, audit, or revoke.
+
+**Share-with-project is a snapshot.** There is deliberately no derived
+"everyone in the project" principal (see Alternatives); the share dialog's
+*Share with project* shortcut writes the project's current IAM principals —
+its `group:` and `user:` bindings, not an expansion of members — into the
+policy at the chosen level. Snapshots keep group dynamism (a group
+gaining a member propagates, since the entry stores the group reference) but
+not membership dynamism (a principal added to the project later is re-shared
+by the owner, as in every group-based peer). Project bindings carrying a CEL
+`condition` (expiring or scoped access) are **skipped**: a time-bounded
+grant cannot be faithfully frozen into an unconditional one, and for a
+governance product under-granting (the owner re-shares) beats silently
+converting expiring access into permanent access.
+
+**Ownership does not transfer** (G4): the creator alone (plus admins)
+re-shares or deletes. Transfer/co-ownership would add a tier and an
+orphan-guard for a case the admin backstop and fork-a-copy already cover.
+**The admin backstop** (`bb.savedQueries.manage`) matches `dataform.admin`
+and Databricks workspace admins: read/write/re-share/delete anything in
+scope, private included — a deliberate privacy reversal (decision 5) that
+makes orphan cleanup and incident response possible.
+
+### API and authorization
+
+Sharing is a policy on the resource, managed via a
+`GetIamPolicy`/`SetIamPolicy` pair — new BigQuery's shape; Databricks and
+Snowflake likewise keep permissions on a dedicated surface. Because Bytebase
+has no resource-level role store below the project, the policy carries
+capability **levels** grouped by member list, evaluated by the saved-query
+handlers, not central `CheckPermission` (decision 6).
+
+**Auth split.** `CreateSavedQuery`, `SearchSavedQueries`,
+`ListSavedQueries`, and `ListSavedQueryFolders` authorize on a single
+family permission checkable at the interceptor (`create`, `search`,
+`list`, `search`), so they are IAM. Everything else
+decides on the specific query's policy — a per-row predicate — so it is
+CUSTOM and the handler runs the access rules. `SearchSavedQueries` is the
+per-member view (concrete project only); `ListSavedQueries` is the auditor
+view, which is why only it may wildcard `projects/-`.
+
+| Method | Gate |
+|---|---|
+| `CreateSavedQuery` | `bb.savedQueries.create` on project (IAM); creator becomes owner |
+| `SearchSavedQueries` | `bb.savedQueries.search` (IAM) → rows where `read(s,u)`; admin: all |
+| `ListSavedQueries` | `bb.savedQueries.list` (IAM) → all rows matching `filter`; `projects/-` allowed |
+| `GetSavedQuery` | `read(s,u)`; NotFound (not PermissionDenied) when unreadable |
+| `UpdateSavedQuery` | title/content/database: `write(s,u)`; `folder`: creator or admin only |
+| `GetIamPolicy` / `SetIamPolicy` | `read(s,u)` / `share(s,u)` |
+| `DeleteSavedQuery` | `delete(s,u)` |
+| `UpdateSavedQueryStar` | `read(s,u)` — star any readable saved query |
+| `BatchUpdateSavedQueries` | rows the caller may re-file (creator; admin: any); mask limited to `folder` |
+| `ListSavedQueryFolders` | `bb.savedQueries.search` (IAM) → distinct folders of the caller's own rows |
+
+Duplicate/fork needs no RPC: read what you can already see, then
+`CreateSavedQuery` — the copy is yours and private.
+
+**Audit events.** Today's `WorksheetService` carries **no**
+`bytebase.v1.audit` annotations at all (sheet and database services do) —
+this design closes that gap. Audited: `CreateSavedQuery`, `GetSavedQuery`
+(content reads — what makes admin access to others' private queries
+*attributable*, the accountability half of decision 5), `DeleteSavedQuery`,
+`SetIamPolicy` (the share event), `BatchUpdateSavedQueries`, and the
+grant-bypassing `ListSavedQueries`. Deliberately **not** audited:
+`UpdateSavedQuery` — the editor autosaves through it, and per-keystroke
+audit rows drown signal. The accepted cost: content edits are attributed
+only via `creator`/`update_time`, not per-edit events; revisit with
+debounced audit or version history if that ever matters. Search, star,
+folder listing, and `GetIamPolicy` are unaudited read/organization noise.
+
+**Compatibility: hard cutover, no shim** (decision 8). `WorksheetService`
+and the `visibility` field are removed in the release that ships
+`SavedQueryService`; the in-repo frontend ships against the new API in the
+same release. Post-rename,
+a shim is not a deprecated field but an entire second service to maintain
+and secure — for a UI-owned feature. Cost: external worksheet scripts break
+loudly at upgrade, documented in the changelog. Historical audit-log
+entries keep old names as records.
+
+### Storage and query scalability
+
+The policy lives in `saved_query.bindings jsonb` — no separate access
+table. The **stored shape is pinned**: the protojson *array* of
+`Binding` messages, e.g.
+`[{"level": "EDITOR", "members": ["group:[email protected]", "user:[email protected]"]}]`
+— the array must sit at the jsonb root for the `@>` probes below (a wrapped
+`{"bindings": [...]}` would force expression indexes). This deviates from
+the store-a-whole-message payload convention, deliberately; the store layer
+gets its own `SavedQueryBinding` message (store protos never import v1).
+
+The caller's principal set expands cheaply — groups are flat (members are
+users, one hop) and `GetUserGroupsSnapshot` is cached in
+`memberGroupsCache`: `principals(u) = {user:u} ∪ {group:g …}`, typically a
+handful. The list query filters the table directly, one GIN probe per
+principal:
+
+```sql
+-- The search gate already passed at the interceptor. An admin drops the
+-- whole access clause. KEYSET cursor: the last row's (updated_at,
+-- resource_id); the cursor predicate is omitted on the first page.
+SELECT s.* FROM saved_query s
+WHERE s.project = $P
+ AND ( s.creator = $me -- own (incl. private)
+ OR s.bindings @> '[{"members":["user:me"]}]'
+ OR s.bindings @> '[{"members":["group:g1"]}]'
+ OR ... ) -- one @> per principals(u), each GIN-indexed
+ AND (s.updated_at, s.resource_id) < ($cursor_at, $cursor_id)
+ORDER BY s.updated_at DESC, s.resource_id DESC
+LIMIT $n;
+-- "My" adds creator = $me and drops the bindings OR; "Shared" adds creator <> $me.
+```
+
+Honest per-tab costs (G7):
+
+- **My** (`creator = me`): btree `(creator, project, updated_at DESC,
+ resource_id DESC)` — equality on the leading columns plus an
+ index-ordered keyset scan → true `O(page)` at any scale. The same index serves the
+ auditor's cross-project `creator` filter (creator leads; the audit list
+ needs no binding test at all).
+- **Starred**: my rows in `saved_query_star` via its `principal` btree —
+ row existence is the star. Fetch the (naturally small) set, join, drop
+ rows I can no longer read (lazily deleting stale stars), sort.
+ `O(my stars)` — bounded by my own behavior.
+- **Shared with me**: the only tab touching groups — `K+1` GIN probes for
+ `K` groups, BitmapOr'd into my accessible set `S`. Bitmap output is
+ unordered, so each page top-N sorts `S`: `O(S log page)`, **not** pure
+ keyset — the honest cost of the no-extra-table choice, acceptable because `S` is *my*
+ reachable set (tens to hundreds), not the project's total.
+
+Pagination is **keyset, never OFFSET**, on every tab: where the plan is
+index-ordered (My) pages are `O(page)`; where it is bitmap-based (Shared)
+the cursor still keeps pages stable under concurrent writes — no
+skips/duplicates — and caps the sort at top-N. And the expensive move —
+expanding a *group's members* — never happens on any path: policies store
+group references, so a 1,000-member group costs the same as a 3-member one
+and membership changes rewrite nothing.
+
+**GIN churn, stated plainly**: the bindings index sits on the same row as
+the autosaved content; a non-HOT content save re-touches it, and churn can
+bloat it between vacuums. Bounded in practice (large content is TOASTed,
+GIN fastupdate batches, bindings change rarely, saved queries are
+human-edited) — fine at scratchpad scale. **Escape hatch** if ever measured
+otherwise: normalize into `saved_query_access(principal, project,
+saved_query)` — still group references — indexed
+`(principal, project, updated_at DESC)`, turning Shared-with-me into
+per-principal *ordered* seeks (`O(K · page)`) and isolating the ACL index
+from content churn. A pure storage change behind the same API.
+
+### Sharing and organization UX
+
+- Views, all within the current project: **My** (`creator == me`, organized
+ in my folder tree), **Shared** (a binding grants me VIEWER+, flat
+ searchable list), **Starred** (my favorites, own or shared). Nobody
+ fetches a query they have no grant on.
+- The edit-vs-view affordance reads `effective_level` off each row
+ (server-computed, on the resource) — no per-row `GetIamPolicy` fan-out;
+ creator and admin status the UI already knows.
+- Share dialog (creator or admin): add `user:`/`group:` at VIEWER/EDITOR;
+ the picker suggests project members/groups (a non-member grantee opens
+ via link but cannot browse the project or run — see Model). **Share with
+ project** = the snapshot shortcut (Model). Admins
+ get a manage affordance on any query. Duplicate is always available.
+ Later dialog polish (search, suggested principals, per-row revoke) needs
+ no schema or API change — the bindings already carry it.
+
+#### Folders and stars
+
+| | Folders | Star / favorite |
+|---|---|---|
+| BigQuery Studio | Personal root **and** shareable folders; folder permissions **propagate** to contents | — |
+| Databricks | Personal `/Users/<me>` **and** `/Shared`; folder ACL, objects **inherit** it | **Star any asset**, incl. shared-with-you; per-user |
+| PopSQL | Private and shared folders; moving into a shared folder auto-shares | Per-user favorite |
+| Snowflake | Folders private by default, shareable as a whole | Recent / My / Shared views |
+
+Two conclusions: a **star is a per-user marker on anything you can reach**
+(shared items included), and every peer's **shared folders grant access by
+inheritance** — a second ACL surface, which is exactly why they are
+deferred.
+
+- **Stars**: a row in `saved_query_star(saved_query, principal)` — row
+ existence is the star. Star any readable query; my star is invisible to
+ you. Powers the Starred view.
+- **Folders (Phase 1 — personal)**: in every peer a query lives in exactly
+ one folder, set by its owner; you never re-file someone else's item.
+ Storage follows the semantic: the location is the `saved_query.folder`
+ **path column on the object** ("a/b/c", '' = unfiled), set via
+ `UpdateSavedQuery` (creator/admin only — re-filing is organization, not
+ editing), bulk rename/move via `BatchUpdateSavedQueries`. Folders never
+ grant access; a folder is a path on rows, so empty folders cannot exist.
+ Today's per-user organizer re-foldering (everyone re-files everything) is
+ dropped as the outlier. A query shared with you appears in
+ **Shared**/**Starred**, never in your tree.
+- **Folders (Phase 2, when demanded — shared)**: a folder becomes a shared
+ resource carrying the same VIEWER/EDITOR policy shape, its contents
+ inheriting `grant(s) ⊔ grant(folder)` — the peers' team library.
+ Deferred: it adds a folder ACL, inheritance in the rules, and a heavier
+ list query, while per-object sharing already delivers the outcome.
+
+### Link sharing
+
+Three different features hide under "share a link" (survey verified against
+vendor docs; sources below):
+
+| Product | Deep link (URL + normal authz) | Authenticated link-grant ("anyone *here* with the link") | Anonymous public link (secret URL, no sign-in) |
+|---|---|---|---|
+| BigQuery modern | Yes — grant IAM first, *then* share the link | No — "public" is an `allAuthenticatedUsers` IAM **binding**, not a secret URL | No (classic's Public-link tier dies with classic) |
+| Databricks (queries) | Yes — Share dialog copies a link; ACL still decides | No | No for queries (dashboards publish/embed separately — a reporting artifact) |
+| Snowflake (Snowsight) | Yes | **Yes, opt-in**: **account** users with the link get View / View+Run — weaker tiers; running still needs the role | No — sharing is to "users in your account" |
+| PopSQL | Yes | — | **Yes** — public presentation links, results embedded, viewers re-run with variables |
+| Metabase | Yes | — | **Yes** — admin-minted; workspace toggle; admin page lists all links |
+| Redash | Yes | — | **Yes** — secret dashboard URLs on revocable API keys |
+
+The pattern: the governance-adjacent platforms (modern BigQuery,
+Databricks) offer **no access-granting link for queries**; Snowflake's
+link-grant is account-scoped and authenticated; anonymous secret URLs exist
+only in collaboration/BI tools whose artifact is a *result for outward
+consumption*.
+
+**What Bytebase provides (decision 9):**
+
+1. **Deep links — yes.** Stable URL; opening runs `read(s,u)`;
+ NotFound for non-viewers; "Copy link" in the editor. The URL carries
+ *location*, never *access* — exactly the BigQuery/Databricks behavior.
+2. **Authenticated link-grant — deferred behind a workspace policy.**
+ Snowflake's pattern maps onto one more binding principal (an opaque
+ link-token member) — it substitutes only for the *grant*, so a leaked
+ link still reaches only authenticated workspace users, and running
+ still requires database permissions. Off by default; add on demand.
+3. **Anonymous public links — never.** Unattributable access (no identity
+ in the audit log), no revocation short of URL rotation, ungoverned
+ egress of SQL embedding schema and business logic — against the
+ product's first principle. If outward *result*-sharing is ever wanted,
+ it is a separately designed egress surface with its own audit events.
+
+Sources: [Snowflake worksheets](https://docs.snowflake.com/en/user-guide/ui-snowsight-worksheets),
+[Databricks saved queries](https://docs.databricks.com/aws/en/sql/user/queries/),
+[BigQuery manage saved queries](https://docs.cloud.google.com/bigquery/docs/manage-saved-queries),
+[Metabase public links](https://www.metabase.com/docs/latest/embedding/public-links),
+[Redash sharing dashboards](https://redash.io/help/user-guide/dashboards/sharing-dashboards/),
+[PopSQL sharing links](https://docs.popsql.com/docs/sharing-a-link-to-your-query-and-results).
+
+## Alternatives
+
+- **A project-derived `projectMembers` principal** — would re-express the
+ visibility flag exactly, keeping today's project-wide semantic alive.
+ Rejected as a hack:
+ no peer derives a sharing audience from an access policy; it couples the
+ audience to the project IAM graph (adding a project viewer silently
+ widens every project-visible query) and is coarse. The
+ share-with-project snapshot is the honest cost.
+- **Classic-BigQuery-style permission family** (`get`/`update` on roles
+ deciding read/edit of all shared queries) — the deprecated generation of
+ the reference product; the sharer cannot scope who edits. An earlier
+ revision recommended it for proximity to current RBAC; proximity is not a
+ direction.
+- **Keep the mode flag** (status quo) — no path to per-user/per-group
+ sharing; it is Problem 2.
+- **Reuse the `bytebase.v1.IamPolicy` proto per query** — role-based, would
+ force per-object pseudo-roles and invite `CheckPermission` expectations.
+ Both shapes reduce to *(members, capability)*, so bindings can be
+ re-expressed as `IamPolicy` later without a data change.
+- **Full per-object IAM** (grants in the central IAM store, resolved by
+ `CheckPermission`) — the ideal end state; Bytebase has no resource-level
+ binding storage below the project, and building one for scratchpads is
+ disproportionate. The bindings shape lets an IAM-native store absorb it.
+- **Ungated PRIVATE creation** (BigQuery leaves Personal permission-free) —
+ rejected narrowly: principals include service accounts; an explicit
+ `create` keeps the surface auditable at zero UX cost.
+- **Gating discovery on `bb.projects.get`** instead of a dedicated
+ `search` permission — an earlier revision's choice, on the argument that
+ discovery is a reachability check (the handler filters to `read(s,u)`
+ anyway) and a dedicated permission would be granted everywhere
+ `projects.get` is. Reversed: that argument proves too much — it applies
+ equally to `create`, which is kept precisely so custom roles control it
+ independently — and the proxy couples the saved-query surface to a
+ permission customers grant for unrelated reasons, making both
+ "discover without project visibility" and "project visibility without
+ the saved-query surface" inexpressible. A dedicated `search` is also
+ the exact `dataform.repositories.list` analog.
+- **A strict membership conjunction on every access** (`member(u, P) AND
+ grant` — an earlier revision's model): project removal would sever even
+ explicitly granted content access, and a grant to a non-member would sit
+ inert. Dropped as stricter than any peer — BigQuery's object grant
+ carries content (membership gates listing and running), and
+ Databricks/Snowflake need no conjunction only because their principal
+ universe *is* the container. The layered model keeps the offboarding
+ outcome where it matters (discovery and run end with membership) while
+ making residual access explicit and revocable instead of impossible. Its
+ opposite extreme — a global cross-project "shared with me" — was also
+ rejected: discovery stays per-project, as in every peer.
+- **Privacy-preserving admin** (delete-without-read) — used in an earlier
+ revision, dropped for peer parity and workable incident response
+ (decision 5); narrow `manage` back if the privacy guarantee matters more.
+- **Grantable OWNER / transfer** — briefly adopted, removed as overkill: a
+ tier plus orphan-guard for cases the admin backstop and fork already
+ cover. Re-adding an OWNER level later is additive.
+- **A legacy `WorksheetService` shim** (derive `visibility` best-effort,
+ translate legacy writes to snapshot SetIamPolicy) — after the rename the
+ shim is an entire second service to maintain, secure, and audit, for a
+ feature whose real consumer ships in lockstep. Hard cutover instead.