> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance

> Understand how an Instance represents a database server or service in Bytebase.

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:

| Engine         | Bytebase Instance                                           | Bytebase Database                                                |
| -------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| **PostgreSQL** | PostgreSQL server or cluster                                | Native database containing schemas such as `public`, then tables |
| **MySQL**      | MySQL server                                                | Native database, also called a schema, containing tables         |
| **SQL Server** | SQL Server instance or managed service                      | Native database containing schemas such as `dbo`, then tables    |
| **Oracle**     | Oracle server or service addressed by a service name or SID | User-owned schema containing tables and other objects            |

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.

<img src="https://mintcdn.com/dbx/qVFhwirzSyvmoIAn/content/docs/concepts/instance-scope-3f298dda.svg?fit=max&auto=format&n=qVFhwirzSyvmoIAn&q=85&s=f2e355e0b81aee7764ea1637484a3e4b" alt="A workspace instance hosts databases assigned to different projects; a project instance and all its databases belong to one project" width="840" height="570" data-path="content/docs/concepts/instance-scope-3f298dda.svg" />

## 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](/concepts/database) for target selection and [instance connection settings](/get-started/connect/overview) for setup.
