Skip to main content
Use this guide to choose resource boundaries for your team. For definitions and first actions, start with Bytebase Essentials, including Instance and Database mappings for each database engine.

​
Workspace

A workspace is the top-level administrative space in Bytebase for managing database access and changes. It contains members, projects, instances, environments, and shared settings. Workspace administrators manage membership and shared configuration; project roles govern work within individual projects. A self-hosted deployment has one workspace. In Bytebase Cloud, you create or select a workspace after signing in. See Workspace and projects for an example of the hierarchy.

​
Project

A Project organizes database resources, member permissions, and changes. It can own instances as well as databases. Choose its boundary around the people and applications that should manage that work together. How to structure your projects:
  • Team-based organization — Align projects with your organizational structure. Each team gets their own project, providing clear ownership and accountability for database changes.
  • Application-centric approach — Create projects around applications or services. This works well when multiple teams contribute to a single application or when applications share common database components.
  • Schema-based grouping — Perfect for multi-tenant architectures where you manage hundreds of databases with identical schemas. Group them in one project to roll out changes consistently across all tenants.
  • Environment-specific projects — Though Bytebase provides environment controls, some organizations create separate projects for production versus non-production databases to enforce stricter isolation and different workflows.
Many enterprises layer these approaches. A common pattern is to first divide projects by application or service, then further split them by environment for critical systems that require additional safeguards.
To manage project roles efficiently at scale, create user groups for teams and assign project roles to these groups rather than individual users. You can also integrate with directory services to automatically synchronize group membership with Bytebase.

​
Database Instance

A Bytebase Instance represents a registered database server, cluster, or service. Choose a workspace instance when a central team manages the instance and assigns its databases to different projects. Choose a project instance when one project owns the instance and all its databases. Scope is chosen at registration and cannot be changed afterward. An instance can represent a service backed by several machines. Configure its primary endpoint to reach the writable database, and add a read-only connection within the same instance for replicas.

​
Database

A Database is the named target you inspect, query, or change through an instance. Its native meaning depends on the engine: PostgreSQL and SQL Server databases contain schemas; MySQL treats database and schema as synonyms; Oracle schemas appear as Bytebase databases. Each database belongs to one project. Databases on workspace instances can be assigned independently; those on project instances inherit their owning project. Assignment changes Bytebase ownership, not the database’s physical location.

​
Database Group

A Database Group selects databases by matching names, environments, instances, or labels. Teams commonly group tenant databases with similar schemas and use batch changes across them. Membership does not compare schemas or guarantee that they are identical.

​
Environment

An Environment identifies a database’s purpose, such as testing or production. Databases inherit the instance’s environment unless explicitly assigned their own. Environment policies can apply different SQL Review and rollout requirements. Environment order determines how Rollout stages are organized; assignment does not copy data or provision infrastructure. Make a database change with the UI or through GitOps.