Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
docs: design project-scoped instances
p0nyadd5ec3a71d9
diff --git a/CONTEXT.md b/CONTEXT.mdindex 94f0f261f2..bf0e7b8b92 100644--- a/CONTEXT.md+++ b/CONTEXT.md@@ -9,15 +9,23 @@ The top-level collaboration boundary that contains projects, database connection_Avoid_: Project, organization**Project**:-A governance boundary for an application or team's databases. It owns issue workflow, approvals, labels, rollout limits, and database membership.+A governance boundary for an application or team's databases. It can own project instances and owns database membership, issue workflow, approvals, labels, and rollout limits._Avoid_: Workspace, repository, environment**Instance**:-A registered database server, cluster, or service connection that Bytebase syncs and operates against. An instance can contain many databases.+A registered database server, cluster, or service connection that Bytebase syncs and operates against. An instance is registered as either a workspace instance or a project instance, and its scope does not change._Avoid_: Database, environment+**Workspace Instance**:+An instance governed directly by the workspace. Its databases may belong to different projects.+_Avoid_: Project instance, unassigned instance++**Project Instance**:+An instance governed by exactly one project. Every database it contains belongs to that same project.+_Avoid_: Workspace instance, shared instance+**Database**:-A named database inside an instance that Bytebase tracks and assigns to a project. It is the usual target of schema, data, export, and access work.+A named database inside an instance that Bytebase tracks and assigns to a project. In a project instance, it belongs to the instance's project; in a workspace instance, it may be assigned independently._Avoid_: Instance, schema**Environment**:diff --git a/docs/adr/0002-support-workspace-and-project-instances.md b/docs/adr/0002-support-workspace-and-project-instances.mdnew file mode 100644index 0000000000..bd8125aa6a--- /dev/null+++ b/docs/adr/0002-support-workspace-and-project-instances.md@@ -0,0 +1,196 @@+# Support workspace and project instance scopes++Related issue: [BYT-9869](https://linear.app/bytebase/issue/BYT-9869/consider-instance-in-project)++## Context++An instance is currently a workspace resource. Its databases may be assigned to+different projects, which is necessary for shared infrastructure. Dedicated+infrastructure needs a different governance boundary: a project team should be+able to own the connection, credentials, databases, and lifecycle of an entire+server, cluster, or service.++Making every instance project-owned would break the shared-infrastructure model.+Instead, Bytebase supports two mutually exclusive instance scopes.++## Decision++An instance is registered as either:++- a **workspace instance**, governed by the workspace, whose databases may+ belong to different projects; or+- a **project instance**, governed by exactly one non-default project, whose+ databases all belong to that project.++The scope is chosen at creation and is immutable in v1. Existing instances+remain workspace instances. A future v2 may add explicit scope-transfer+semantics.++Only the owning project's plans, releases, database creation, SQL operations,+access grants, and other project-bearing workflows may target a project+instance. Workspace instances remain the sharing mechanism across projects.++### API and resource names++This is an additive extension to the existing v1 `InstanceService`.++| Resource | Workspace instance | Project instance |+| --- | --- | --- |+| Instance | `instances/{instance}` | `projects/{project}/instances/{instance}` |+| Database | `instances/{instance}/databases/{database}` | `projects/{project}/instances/{instance}/databases/{database}` |+| Instance role | `instances/{instance}/roles/{role}` | `projects/{project}/instances/{instance}/roles/{role}` |+| Instance policy | `instances/{instance}/policies/{policy}` | `projects/{project}/instances/{instance}/policies/{policy}` |+| Database metadata | `instances/{instance}/databases/{database}/metadata` | `projects/{project}/instances/{instance}/databases/{database}/metadata` |+| Database catalog | `instances/{instance}/databases/{database}/catalog` | `projects/{project}/instances/{instance}/databases/{database}/catalog` |+| Database policy | `instances/{instance}/databases/{database}/policies/{policy}` | `projects/{project}/instances/{instance}/databases/{database}/policies/{policy}` |+| Changelog | `instances/{instance}/databases/{database}/changelogs/{changelog}` | `projects/{project}/instances/{instance}/databases/{database}/changelogs/{changelog}` |+| Revision | `instances/{instance}/databases/{database}/revisions/{revision}` | `projects/{project}/instances/{instance}/databases/{database}/revisions/{revision}` |++The database schema read endpoints—`schema`, `sdlSchema`, and `schemaString`—also+inherit the complete applicable database prefix. Top-level names never alias+project resources: `instances/{instance}` resolves only a workspace instance.+APIs neither accept nor emit shortened aliases for project resources.++Every API field, filter, target, audit log, activity record, and historical+reference that identifies one of these resources accepts or retains its full+canonical name. Project-scoped references must match the owning project.+Historical references retain the full name after archival or purge.++The canonical `Instance.name` is the only public scope indicator. `Instance`+does not add either `project` or `scope`, avoiding duplicate representations+that could disagree.++Create and list methods use an optional `parent`:++- omitted: use the workspace inferred from request context and preserve the+ existing `/v1/instances` behavior;+- `projects/{project}`: operate on that active, non-default project's instance+ collection.++Methods acting on a specific existing resource derive scope from `name` and do+not add a separate parent. This includes `ListInstanceDatabase`, including its+inline candidate-instance case.++Parentless `ListInstances` returns only workspace instances.+`ListInstances(parent="projects/P")` returns only P's project instances. Its+existing `project` filter may be omitted or equal P; a different project is+contradictory and returns `INVALID_ARGUMENT`. V1 does not support wildcard+collections such as `projects/-/instances`.++Batch sync and update use the same optional collection parent. Every target must+belong to that exact collection; cross-project and cross-scope batches are+rejected in v1.++For project-scoped creation, `parent` is the sole database-assignment source and+`initial_database_project` must be unset. Parentless workspace creation keeps+the existing optional `initial_database_project` behavior.++`Database.project` remains public:++- for a workspace-instance database, it is an independent assignment;+- for a project-instance database, it must equal the project encoded in the+ canonical name.++`ListDatabases(parent="projects/P")` remains a unified project database view. It+returns P's databases whether they are hosted by workspace instances or by P's+project instances.++These collection and resource-name rules follow the distinction in+[AIP-122](https://google.aip.dev/122),+[AIP-132](https://google.aip.dev/132), and+[AIP-133](https://google.aip.dev/133): collection methods identify their parent,+while methods for a specific resource identify it by name.++### Store invariants++The `instance` table gains nullable+`project REFERENCES project(resource_id)`:++- null means workspace instance;+- non-null means project instance.++Existing rows migrate with null. Their names and database assignments do not+change.++Instance resource IDs remain unique across the workspace even though project+instance names are nested. Reusing an ID in another project returns+`ALREADY_EXISTS`; this design does not introduce composite instance identity.++Every newly discovered database in a project instance inherits the instance's+project. Moving such a database to another project is rejected. Store write+paths enforce scope immutability and project/database consistency+transactionally. Bytebase does not add persistent PostgreSQL triggers for these+rules.++V1 does not try to identify duplicate physical servers across scopes. Endpoints+may be aliased, proxied, or tunneled, so only the instance resource ID is used+for uniqueness.++### IAM and policy inheritance++Workspace IAM governs workspace instances. Project IAM governs project+instances and every descendant under their canonical names, including+databases, roles, catalogs, policies, and changelogs. Existing workspace-level+Admin and DBA authority continues across both scopes.++Among built-in project roles, only Project Owner receives instance permissions:+read, create, update, sync, delete, and undelete. Custom project roles may grant+a narrower subset of the existing `bb.instances.*` permissions.++For policy types that support parent inheritance, project-instance resources+follow `project → instance → database`. Existing workspace-wide and environment+policy evaluation remains in force; project ownership cannot bypass enforced+workspace guardrails.++### Lifecycle++Archiving a project makes its project instances unavailable and suspends their+scheduled activity without changing individual instance states. Restoring the+project reveals the prior states and resumes scheduling.++Permanently purging a project permanently deletes its project instances,+databases, and related Bytebase metadata. They are not converted to workspace+instances or moved to the default project.++Directly archiving a project instance leaves its databases assigned to the+owning project. Restoring it reveals them again. Purging it deletes the+databases and related Bytebase metadata. The workspace-instance `force`+behavior that transfers databases to the default project does not apply.++### Availability and limits++Project instances are available in every Bytebase deployment and edition. They+are not Cloud-specific or feature-gated.++Workspace and project instances share the existing workspace-wide instance and+activation limits. Scope does not introduce a separate licensing or capacity+model.++## Considered alternatives++- **Make every instance project-owned.** Rejected because one instance must+ continue to host databases shared by multiple projects.+- **Allow scope transfer in v1.** Deferred because it requires coordinated+ renaming, IAM, lifecycle, database reassignment, and historical-reference+ semantics.+- **Add public `Instance.project` or `Instance.scope`.** Rejected because the+ canonical resource name already identifies scope.+- **Allow short aliases for project resources.** Rejected because+ `instances/{instance}` must continue to identify only workspace resources.+- **Use project-local instance IDs.** Rejected to preserve existing+ workspace-wide identity and avoid a composite-key migration.+- **Enforce invariants with database triggers.** Rejected in favor of+ transactional store-layer enforcement.++## Consequences++- Existing clients and existing instances preserve their workspace behavior.+- Backend resource-name handling and HTTP bindings must support both canonical+ hierarchies for every instance and database descendant.+- Project IAM becomes a truthful ownership boundary for dedicated database+ infrastructure without removing workspace governance.+- Shared and dedicated infrastructure coexist in the same project database+ view.+- Frontend work can follow later with dedicated project instance list, create,+ and detail routes while retaining the empty-project database onboarding+ shortcut.