Skip to content

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

docs: design project-scoped instances

p0nyadd5ec3a71d9
diff --git a/CONTEXT.md b/CONTEXT.md
index 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.md
new file mode 100644
index 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.