diff --git a/mintlify/get-started/instance.mdx b/mintlify/get-started/instance.mdx
index 9fc032849..0ddaa9ff1 100644
--- a/mintlify/get-started/instance.mdx
+++ b/mintlify/get-started/instance.mdx
@@ -10,207 +10,206 @@ import ClickHouseConfig from '/snippets/get-started/instance/clickhouse.mdx';
import DatabricksConfig from '/snippets/get-started/instance/databricks.mdx';
import SpannerConfig from '/snippets/get-started/instance/spanner.mdx';
-
-
-Only **Workspace Admin** or **Workspace DBA** role can configure database instance.
+Learn how to connect Bytebase to your database instances, configure authentication, and set up advanced security options.
-
+## Quick Start
-To allow Bytebase to execute operations on behalf the end user, you need to supply Bytebase with the
-connection info for your database instance.
+Navigate to the configuration section for your cloud provider, or start with general configuration options that apply to all databases:
-
-
-
-
+
+
+
+
-## General
-
-### Database Connectivity
-
-- **Docker (standard mode)**: Use `host.docker.internal` for localhost databases. [Learn more](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host)
-- **Docker (--network host)**: Use `127.0.0.1` for localhost databases
-- **Bytebase Cloud**: Whitelist required IP addresses first. See [Cloud Prerequisites](/get-started/cloud#prerequisites)
-
-### Read-Only Connection
-
-
-
-Read-only connection is used in:
-
-1. Restrict SQL Editor to query and export from [read-only data source](/sql-editor/settings/data-source-restriction).
-1. [Export from Export Center](/security/database-permission/export#request-from-export-center)
-
-
-
-To separate from admin connection, you can configure read-only connections once an instance is added.
-
-1. Create a new role with read-only access or a read-replica instance.
-1. Click **Create** or **+** on **Connection info**.
-1. Enter read-only connection info. If this is a read-replica instance, you need to enter its host and port information.
-1. Click **Update** to finish the configuration.
-1. Click **+** to add more, or click trash icon to delete.
+## General Configuration
-
+### Basic Connection
-### SSH tunnel
+Before configuring connection parameters, ensure network connectivity:
-
+**Network Requirements:**
+- Verify network routing between Bytebase and your database instance (e.g., VPN, private networks)
+- Configure firewall rules to allow Bytebase to connect to your database port
+- For cloud databases, add Bytebase to security groups or IP allowlists
+- Bytebase Cloud users: [Whitelist required IPs](/get-started/cloud#prerequisites)
-To protect their databases, some hosting providers block direct remote access. However, they often enable SSH, which allows users to connect to their servers remotely using an SSH client. If you want to connect to a database on one of these servers from Bytebase, you will need to create an SSH tunnel. This will allow you to connect to the database without compromising security.
+**Connection Parameters:**
-
+1. **Host**: Database server address
+ - Docker (standard): Use `host.docker.internal` for localhost databases
+ - Docker (--network host): Use `127.0.0.1` for localhost databases
-1. After filling in the standard database connection information, click **SSH Connection** > **Tunnel + Private Key**.
-2. Fill in the SSH connection information. The **Private Key** is used to authenticate the SSH connection. You can also use a password instead.
- 
-3. Click **Test Connection**. If the connection is successful, click **Create** to create this instance.
+2. **Port**: Database port number (e.g., 5432 for PostgreSQL, 3306 for MySQL)
-### Extra Connection Parameters
+3. **Username & Password**: Database credentials with appropriate permissions
-When connecting to a database instance, you may need to specify additional parameters to customize the connection behavior. Bytebase provides a feature that allows users to define extra parameters for the database connection string directly in the UI.
+Additional parameters vary by database type - see [Database-Specific Guides](#database-specific-guides) for your database's requirements.
-**Supported Database Connection Parameters**
+### Advanced Options
-Below are links to official documentation for configuring connection parameters:
+#### Read-Only Connections
-- **PostgreSQL**: [Connection Parameters](https://www.postgresql.org/docs/current/libpq-connect.html)
-- **Oracle (Go-ORA)**: [Go-ORA Connection Options](https://github.com/sijms/go-ora)
-- **MySQL (Go SQL Driver)**: [Connection Parameters](https://github.com/go-sql-driver/mysql?tab=readme-ov-file#parameters)
-- **Microsoft SQL Server (Go-MSSQL)**: [Connection Options](https://pkg.go.dev/github.com/microsoft/go-mssqldb#section-readme)
+Configure separate read-only connections for enhanced security and performance:
-**Common Connection Parameters**
+
+Read-only connections are used for:
+- SQL Editor queries with [data source restrictions](/sql-editor/settings/data-source-restriction)
+- [Export Center operations](/security/database-permission/export#request-from-export-center)
+
-| Parameter | Description | Example |
-| ----------------- | -------------------------------------------- | --------- |
-| `sslmode` | SSL connection mode (PostgreSQL) | `require` |
-| `connect_timeout` | Timeout for establishing connections | `10` |
-| `readTimeout` | Read timeout for MySQL and MSSQL connections | `30s` |
-| `max_connections` | Maximum number of connections allowed | `100` |
+**Setup Steps:**
+1. Create a read-only database user or configure a read-replica
+2. Click **Create** or **+** on **Connection info**
+3. Enter the read-only connection details
+4. Click **Update** to save
-For a full list of supported parameters, refer to the official database documentation links above.
+
-### External Secret Manager
+#### SSH Tunnel
-
+
-By default, Bytebase stores the database credentials in an obfuscated format in its own meta store.
-You can also instruct Bytebase to retrieve the database credential from an external secret manager.
+Connect to databases behind firewalls using SSH tunneling:
-
+
-1. User tries to access database from Bytebase.
-1. Bytebase calls the external secret manager to exchange the configured key for the database password.
-1. Bytebase retrieves the password and connect the database.
+**Configuration:**
+1. Fill in standard database connection details
+2. Select **SSH Connection** > **Tunnel + Private Key**
+3. Provide SSH connection information:
+ - SSH Host & Port
+ - SSH Username
+ - Private Key or Password
+4. Test connection and click **Create**
-#### HashiCorp Vault
+
-
+#### Connection Parameters
-Bytebase only supports KV v2 engine.
+Customize connection behavior with database-specific parameters:
-
+**Common Parameters:**
-Create the secret in Vault like below:
+| Parameter | Description | Example | Databases |
+|-----------|------------|---------|-----------|
+| `sslmode` | SSL connection mode | `require` | PostgreSQL |
+| `connect_timeout` | Connection timeout | `10` | PostgreSQL, MySQL |
+| `readTimeout` | Read operation timeout | `30s` | MySQL, SQL Server |
+| `max_connections` | Maximum connections | `100` | All |
-- Secret engine name: `secret`
-- Secret path: `bytebase`
-- Secret key: `DB_PASSWORD`
-- Secret: `<>`
+**Database Documentation:**
+- [PostgreSQL Parameters](https://www.postgresql.org/docs/current/libpq-connect.html)
+- [MySQL Parameters](https://github.com/go-sql-driver/mysql#parameters)
+- [SQL Server Parameters](https://pkg.go.dev/github.com/microsoft/go-mssqldb#section-readme)
+- [Oracle Parameters](https://github.com/sijms/go-ora)
- 
+### Security Features
-Configure instance to retrieve database password from vault:
+#### Secret Manager
-- Specify the Vault URL.
+
-- Specify the Vault auth method.
+Store database credentials securely in secret managers instead of Bytebase's internal storage.
- - For [Token](https://developer.hashicorp.com/vault/docs/auth/token), specify the token.
- - For [AppRole](https://developer.hashicorp.com/vault/docs/auth/approle), specify the auth role id and secret id.
+
-- Specify the secret engine name`secret`, secret path `bytebase` and secret key `DB_PASSWORD`.
+**Supported Providers:**
+- **HashiCorp Vault** - Configure below
+- **[AWS Secrets Manager](#aws-secrets-manager)** - See AWS configuration section
+- **[GCP Secret Manager](#gcp-secret-manager)** - See GCP configuration section
+- **Custom API Endpoint** - Configure below
- 
+##### HashiCorp Vault
-#### Custom endpoint
+
+Requires Vault KV v2 engine
+
-
+**Vault Setup:**
+1. Create secret in Vault:
+ - Engine: `secret`
+ - Path: `bytebase`
+ - Key: `DB_PASSWORD`
+ - Value: Your password
-If you have a custom external secret manager, you can supply its API endpoint by enclosing it with the mustache `{{` `}}`, e.g `{{http://example.com/secrets/mydbkey}}`
+
-**Sample request**
+**Bytebase Configuration:**
+1. Enter Vault URL
+2. Choose authentication method:
+ - **[Token](https://developer.hashicorp.com/vault/docs/auth/token)**: Provide access token
+ - **[AppRole](https://developer.hashicorp.com/vault/docs/auth/approle)**: Provide role ID and secret ID
+3. Specify secret location (engine/path/key)
-Usually `mydbkey` is unique for each database and used for exchanging the password for that database.
+
-```bash
-curl "http://example.com/secrets/mydbkey"
-```
+##### Custom API Endpoint
-**Expected response**
+Integrate with custom secret managers using your API:
-Bytebase expects the following JSON response from the external secret manager. The `payload.data` is the
-base64-encoded contents of the database password.
+**Endpoint Format:** `{{http://example.com/secrets/mydbkey}}`
+**Expected Response:**
```json
{
"payload": {
- "data": "xxx"
+ "data": "base64_encoded_password"
}
}
```
-## AWS
+## AWS Configuration
-While creating an RDS or Aurora instance, you can choose to enable IAM authentication.
-
+### RDS/Aurora with IAM Authentication
-### IAM Authentication
+Connect to AWS databases using IAM credentials instead of passwords.
-#### Create IAM policy
+#### Prerequisites
-1. Go to **IAM > Policies** and click **Create policy**.
- 
+Enable IAM authentication when creating your RDS/Aurora instance:
-1. Select `RDS IAM Authentication` for service.
- 
+
-1. Select `connect` permission and `specific` as Resources. Check `Any in this account`.
- 
+#### Setup IAM Policy
-
+1. Go to **IAM > Policies** and click **Create policy**
+ 
- `Any in this account` will mark the resource as
- `arn:aws:rds-db:*:<>:dbuser:*/*`, which contains 3 `*`:
+2. Select `RDS IAM Authentication` for service
+ 
- - 1st \*: any regions
- - 2nd \*: any databases
- - 3rd \*: any database users
+3. Select `connect` permission and `specific` as Resources. Check `Any in this account`
+ 
- This will allow the RDS connect on behalf of all database users in all databases in your account.
- If you want to limit the connection to specific databases, please follow [this doc](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html).
+
+ `Any in this account` will mark the resource as `arn:aws:rds-db:*:<>:dbuser:*/*`, which contains 3 `*`:
+ - 1st *: any regions
+ - 2nd *: any databases
+ - 3rd *: any database users
-
+ This will allow RDS connect on behalf of all database users in all databases in your account.
+ If you want to limit the connection to specific databases, please follow [this doc](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html).
+
-1. Name it `rds-connect` and create this policy.
+4. Name it `rds-connect` and create this policy
-#### Create IAM user
+#### Create IAM User
-1. Go to **IAM > Users** can click **Create user**. Name it `rds-connector`.
+1. Go to **IAM > Users** and click **Create user**. Name it `rds-connector`
-1. Choose Attach policy directly and select the `rds-connect` policy. Click **Next** and then click **Create user**.
+2. Choose **Attach policy directly** and select the `rds-connect` policy. Click **Next** and then click **Create user**
-1. On the user detail page, click **Create access key**.
+3. On the user detail page, click **Create access key**
-1. Choose `Application running outside AWS` and click **Next**.
+4. Choose `Application running outside AWS` and click **Next**
-1. Then you get the **access key** and the **secret access key**.
+5. Then you get the **access key** and the **secret access key**
#### Use IAM Auth in Bytebase
@@ -218,43 +217,32 @@ While creating an RDS or Aurora instance, you can choose to enable IAM authentic
1. Start Bytebase with AWS IAM credentials by passing the AWS environment variables:
```bash
- docker run --init \
+ docker run --init \
-e AWS_ACCESS_KEY_ID=<> \
-e AWS_SECRET_ACCESS_KEY=<> \
-e AWS_REGION=<> \
- --name bytebase \
- --publish 8080:8080 --pull always \
- bytebase/bytebase:latest
+ ...
```
-1. Go to RDS instance detail page, you'll find the **endpoint** and **port**.
+2. Go to RDS instance detail page, you'll find the **endpoint** and **port**
-1. Configure instance connection using `AWS RDS IAM`, create the `bytebase` user with `AWSAuthenticationPlugin` and grant permission.
+3. Configure instance connection using `AWS RDS IAM`, create the `bytebase` user with `AWSAuthenticationPlugin` and grant permissions:
```sql
- CREATE USER bytebase@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
-
- ALTER USER 'bytebase'@'%' REQUIRE SSL;
-
- GRANT ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, CREATE VIEW,
- DELETE, DROP, EVENT, EXECUTE, INDEX, INSERT, PROCESS, REFERENCES,
- SELECT, SHOW DATABASES, SHOW VIEW, TRIGGER, UPDATE, USAGE,
- RELOAD, LOCK TABLES, REPLICATION CLIENT, REPLICATION SLAVE
- /*!80000 , SET_USER_ID */ON *.* to bytebase@'%';
+ -- For MySQL/Aurora MySQL
+ CREATE USER bytebase@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
+ ALTER USER 'bytebase'@'%' REQUIRE SSL;
```
-1. Use the instance endpoint, port and the username `bytebase` to connect the instance.
+4. Use the instance endpoint, port and the username `bytebase` to connect the instance
-### Secrets Manager
+### AWS Secrets Manager
#### Create an IAM user to access the Secrets Manager
-
-It's recommended to create a dedicated IAM user for Bytebase to retrieve the secrets. You only need to do this once
-.
-
+It's recommended to create a dedicated IAM user for Bytebase to retrieve the secrets. You only need to do this once.
Visit [IAM](https://aws.amazon.com/iam/) to create a new IAM user. Name it `bytebase-external-secret`.
@@ -273,16 +261,13 @@ Select `Third-party service` as the use case.
-Optionally set the description tag and in the `Retrieve access keys` screen, record `Access key` and
-`Secret access key`. They will be passed as environment variables when starting Bytebase.
+Optionally set the description tag and in the `Retrieve access keys` screen, record `Access key` and `Secret access key`. They will be passed as environment variables when starting Bytebase.
#### Create secret
-Visit [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) to store a new secret. Select
-`Other type of secret`, and add a key/value pair. The key is `DB_PASSWORD` and the value is your
-database user password.
+Visit [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) to store a new secret. Select `Other type of secret`, and add a key/value pair. The key is `DB_PASSWORD` and the value is your database user password.
@@ -294,58 +279,50 @@ Skip rotation, review and create the secret.
#### Use secret in Bytebase
-Restart Bytebase with the following environment variables
-
-- `AWS_REGION`=`us-east-1`
-- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are the ones you previously created on the IAM user:
-
-```bash
-AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy ./bytebase <>
-```
+Restart Bytebase with the following environment variables:
```bash
docker run --init \
- -e AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy \
- --name bytebase \
- <>
+ -e AWS_REGION=us-east-1 \
+ -e AWS_ACCESS_KEY_ID=xxx \
+ -e AWS_SECRET_ACCESS_KEY=yyy \
+ ...
```
-Go to instance setting, specify `bytebase` as the Secret name and `DB_PASSWORD` as the Secret key.
-These two correspond to the value you created in the AWS Secrets Manager.
+Go to instance setting, specify `bytebase` as the Secret name and `DB_PASSWORD` as the Secret key. These two correspond to the value you created in the AWS Secrets Manager.
-## GCP
+## GCP Configuration
-### IAM Authentication
+### Cloud SQL with IAM Authentication
#### Create a service account
1. Visit [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) to create a new service account `bytebase`.
-1. Grant `Cloud SQL Admin` permission to the service account.
+2. Grant `Cloud SQL Admin` permission to the service account.
-1. After the service account is created, you may view the email for the service account `bytebase@<>.iam.gserviceaccount.com`. Go to **KEYS**.
+3. After the service account is created, you may view the email for the service account `bytebase@<>.iam.gserviceaccount.com`. Go to **KEYS**.
-1. Click **ADD KEY** and then **Create new key**.
+4. Click **ADD KEY** and then **Create new key**.
-1. Choose `JSON` as the key type and click **CREATE**. Keep the downloaded private key file. This will be passed
- as environment variables when starting Bytebase.
+5. Choose `JSON` as the key type and click **CREATE**. Keep the downloaded private key file. This will be passed as environment variables when starting Bytebase.
-1. Go to Cloud SQL database instance detail page, and make sure `cloudsql_iam_authentication` is enabled.
+6. Go to Cloud SQL database instance detail page, and make sure `cloudsql_iam_authentication` is enabled.
-1. Go to **Users** tab, and click **ADD USER ACCOUNT**.
+7. Go to **Users** tab, and click **ADD USER ACCOUNT**.
-1. Select `Cloud IAM` and copy/paste the service account email `bytebase@<>.iam.gserviceaccount.com`.
+8. Select `Cloud IAM` and copy/paste the service account email `bytebase@<>.iam.gserviceaccount.com`.
-1. Then you can get the Cloud SQL IAM user: `bytebase`.
+9. Then you can get the Cloud SQL IAM user: `bytebase`.
#### Use IAM Auth in Bytebase
@@ -353,26 +330,20 @@ These two correspond to the value you created in the AWS Secrets Manager.
1. Start Bytebase with Google IAM credentials by passing `GOOGLE_APPLICATION_CREDENTIALS` as an environment variable:
```bash
- docker run --init \
+ docker run --init \
-e GOOGLE_APPLICATION_CREDENTIALS=<> \
- --name bytebase \
- --publish 8080:8080 --pull always \
- --volume ~/.bytebase/data:/var/opt/bytebase \
- bytebase/bytebase:latest
+ ...
```
-1. Go to SQL overview page, you'll find the **Connection name**, use it as the host. Choose `Google Cloud SQL IAM` along with your user `bytebase` to connect to the database.
+2. Go to SQL overview page, you'll find the **Connection name**, use it as the host. Choose `Google Cloud SQL IAM` along with your user `bytebase` to connect to the database.
-### Secret Manager
+### GCP Secret Manager
#### Create a service account to access the Secret Manager
-
-It's recommended to create a dedicated service account for Bytebase to retrieve the secrets. You only need to do this once
-.
-
+It's recommended to create a dedicated service account for Bytebase to retrieve the secrets. You only need to do this once.
Visit [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) to create a new service account.
@@ -387,8 +358,7 @@ After the service account is created, visit its `KEYS` page and add a new key.
-Choose `JSON` as the key type and create. Keep the downloaded private key file. This will be passed
-as environment variables when starting Bytebase.
+Choose `JSON` as the key type and create. Keep the downloaded private key file. This will be passed as environment variables when starting Bytebase.
@@ -404,30 +374,23 @@ After creation, note the fully qualified secret name.
#### Use secret in Bytebase
-Restart Bytebase by specifying `GOOGLE_APPLICATION_CREDENTIALS`=`private key file` as an environment variable. The
-private key file is the JSON file downloaded before for the service account.
+Restart Bytebase by specifying `GOOGLE_APPLICATION_CREDENTIALS`=`private key file` as an environment variable. The private key file is the JSON file downloaded before for the service account.
-
-If you run Bytebase in docker, you need to put the JSON file under the mounted directory. Otherwise, Bytebase
-won't be able to access the key file.
-
+If you run Bytebase in docker, you need to put the JSON file under the mounted directory. Otherwise, Bytebase won't be able to access the key file.
```bash
docker run --init \
-e GOOGLE_APPLICATION_CREDENTIALS=/var/opt/bytebase/key.json \
- --name bytebase \
- --volume ~/.bytebase/data:/var/opt/bytebase \
- <>
+ ...
```
-Go to instance setting, specify the fully qualified name such as `projects/228712144016/secrets/DB_PASSWORD`
-as the Secret full name.
+Go to instance setting, specify the fully qualified name such as `projects/228712144016/secrets/DB_PASSWORD` as the Secret full name.
-## Azure
+## Azure Configuration
### Entra Managed Identity
@@ -439,16 +402,7 @@ For more information about the credential chain in default Azure credential, ple
1. Enable system assigned managed identity while creating a VM.
-2. Deploy the Bytebase on the VM in Docker:
-
- ```bash
- docker run --init \
- --network=host \
- --name bytebase \
- --pull always \
- --volume ~/.bytebase/data:/var/opt/bytebase \
- bytebase/bytebase:latest
- ```
+2. Deploy the Bytebase on the VM in Docker.
#### Enable Microsoft Entra Authentication in Azure SQL
@@ -460,11 +414,11 @@ For more information about the credential chain in default Azure credential, ple
1. Connect to the Azure SQL database using the Microsoft Entra Admin account.
-2. For each databases desired to be managed by Bytebase, running the following SQL command inside the database to a contained database user:
+2. For each databases desired to be managed by Bytebase, running the following SQL command inside the database to create a contained database user:
```sql
- CREATE USER [] FROM EXTERNAL PROVIDER;
- ALTER ROLE db_owner ADD MEMBER [];
+ CREATE USER [] FROM EXTERNAL PROVIDER;
+ ALTER ROLE db_owner ADD MEMBER [];
```
#### Connect to Azure SQL Database in Bytebase
@@ -475,10 +429,12 @@ For more information about the credential chain in default Azure credential, ple
In this way, Bytebase can only connect to one specific Azure SQL database. To manage multiple Azure SQL databases in one instance inside Bytebase, considering set the VM principal as the Azure SQL Managed Instance Microsoft Entra Admin.
-## Database-Specific Configuration
+## Database-Specific Guides
+
+Configure connection settings for specific database types:
-
+
@@ -500,3 +456,4 @@ In this way, Bytebase can only connect to one specific Azure SQL database. To ma
+