Bytebase Essentials

Understand how Bytebase organizes databases and manages changes.

Bytebase connects databases, checks proposed SQL, and manages review and deployment.

Examples use Bytebase’s built-in HR data: the employee table in hr_test. Diagrams extend this example with a hypothetical hr_prod database and Payroll project where needed; these are not created by sample setup.

Workspace and projects

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 across projects.

A self-hosted Bytebase deployment has one workspace. In Bytebase Cloud, you create a workspace or select one you belong to after signing in.

Within a workspace, a Project organizes database resources, member permissions, and changes for an application or team. For example, a company can use one workspace with separate HR and Payroll projects. Each project manages its databases, any project instances, and its change workflow.

The boxes show how Bytebase organizes resources and responsibilities.

Instances, databases, and environments

Bytebase registers a database server or service as an Instance and discovers the Databases it manages. Each database’s Environment identifies its purpose, such as testing or production.

Concept	Meaning	Example
Instance	A database server or service registered in Bytebase, with the settings needed to access it	The Sample Project Instance instance representing a PostgreSQL server
Database	A named database resource reached through an instance and assigned to a project	hr_test, containing public.employee
Environment	A named resource such as Test or Prod, used to select policies and group deployment tasks into stages	hr_test is assigned to Test

The example uses PostgreSQL. What Bytebase lists as a database differs by engine; the engine mapping covers PostgreSQL, MySQL, SQL Server, and Oracle. See Project for project organization and instance scope for instance ownership.

Change workflow

A Plan tracks a change from proposed work and selected targets through deployment. For UI changes, its linked Issue records review and approval, and its Rollout records execution. In GitOps, a Release supplies the SQL files; pull requests and CI checks provide review instead of a Bytebase Issue.

Concept	Purpose
Plan	Manages the change’s work, targets, and lifecycle
Issue	Records a request’s discussion and approval
Release	Packages SQL files into an immutable artifact
Rollout	Records the Plan’s execution stages, database tasks, and results
SQL Review	Checks SQL against the target’s schema and configured rules

Both workflows use Plans and Rollouts to track deployment. Review approval and successful SQL checks prepare a change for execution; verify the task results to confirm that it ran.

Make a database change

With the UI

Write SQL, review checks, and deploy to Test.

With GitOps

Review a migration in Git and deploy through CI.

Verify the task succeeded and the target database has the expected result. For setup, follow Quick Start; for resource configuration, see Organize Resources.