Database

Identify the exact database target before querying data or proposing a database change.

A Bytebase Database is a record of a database managed through a registered Instance. It identifies the database to query or change, belongs to one Project, and displays its synchronized schema metadata. For PostgreSQL, it corresponds to a native database containing schemas and tables; other engines map differently, as shown below.

For example, an HR application’s hr_test and hr_prod are separate database targets, even when their tables have identical names.

The database and its rows remain on the database server. Bytebase discovery records its name and schema information without creating a second copy of the data.

Database versus Instance

An Instance represents a registered server or service and stores how Bytebase accesses it. A Database identifies a database within that instance. Select the database when querying its data or proposing changes to its schema; open the instance to manage connection settings and database discovery.

Database names can repeat across instances. Check the instance and displayed environment; an explicit database environment overrides the instance’s environment.

What Database means for each engine

Engine	What appears as a Bytebase Database	Example table location
PostgreSQL	A native database, containing one or more schemas	Database hr_test, schema public, table employee
MySQL	A native database; MySQL also calls it a schema	Database hr_test, table employee
SQL Server	A native database, containing schemas	Database hr_test, schema dbo, table employee
Oracle	A user-owned schema	Schema HR_TEST, table EMPLOYEE

PostgreSQL and SQL Server schemas, such as public and dbo, are namespaces within a database. MySQL treats database and schema as synonyms.

For Oracle, Bytebase lists user-owned schemas as databases. Selecting HR_TEST sets the current schema on the instance’s service/SID connection; it does not select a PDB. Preserve the discovered name’s case.

See Instance for what the instance represents in each engine.

How a database appears in Bytebase

Discovery: after an instance is connected, Bytebase reads the databases visible to the instance’s database account. It creates a record for each database allowed by the instance’s discovery filter and periodically synchronizes the schema metadata.

Project-instance databases join the owning project. Databases discovered on workspace instances initially belong to the built-in project displayed as Unassigned until an authorized operator assigns them to a team’s project. Reassigning a database changes its management in Bytebase without moving its data. See instance scope for transfer restrictions.

Creation: for supported engines, an operator with instance access and Plan/Issue creation permissions can submit Create Database. Execution creates the physical database. Databases provisioned externally can be discovered afterward.

Inspect a database

1. Open your project’s Databases page and select a database.
2. Check its Instance and Environment in the header to confirm the target.
3. Inspect the database’s tables and schemas. Open a table to see its columns and structure.
4. If you have query access, click SQL Editor to open that database as your target.

In this example, hr_test is in Test on Sample Project Instance. The table list is filtered to public.employee.

The schema view reflects the latest synchronized metadata. If a recent table change is missing, use Sync Database or ask the instance operator to check synchronization. Opening SQL Editor also requires query permission, such as the SQL Editor Read User role.

Continue with the UI Quick Start, Plan, or SQL Review.