Instance

A Bytebase Instance represents a database server or service registered in a workspace or project. It stores the database engine, network endpoint, and authentication settings Bytebase uses to discover databases, synchronize their schema metadata, and execute authorized SQL. For example, the built-in PostgreSQL Sample Project Instance hosts hr_test. A separately registered shared PostgreSQL instance could host both hr_test and payroll_test. An instance serves a similar purpose to a saved connection in a database client, but also has a scope, environment, and synchronized database metadata. Read-only connections can be configured within the same instance.

​

Instance versus Database

An Instance identifies the server or service and how Bytebase accesses it. A Database identifies a database within that instance to inspect, query, or change. One instance can expose several databases; each database belongs to that instance. In the example above, select Sample Project Instance to manage the server’s connection settings and database discovery. Select hr_test to inspect its schema or propose a change to its tables.

​

What Instance means for each engine

Bytebase uses Instance and Database consistently in the UI, but the corresponding native objects differ: For Oracle, a service name or SID selects the connection destination. A Bytebase database selects an Oracle schema, not a CDB or PDB.

​

Workspace and project instances

Instances have one of two scopes, chosen at registration:

• Workspace instance: managed at workspace level; its databases can belong to different projects.
• Project instance: belongs to one project, as do all of its databases.

The scope cannot be changed later. A project’s Databases page can show databases from both kinds of instance. Its Instances page shows only the instances it owns. Use a workspace instance when a central team manages a shared server and assigns its databases to different projects. Use a project instance when one project should manage the server and all its databases. A project-instance database cannot be transferred to another project independently.

​

How an instance is created

Register an existing server or service; connecting an instance does not provision infrastructure. Workspace Admins and Workspace DBAs register workspace instances under workspace Instances. Project Owners register project instances under their project’s Instances page. Custom roles can grant the same permissions. Click Connect instance, select an engine and environment, enter connection details, test, and save. Bytebase discovers visible databases, filtered by Sync Databases. Project-instance databases join the owning project; workspace-instance databases may need assignment.

​

Use an instance

Open the instance from the appropriate Instances page to inspect its discovered databases, synchronization status, and connection settings. You can also follow the Instance link from a database’s detail page if your role permits it. Bytebase can discover only databases visible to the configured database account and allowed by Sync Databases. If an expected database is missing, the instance operator should check those settings and the latest synchronization result. Connection failures require checking reachability from Bytebase, credentials, TLS, and engine-specific settings. Managing an instance requires instance permissions. A member can have permission to query a database without permission to administer its instance. See Database for target selection and instance connection settings for setup.