diff --git a/mintlify/docs.json b/mintlify/docs.json
index 43c91b11f..358fd7295 100644
--- a/mintlify/docs.json
+++ b/mintlify/docs.json
@@ -42,8 +42,16 @@
"get-started/self-host/upgrade"
]
},
- "get-started/cloud",
- "get-started/instance"
+ "get-started/cloud"
+ ]
+ },
+ {
+ "group": "Connect Databases",
+ "pages": [
+ "get-started/connect/overview",
+ "get-started/connect/aws",
+ "get-started/connect/azure",
+ "get-started/connect/gcp"
]
},
{
@@ -486,6 +494,10 @@
}
},
"redirects": [
+ {
+ "source": "/get-started/instance",
+ "destination": "/get-started/connect/overview"
+ },
{
"source": "/get-started/self-host",
"destination": "/get-started/self-host-vs-cloud"
diff --git a/mintlify/get-started/connect/aws.mdx b/mintlify/get-started/connect/aws.mdx
new file mode 100644
index 000000000..299a6e692
--- /dev/null
+++ b/mintlify/get-started/connect/aws.mdx
@@ -0,0 +1,214 @@
+---
+title: AWS Database Connections
+description: Configure secure database connections for AWS RDS, Aurora, and other AWS-managed databases
+---
+
+import PostgreSQLConfig from '/snippets/get-started/instance/postgresql.mdx';
+
+Learn how to configure secure connections to AWS-managed databases using IAM authentication, Secrets Manager, and best practices for production deployments.
+
+## Prerequisites: IAM Role Setup
+
+Use attached IAM roles for secure, key-free authentication on EC2 instances. This eliminates the need to manage access keys.
+
+References: [IAM roles for EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) | [IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) | [Using instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)
+
+### Create IAM Role
+
+1. Go to [IAM Console → Roles](https://console.aws.amazon.com/iam/home#/roles)
+2. Click **Create role**
+3. Select trusted entity type: **AWS service** → **EC2**
+4. Attach policies as needed:
+ - For RDS IAM authentication - see [RDS/Aurora section](#rdsaurora-with-iam-authentication)
+ - For Secrets Manager access - see [AWS Secrets Manager section](#aws-secrets-manager)
+5. Name the role: `bytebase-role`
+
+### Attach IAM Role to EC2
+
+**New EC2 Instance:**
+1. Launch instance in [EC2 Console](https://console.aws.amazon.com/ec2/)
+2. In **Advanced details** → **IAM instance profile**: Select `bytebase-role`
+
+**Existing EC2 Instance:**
+1. Select instance → **Actions** → **Security** → **Modify IAM role**
+2. Select `bytebase-role` → **Update IAM role**
+
+Deploy Bytebase on your EC2 instance - credentials are provided automatically through the instance metadata service.
+
+### Alternative: IAM User with Access Keys
+
+
+Use only when running Bytebase outside AWS. See [why to use IAM roles instead of access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#access-keys-alternatives).
+
+
+1. Create an IAM user with required policies
+2. Generate access keys
+3. Set environment variables:
+ ```bash
+ -e AWS_ACCESS_KEY_ID=xxx
+ -e AWS_SECRET_ACCESS_KEY=yyy
+ -e AWS_REGION=us-east-1
+ ```
+
+Reference: [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
+
+## RDS/Aurora with IAM Authentication
+
+
+Prerequisites: [IAM role](#prerequisites-iam-role-setup) with RDS connect permissions.
+
+
+References: [IAM database authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) | [Connecting with IAM](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html)
+
+### Step 1: Configure RDS/Aurora Instance
+
+1. In [RDS Console](https://console.aws.amazon.com/rds/), modify your instance
+2. Enable **IAM database authentication** under Database authentication options
+3. Save changes (SSL is enabled by default)
+
+Reference: [Enabling IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html)
+
+### Step 2: Grant Database Connect Permission
+
+Add this policy to your IAM role to allow RDS IAM authentication:
+
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": "rds-db:connect",
+ "Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:DB_RESOURCE_ID/bytebase"
+ }
+ ]
+}
+```
+
+Replace `REGION`, `ACCOUNT_ID`, and `DB_RESOURCE_ID` with your values. Find DB_RESOURCE_ID in RDS console → Configuration tab. For easier setup, you can use wildcards: `arn:aws:rds-db:*:*:dbuser:*/*`
+
+Reference: [IAM policy examples](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html)
+
+### Step 3: Create Database User
+
+**MySQL/Aurora MySQL:**
+```sql
+CREATE USER 'bytebase'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
+ALTER USER 'bytebase'@'%' REQUIRE SSL;
+GRANT ALL PRIVILEGES ON *.* TO 'bytebase'@'%';
+```
+
+**PostgreSQL/Aurora PostgreSQL:**
+```sql
+CREATE USER bytebase;
+GRANT rds_iam TO bytebase;
+-- Grant appropriate permissions
+```
+
+References: [MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.MySQL) | [PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL)
+
+### Step 4: Connect from Bytebase
+
+1. Click **New Instance** in Bytebase
+2. Configure connection:
+ - **Host:** Your RDS endpoint
+ - **Port:** 3306 (MySQL) or 5432 (PostgreSQL)
+ - **Username:** `bytebase`
+ - **Authentication:** Select `AWS RDS IAM`
+3. Test and save the connection
+
+Bytebase automatically handles token generation and refresh using the EC2 instance profile.
+
+## AWS Secrets Manager
+
+Store database passwords securely in AWS Secrets Manager instead of Bytebase.
+
+
+Prerequisites: [IAM role](#prerequisites-iam-role-setup) with Secrets Manager permissions.
+
+
+### Step 1: Grant Secrets Manager Access
+
+Add this policy to your IAM role to read secrets:
+
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "secretsmanager:GetSecretValue",
+ "secretsmanager:DescribeSecret"
+ ],
+ "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:SECRET_NAME-*"
+ }
+ ]
+}
+```
+
+Replace `REGION`, `ACCOUNT_ID`, and `SECRET_NAME` with your values. For easier setup, you can use wildcards: `arn:aws:secretsmanager:*:*:secret:*`
+
+Reference: [Secrets Manager IAM permissions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html)
+
+### Step 2: Create Secret
+
+1. Go to [AWS Secrets Manager Console](https://console.aws.amazon.com/secretsmanager/)
+2. Click **Store a new secret**
+3. Select **Other type of secret**
+4. Add key/value pair: Key = `DB_PASSWORD`, Value = your password
+5. Name the secret (e.g., `bytebase-db-password`)
+6. Complete creation and note the ARN
+
+Reference: [Creating secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)
+
+### Step 3: Configure in Bytebase
+
+1. In your database instance settings, find the password field
+2. Click the key icon to use external secret
+3. Select **AWS Secrets Manager**
+4. Enter:
+ - **Secret Name:** Your secret name from Step 2
+ - **Secret Key:** `DB_PASSWORD`
+5. Test connection and save
+
+## Database-Specific Configuration
+
+For specific database types running on AWS, see their configuration guides:
+
+
+
+
+
+
+ See the PostgreSQL configuration above, with IAM authentication enabled as described in this guide.
+
+
+ Follow the MySQL configuration with IAM authentication enabled as described in this guide.
+
+
+
+## Best Practices
+
+1. **Use IAM Roles over Access Keys**: Always prefer IAM roles when running on EC2
+2. **Enable SSL/TLS**: All AWS database services support encrypted connections
+3. **Use Secrets Manager**: Centralize password management with automatic rotation
+4. **Follow Least Privilege**: Grant only necessary permissions to IAM roles
+5. **Monitor Access**: Use CloudTrail to audit database access patterns
+
+## Troubleshooting
+
+### Connection Timeout
+- Verify security group rules allow traffic on database port
+- Check VPC routing and subnet configuration
+- Ensure database is publicly accessible or use VPN/bastion host
+
+### IAM Authentication Failed
+- Verify IAM role has correct `rds-db:connect` permissions
+- Check database user was created with correct authentication method
+- Ensure SSL is enabled for the connection
+
+### Secrets Manager Access Denied
+- Verify IAM role has `secretsmanager:GetSecretValue` permission
+- Check secret ARN matches the policy resource
+- Ensure secret exists in the correct region
\ No newline at end of file
diff --git a/mintlify/get-started/connect/azure.mdx b/mintlify/get-started/connect/azure.mdx
new file mode 100644
index 000000000..bbae5abdf
--- /dev/null
+++ b/mintlify/get-started/connect/azure.mdx
@@ -0,0 +1,208 @@
+---
+title: Azure Database Connections
+description: Configure secure database connections for Azure SQL Database and Azure-managed databases
+---
+
+Learn how to configure secure connections to Azure-managed databases using Managed Identity authentication and best practices for production deployments.
+
+## Azure SQL with Managed Identity Authentication
+
+This guide demonstrates the most secure method for connecting to Azure SQL Database and Azure SQL Managed Instance using VM-attached managed identities, eliminating the need to manage credentials or connection strings.
+
+For alternative authentication methods and detailed configuration options, refer to:
+- [Azure SQL authentication methods overview](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-overview)
+- [Managed identities for Azure resources](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)
+- [Configure Azure AD authentication for SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-configure)
+- [Connect to Azure SQL with managed identity](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-azure-ad-user-assigned-managed-identity)
+
+### Step 1: Create Azure VM with System-Assigned Managed Identity
+
+1. **Create VM with Managed Identity**
+ - Go to [Azure Portal → Virtual Machines](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.Compute%2FVirtualMachines)
+ - Click **Create** → **Azure virtual machine**
+ - Configure VM settings as needed
+ - Under **Management** tab:
+ - Enable **System assigned managed identity**: Set to **On**
+ - Complete VM creation
+
+ > **Security Best Practice:** System-assigned managed identities are automatically managed by Azure and tied to the VM lifecycle. This eliminates credential management and reduces security risks. Learn more: [Managed identity best practices](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/managed-identity-best-practice-recommendations)
+
+2. **Deploy Bytebase on the VM**
+
+ Deploy Bytebase on your Azure VM. The VM's managed identity is automatically available - no credential configuration needed.
+
+### Step 2: Configure Azure SQL Database
+
+1. **Enable Microsoft Entra Authentication**
+ - Navigate to your Azure SQL Server in [Azure Portal](https://portal.azure.com)
+ - Go to **Settings** → **Microsoft Entra ID**
+ - Click **Set admin** and select an Entra admin account
+ - Click **Save** to enable Entra authentication
+
+ Reference: [Configure Entra authentication for Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-configure)
+
+2. **Grant Database Access to Managed Identity**
+ - Note your VM's managed identity name (same as VM name)
+ - Connect to Azure SQL using the Entra admin account
+ - Run the following for each database:
+
+ ```sql
+ -- Create user for the VM's managed identity
+ CREATE USER [your-vm-name] FROM EXTERNAL PROVIDER;
+
+ -- Grant appropriate permissions (adjust as needed)
+ ALTER ROLE db_datareader ADD MEMBER [your-vm-name];
+ ALTER ROLE db_datawriter ADD MEMBER [your-vm-name];
+ ALTER ROLE db_ddladmin ADD MEMBER [your-vm-name];
+
+ -- For full database management in Bytebase:
+ ALTER ROLE db_owner ADD MEMBER [your-vm-name];
+ ```
+
+ > **Production Best Practice:** Follow the principle of least privilege. Grant only the minimum permissions required for your use case. See [Azure SQL Database permissions](https://learn.microsoft.com/en-us/azure/azure-sql/database/logins-create-manage).
+
+### Step 3: Connect from Bytebase
+
+1. Access Bytebase on your VM (typically `http://localhost:5678`)
+2. Click **New Instance**
+3. Configure the connection:
+ - **Host:** Your Azure SQL server name (e.g., `yourserver.database.windows.net`)
+ - **Port:** 1433
+ - **Database:** Target database name
+ - **Authentication:** Select `Azure Default Credential`
+4. Test and save the connection
+
+Bytebase automatically uses the VM's managed identity through Azure's Instance Metadata Service (IMDS) for authentication.
+
+
+**Advantages of this approach:**
+- No passwords or connection strings to manage
+- Automatic credential rotation handled by Azure
+- Enhanced security through Azure RBAC
+- Simplified compliance and auditing
+
+For troubleshooting, see [Troubleshoot managed identity authentication](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-azure-ad-user-assigned-managed-identity#troubleshooting).
+
+
+### Alternative: User-Assigned Managed Identity
+
+For more granular control or cross-resource scenarios:
+
+1. **Create User-Assigned Managed Identity**
+ - Go to [Managed Identities](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.ManagedIdentity%2FuserAssignedIdentities)
+ - Create a new identity with a descriptive name
+ - Assign it to your VM under **Settings** → **Identity** → **User assigned**
+
+2. **Configure Database Access**
+ ```sql
+ CREATE USER [managed-identity-name] FROM EXTERNAL PROVIDER;
+ ALTER ROLE db_owner ADD MEMBER [managed-identity-name];
+ ```
+
+3. **Set Environment Variable** (if using multiple identities)
+ ```bash
+ export AZURE_CLIENT_ID=
+ ```
+
+Reference: [User-assigned managed identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities)
+
+## Azure Database for PostgreSQL
+
+### Entra ID Authentication
+
+1. **Enable Entra Authentication**
+ - In Azure Portal, navigate to your PostgreSQL server
+ - Go to **Authentication** → **Active Directory admin**
+ - Set an Entra admin and save
+
+2. **Create Database User**
+ Connect as the Entra admin and run:
+ ```sql
+ -- For system-assigned managed identity
+ CREATE ROLE "your-vm-name" LOGIN;
+ GRANT ALL PRIVILEGES ON DATABASE yourdb TO "your-vm-name";
+ ```
+
+3. **Connect from Bytebase**
+ - **Host:** Your PostgreSQL server name
+ - **Port:** 5432
+ - **Username:** VM name (for system-assigned identity)
+ - **Authentication:** Select `Azure Default Credential`
+
+Reference: [Azure Database for PostgreSQL Entra authentication](https://learn.microsoft.com/en-us/azure/postgresql/single-server/concepts-azure-ad-authentication)
+
+## Azure Database for MySQL
+
+### Entra ID Authentication
+
+1. **Enable Entra Authentication**
+ - Navigate to your MySQL server in Azure Portal
+ - Go to **Active Directory admin**
+ - Set an Entra admin
+
+2. **Create Database User**
+ ```sql
+ CREATE AADUSER 'your-vm-name';
+ GRANT ALL PRIVILEGES ON *.* TO 'your-vm-name';
+ ```
+
+3. **Connect from Bytebase**
+ - **Host:** Your MySQL server name
+ - **Port:** 3306
+ - **Username:** VM name
+ - **Authentication:** Select `Azure Default Credential`
+
+Reference: [Azure Database for MySQL Entra authentication](https://learn.microsoft.com/en-us/azure/mysql/single-server/concepts-azure-ad-authentication)
+
+## Private Endpoints and VNet Integration
+
+For enhanced security using private endpoints:
+
+### Configure Private Endpoint
+
+1. **Create Private Endpoint**
+ - Navigate to your database resource
+ - Go to **Networking** → **Private endpoint connections**
+ - Click **+ Private endpoint**
+ - Select your VNet and subnet
+ - Complete the configuration
+
+2. **Update DNS**
+ - Use Azure Private DNS zones for automatic resolution
+ - Or manually configure DNS for the private endpoint
+
+3. **Connect from Bytebase**
+ - Deploy Bytebase in the same VNet or peered VNet
+ - Use the private endpoint DNS name for connection
+
+Reference: [Private endpoints for Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/private-endpoint-overview)
+
+## Best Practices
+
+1. **Use Managed Identities**: Eliminate password management overhead
+2. **Enable Private Endpoints**: Restrict database access to your VNet
+3. **Follow Least Privilege**: Grant minimal required permissions
+4. **Enable Auditing**: Use Azure SQL Auditing for compliance
+5. **Use Azure Key Vault**: For scenarios requiring password storage
+
+## Troubleshooting
+
+### Authentication Failed
+- Verify managed identity is properly assigned to VM
+- Check database user was created with `FROM EXTERNAL PROVIDER`
+- Ensure Entra authentication is enabled on the database
+
+### Connection Timeout
+- Verify network security group rules
+- Check VNet and subnet configuration
+- Ensure database firewall rules allow your IP
+
+### Private Endpoint Issues
+- Verify DNS resolution for private endpoint
+- Check VNet peering if using multiple VNets
+- Ensure network security allows traffic
+
+### Managed Identity Not Working
+- Restart VM after enabling managed identity
+- Check Azure RBAC assignments
+- Verify IMDS endpoint is accessible from VM
\ No newline at end of file
diff --git a/mintlify/get-started/connect/gcp.mdx b/mintlify/get-started/connect/gcp.mdx
new file mode 100644
index 000000000..2ab8439c0
--- /dev/null
+++ b/mintlify/get-started/connect/gcp.mdx
@@ -0,0 +1,208 @@
+---
+title: GCP Database Connections
+description: Configure secure database connections for Cloud SQL and other GCP-managed databases
+---
+
+import PostgreSQLConfig from '/snippets/get-started/instance/postgresql.mdx';
+import SpannerConfig from '/snippets/get-started/instance/spanner.mdx';
+
+Learn how to configure secure connections to GCP-managed databases using service account authentication, Secret Manager, and best practices for production deployments.
+
+## Prerequisites: Service Account Setup
+
+Use attached service accounts for secure, key-free authentication on:
+- **GCE** - VMs with attached service accounts
+- **GKE** - Pods with Workload Identity
+
+References: [Service accounts](https://cloud.google.com/iam/docs/service-account-overview) | [Best practices](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys) | [ADC](https://cloud.google.com/docs/authentication/application-default-credentials)
+
+### Create Service Account
+
+1. Go to [IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
+2. Create service account named `bytebase`
+3. Grant roles as needed:
+ - `Cloud SQL Client` and `Cloud SQL Instance User` - for Cloud SQL
+ - `Secret Manager Secret Accessor` - for Secret Manager
+4. Note the email: `bytebase@PROJECT_ID.iam.gserviceaccount.com`
+
+### Attach Service Account
+
+**Option A: GCE VM**
+1. Create VM in [Compute Engine](https://console.cloud.google.com/compute/instances)
+2. Set service account: `bytebase@PROJECT_ID.iam.gserviceaccount.com`
+3. Set access scopes: "Allow full access to all Cloud APIs"
+
+**Option B: GKE with Workload Identity**
+```bash
+# Create Kubernetes service account
+kubectl create serviceaccount bytebase-ksa
+
+# Bind to Google service account
+kubectl annotate serviceaccount bytebase-ksa \
+ iam.gke.io/gcp-service-account=bytebase@PROJECT_ID.iam.gserviceaccount.com
+
+# Allow impersonation
+gcloud iam service-accounts add-iam-policy-binding bytebase@PROJECT_ID.iam.gserviceaccount.com \
+ --role roles/iam.workloadIdentityUser \
+ --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/bytebase-ksa]"
+```
+
+Reference: [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
+
+Deploy Bytebase on your resource - credentials are provided automatically.
+
+### Alternative: Service Account Keys
+
+
+Use only when running Bytebase outside GCP. See [why to avoid service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#avoid).
+
+
+1. Create a service account with required roles
+2. Download the JSON key file
+3. Set environment variable:
+ ```bash
+ -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+ ```
+
+Reference: [Service account keys authentication](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key)
+
+## Cloud SQL with IAM Authentication
+
+
+Prerequisites: [Service account](#prerequisites-service-account-setup) with Cloud SQL roles.
+
+
+References: [IAM authentication](https://cloud.google.com/sql/docs/mysql/iam-authentication) | [Configure instances](https://cloud.google.com/sql/docs/mysql/create-edit-iam-instances)
+
+### Step 1: Configure Cloud SQL Instance
+
+1. In [Cloud SQL](https://console.cloud.google.com/sql/instances), edit your instance
+2. Add flag: `cloudsql_iam_authentication` = `on`
+3. Save (SSL is enabled by default)
+
+### Step 2: Add Service Account User
+
+**Using gcloud:**
+```bash
+gcloud sql users create bytebase@PROJECT_ID.iam.gserviceaccount.com \
+ --instance=INSTANCE_NAME \
+ --type=cloud_iam_service_account
+```
+
+**Using Console:**
+Instance → Users → Add User Account → Cloud IAM → Enter service account email
+
+References: [MySQL](https://cloud.google.com/sql/docs/mysql/add-manage-iam-users) | [PostgreSQL](https://cloud.google.com/sql/docs/postgres/add-manage-iam-users)
+
+### Step 3: Connect from Bytebase
+
+1. Click **New Instance** in Bytebase
+2. Configure connection details:
+ - **Host:** Your Cloud SQL connection name (`PROJECT_ID:REGION:INSTANCE_ID`)
+ - Find this in Cloud SQL console → Instance details
+ - **Port:** 3306 (MySQL) or 5432 (PostgreSQL)
+ - **Username:**
+ - MySQL: `bytebase` (service account name only)
+ - PostgreSQL: `bytebase@PROJECT_ID.iam` (with project ID)
+ - **Authentication:** Select `Google Cloud SQL IAM`
+3. Click **Test Connection** then **Create**
+
+## GCP Secret Manager
+
+Store database passwords securely in Google Cloud Secret Manager instead of Bytebase.
+
+
+Prerequisites: [Service account](#prerequisites-service-account-setup) with `Secret Manager Secret Accessor` role.
+
+
+### Step 1: Create Secret
+
+1. Go to [Secret Manager Console](https://console.cloud.google.com/security/secret-manager)
+2. Click **Create Secret**
+3. Enter secret name (e.g., `db-password`) and your database password as value
+4. Click **Create** and note the resource name: `projects/PROJECT_ID/secrets/SECRET_NAME`
+
+### Step 2: Configure in Bytebase
+
+1. In your database instance settings, find the password field
+2. Click the key icon to use external secret
+3. Select **GCP Secret Manager**
+4. Enter the secret resource name from Step 1
+5. Test connection and save
+
+## Private IP and VPC Peering
+
+For Cloud SQL instances using private IP:
+
+### Step 1: Configure VPC Peering
+
+1. Enable Service Networking API
+2. Reserve IP range for services:
+ ```bash
+ gcloud compute addresses create google-managed-services-default \
+ --global \
+ --purpose=VPC_PEERING \
+ --prefix-length=16 \
+ --network=default
+ ```
+3. Create private connection:
+ ```bash
+ gcloud services vpc-peerings connect \
+ --service=servicenetworking.googleapis.com \
+ --ranges=google-managed-services-default \
+ --network=default
+ ```
+
+Reference: [Private IP configuration](https://cloud.google.com/sql/docs/mysql/configure-private-ip)
+
+### Step 2: Connect from Bytebase
+
+1. Deploy Bytebase in the same VPC or a peered VPC
+2. Use the private IP address for the Cloud SQL instance
+3. Configure connection as normal with private IP
+
+## Database-Specific Configuration
+
+For specific database types running on GCP:
+
+
+
+
+
+
+ Follow standard MySQL configuration with IAM authentication enabled as described above.
+
+
+
+
+
+
+## Best Practices
+
+1. **Use Service Accounts over Keys**: Always prefer attached service accounts
+2. **Enable Private IP**: Use VPC peering for enhanced security
+3. **Use Secret Manager**: Centralize password management
+4. **Follow Least Privilege**: Grant only necessary IAM roles
+5. **Enable Audit Logging**: Monitor database access with Cloud Audit Logs
+
+## Troubleshooting
+
+### Connection Refused
+- Verify Cloud SQL instance allows connections from your IP/network
+- Check authorized networks configuration
+- Ensure VPC peering is properly configured for private IP
+
+### IAM Authentication Failed
+- Verify service account has `Cloud SQL Instance User` role
+- Check database user was created with correct type
+- Ensure `cloudsql_iam_authentication` flag is enabled
+
+### Secret Manager Access Denied
+- Verify service account has `Secret Manager Secret Accessor` role
+- Check secret resource name is correct
+- Ensure secret exists in the correct project
+
+### Private IP Connection Issues
+- Verify VPC peering is active
+- Check firewall rules allow traffic
+- Ensure Bytebase is deployed in the correct VPC
\ No newline at end of file
diff --git a/mintlify/get-started/connect/overview.mdx b/mintlify/get-started/connect/overview.mdx
new file mode 100644
index 000000000..b365228f1
--- /dev/null
+++ b/mintlify/get-started/connect/overview.mdx
@@ -0,0 +1,183 @@
+---
+title: Overview
+description: Connect Bytebase to your databases - from basic setup to cloud-native authentication
+---
+
+import PostgreSQLConfig from '/snippets/get-started/instance/postgresql.mdx';
+import OracleConfig from '/snippets/get-started/instance/oracle.mdx';
+import SnowflakeConfig from '/snippets/get-started/instance/snowflake.mdx';
+import MongoDBConfig from '/snippets/get-started/instance/mongodb.mdx';
+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';
+
+Learn how to connect Bytebase to your database instances and configure basic connection settings.
+
+## Quick Start
+
+
+
+ RDS, Aurora with IAM auth
+
+
+ Cloud SQL, Spanner with service accounts
+
+
+ Azure SQL with managed identity
+
+
+
+## Basic Connection
+
+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)
+
+**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
+
+2. **Port**: Database port number (e.g., 5432 for PostgreSQL, 3306 for MySQL)
+
+3. **Username & Password**: Database credentials with appropriate permissions
+
+Additional parameters vary by database type - see the database-specific guides below.
+
+## Advanced Connection Options
+
+### Read-Only Connections
+
+Configure separate read-only connections for enhanced security and performance. 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)
+
+**Setup:**
+1. Create a read-only database user or configure a read-replica
+2. In Bytebase, click **+** next to **Connection Info**
+3. Enter the read-only connection details
+4. Save the configuration
+
+### SSH Tunnel
+
+
+
+Use SSH tunneling to connect through a bastion host when your database is behind a firewall or in a private network.
+
+**Setup:**
+1. Enter your database connection details
+2. Enable **SSH Connection** and select **Tunnel + Private Key**
+3. Configure SSH settings:
+ - **SSH Host**: Bastion host address
+ - **SSH Port**: SSH port (typically 22)
+ - **SSH User**: Username for SSH authentication
+ - **Private Key** or **Password**: SSH credentials
+4. Test and save the connection
+
+### Connection Parameters
+
+Customize connection behavior with database-specific parameters:
+
+| 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 |
+
+**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)
+
+### Secret Manager Integration
+
+
+
+Never store database passwords in Bytebase. Use your existing secret manager for automatic rotation, compliance, and centralized control.
+
+**Key benefits:**
+- Meet SOC2/HIPAA compliance requirements
+- Automatic password rotation without downtime
+- Complete audit trail of credential access
+- Centralized management across all systems
+
+**Supported integrations:**
+
+- **[AWS Secrets Manager](/get-started/connect/aws#aws-secrets-manager)** - For AWS deployments
+- **[GCP Secret Manager](/get-started/connect/gcp#gcp-secret-manager)** - For GCP deployments
+- **HashiCorp Vault** - Enterprise secret management
+- **Custom API Endpoint** - Custom integrations
+
+#### HashiCorp Vault
+
+
+Requires Vault KV v2 engine
+
+
+**Vault Setup:**
+1. Create secret in Vault:
+ - Engine: `secret`
+ - Path: `bytebase`
+ - Key: `DB_PASSWORD`
+
+**Bytebase Configuration:**
+1. Enter Vault URL
+2. Choose authentication: Token or AppRole
+3. Specify secret location
+
+#### Custom API Endpoint
+
+**Endpoint Format:** `{{http://example.com/secrets/mydbkey}}`
+
+**Expected Response:**
+```json
+{
+ "payload": {
+ "data": "base64_encoded_password"
+ }
+}
+```
+
+## Database-Specific Guides
+
+Configure connection settings for specific database types:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Next Steps
+
+
+
+ Configure IAM authentication and cloud-specific features
+
+
+ Best practices for production deployments
+
+
\ No newline at end of file
diff --git a/mintlify/get-started/instance.mdx b/mintlify/get-started/instance.mdx
deleted file mode 100644
index e6ae52e49..000000000
--- a/mintlify/get-started/instance.mdx
+++ /dev/null
@@ -1,565 +0,0 @@
----
-title: Connect Your Database
----
-
-import PostgreSQLConfig from '/snippets/get-started/instance/postgresql.mdx';
-import OracleConfig from '/snippets/get-started/instance/oracle.mdx';
-import SnowflakeConfig from '/snippets/get-started/instance/snowflake.mdx';
-import MongoDBConfig from '/snippets/get-started/instance/mongodb.mdx';
-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';
-
-Learn how to connect Bytebase to your database instances, configure authentication, and set up advanced security options.
-
-## Quick Start
-
-Navigate to the configuration section for your cloud provider, or start with general configuration options that apply to all databases:
-
-
-
-
-
-
-
-
-## General Configuration
-
-### Basic Connection
-
-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)
-
-**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
-
-2. **Port**: Database port number (e.g., 5432 for PostgreSQL, 3306 for MySQL)
-
-3. **Username & Password**: Database credentials with appropriate permissions
-
-Additional parameters vary by database type - see [Database-Specific Guides](#database-specific-guides) for your database's requirements.
-
-### Read-Only Connections
-
-Configure separate read-only connections for enhanced security and performance. 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)
-
-**Setup:**
-1. Create a read-only database user or configure a read-replica
-2. In Bytebase, click **+** next to **Connection Info**
-3. Enter the read-only connection details
-4. Save the configuration
-
-### SSH Tunnel
-
-
-
-Use SSH tunneling to connect through a bastion host or jump server when your database is behind a firewall, in a private network, or requires specific security policies for access. This is common for databases in different VPCs or restricted network segments.
-
-**Setup:**
-1. Enter your database connection details as usual
-2. Enable **SSH Connection** and select **Tunnel + Private Key**
-3. Configure SSH tunnel settings:
- - **SSH Host**: Bastion host or jump server address
- - **SSH Port**: SSH port (typically 22)
- - **SSH User**: Username for SSH authentication
- - **Private Key** or **Password**: SSH authentication credentials
-4. Test the connection and save
-
-### Connection Parameters
-
-Customize connection behavior with database-specific parameters:
-
-**Common Parameters:**
-
-| 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 |
-
-**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)
-
-### Secret Manager
-
-
-
-Integrate with external secret managers for centralized credential management. Use this for corporate compliance, automatic password rotation, or when you prefer not to store credentials directly in Bytebase.
-
-**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
-
-
-Requires Vault KV v2 engine
-
-
-**Vault Setup:**
-1. Create secret in Vault:
- - Engine: `secret`
- - Path: `bytebase`
- - Key: `DB_PASSWORD`
- - Value: Your password
-
-**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)
-
-#### Custom API Endpoint
-
-Integrate with custom secret managers using your API:
-
-**Endpoint Format:** `{{http://example.com/secrets/mydbkey}}`
-
-**Expected Response:**
-```json
-{
- "payload": {
- "data": "base64_encoded_password"
- }
-}
-```
-
-## AWS Configuration
-
-### Prerequisites: IAM Role Setup
-
-Use attached IAM roles for secure, key-free authentication on EC2 instances. This eliminates the need to manage access keys.
-
-References: [IAM roles for EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) | [IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) | [Using instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)
-
-#### Create IAM Role
-
-1. Go to [IAM Console → Roles](https://console.aws.amazon.com/iam/home#/roles)
-2. Click **Create role**
-3. Select trusted entity type: **AWS service** → **EC2**
-4. Attach policies as needed:
- - For RDS IAM authentication - see [RDS/Aurora section](#rdsaurora-with-iam-authentication)
- - For Secrets Manager access - see [AWS Secrets Manager section](#aws-secrets-manager)
-5. Name the role: `bytebase-role`
-
-#### Attach IAM Role to EC2
-
-**New EC2 Instance:**
-1. Launch instance in [EC2 Console](https://console.aws.amazon.com/ec2/)
-2. In **Advanced details** → **IAM instance profile**: Select `bytebase-role`
-
-**Existing EC2 Instance:**
-1. Select instance → **Actions** → **Security** → **Modify IAM role**
-2. Select `bytebase-role` → **Update IAM role**
-
-Deploy Bytebase on your EC2 instance - credentials are provided automatically through the instance metadata service.
-
-#### Alternative: IAM User with Access Keys
-
-
-Use only when running Bytebase outside AWS. See [why to use IAM roles instead of access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#access-keys-alternatives).
-
-
-1. Create an IAM user with required policies
-2. Generate access keys
-3. Set environment variables:
- ```bash
- -e AWS_ACCESS_KEY_ID=xxx
- -e AWS_SECRET_ACCESS_KEY=yyy
- -e AWS_REGION=us-east-1
- ```
-
-Reference: [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
-
-### RDS/Aurora with IAM Authentication
-
-
-Prerequisites: [IAM role](#prerequisites-iam-role-setup) with RDS connect permissions.
-
-
-References: [IAM database authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) | [Connecting with IAM](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html)
-
-#### Step 1: Configure RDS/Aurora Instance
-
-1. In [RDS Console](https://console.aws.amazon.com/rds/), modify your instance
-2. Enable **IAM database authentication** under Database authentication options
-3. Save changes (SSL is enabled by default)
-
-Reference: [Enabling IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html)
-
-#### Step 2: Grant Database Connect Permission
-
-Add this policy to your IAM role to allow RDS IAM authentication:
-
-```json
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": "rds-db:connect",
- "Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:DB_RESOURCE_ID/bytebase"
- }
- ]
-}
-```
-
-Replace `REGION`, `ACCOUNT_ID`, and `DB_RESOURCE_ID` with your values. Find DB_RESOURCE_ID in RDS console → Configuration tab. For easier setup, you can use wildcards: `arn:aws:rds-db:*:*:dbuser:*/*`
-
-Reference: [IAM policy examples](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html)
-
-#### Step 3: Create Database User
-
-**MySQL/Aurora MySQL:**
-```sql
-CREATE USER 'bytebase'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
-ALTER USER 'bytebase'@'%' REQUIRE SSL;
-GRANT ALL PRIVILEGES ON *.* TO 'bytebase'@'%';
-```
-
-**PostgreSQL/Aurora PostgreSQL:**
-```sql
-CREATE USER bytebase;
-GRANT rds_iam TO bytebase;
--- Grant appropriate permissions
-```
-
-References: [MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.MySQL) | [PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL)
-
-#### Step 4: Connect from Bytebase
-
-1. Click **New Instance** in Bytebase
-2. Configure connection:
- - **Host:** Your RDS endpoint
- - **Port:** 3306 (MySQL) or 5432 (PostgreSQL)
- - **Username:** `bytebase`
- - **Authentication:** Select `AWS RDS IAM`
-3. Test and save the connection
-
-Bytebase automatically handles token generation and refresh using the EC2 instance profile.
-
-### AWS Secrets Manager
-
-Store database passwords securely in AWS Secrets Manager instead of Bytebase.
-
-
-Prerequisites: [IAM role](#prerequisites-iam-role-setup) with Secrets Manager permissions.
-
-
-#### Step 1: Grant Secrets Manager Access
-
-Add this policy to your IAM role to read secrets:
-
-```json
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": [
- "secretsmanager:GetSecretValue",
- "secretsmanager:DescribeSecret"
- ],
- "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:SECRET_NAME-*"
- }
- ]
-}
-```
-
-Replace `REGION`, `ACCOUNT_ID`, and `SECRET_NAME` with your values. For easier setup, you can use wildcards: `arn:aws:secretsmanager:*:*:secret:*`
-
-Reference: [Secrets Manager IAM permissions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html)
-
-#### Step 2: Create Secret
-
-1. Go to [AWS Secrets Manager Console](https://console.aws.amazon.com/secretsmanager/)
-2. Click **Store a new secret**
-3. Select **Other type of secret**
-4. Add key/value pair: Key = `DB_PASSWORD`, Value = your password
-5. Name the secret (e.g., `bytebase-db-password`)
-6. Complete creation and note the ARN
-
-Reference: [Creating secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)
-
-#### Step 3: Configure in Bytebase
-
-1. In your database instance settings, find the password field
-2. Click the key icon to use external secret
-3. Select **AWS Secrets Manager**
-4. Enter:
- - **Secret Name:** Your secret name from Step 2
- - **Secret Key:** `DB_PASSWORD`
-5. Test connection and save
-
-## GCP Configuration
-
-### Prerequisites: Service Account Setup
-
-Use attached service accounts for secure, key-free authentication on:
-- **GCE** - VMs with attached service accounts
-- **GKE** - Pods with Workload Identity
-
-References: [Service accounts](https://cloud.google.com/iam/docs/service-account-overview) | [Best practices](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys) | [ADC](https://cloud.google.com/docs/authentication/application-default-credentials)
-
-#### Create Service Account
-
-1. Go to [IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
-2. Create service account named `bytebase`
-3. Grant roles as needed:
- - `Cloud SQL Client` and `Cloud SQL Instance User` - for Cloud SQL
- - `Secret Manager Secret Accessor` - for Secret Manager
-4. Note the email: `bytebase@PROJECT_ID.iam.gserviceaccount.com`
-
-#### Attach Service Account
-
-**Option A: GCE VM**
-1. Create VM in [Compute Engine](https://console.cloud.google.com/compute/instances)
-2. Set service account: `bytebase@PROJECT_ID.iam.gserviceaccount.com`
-3. Set access scopes: "Allow full access to all Cloud APIs"
-
-**Option B: GKE with Workload Identity**
-```bash
-# Create Kubernetes service account
-kubectl create serviceaccount bytebase-ksa
-
-# Bind to Google service account
-kubectl annotate serviceaccount bytebase-ksa \
- iam.gke.io/gcp-service-account=bytebase@PROJECT_ID.iam.gserviceaccount.com
-
-# Allow impersonation
-gcloud iam service-accounts add-iam-policy-binding bytebase@PROJECT_ID.iam.gserviceaccount.com \
- --role roles/iam.workloadIdentityUser \
- --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/bytebase-ksa]"
-```
-
-Reference: [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
-
-Deploy Bytebase on your resource - credentials are provided automatically.
-
-#### Alternative: Service Account Keys
-
-
-Use only when running Bytebase outside GCP. See [why to avoid service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#avoid).
-
-
-1. Create a service account with required roles
-2. Download the JSON key file
-3. Set environment variable:
- ```bash
- -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
- ```
-
-Reference: [Service account keys authentication](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key)
-
-### Cloud SQL with IAM Authentication
-
-
-Prerequisites: [Service account](#prerequisites-service-account-setup) with Cloud SQL roles.
-
-
-References: [IAM authentication](https://cloud.google.com/sql/docs/mysql/iam-authentication) | [Configure instances](https://cloud.google.com/sql/docs/mysql/create-edit-iam-instances)
-
-#### Step 1: Configure Cloud SQL Instance
-
-1. In [Cloud SQL](https://console.cloud.google.com/sql/instances), edit your instance
-2. Add flag: `cloudsql_iam_authentication` = `on`
-3. Save (SSL is enabled by default)
-
-#### Step 2: Add Service Account User
-
-**Using gcloud:**
-```bash
-gcloud sql users create bytebase@PROJECT_ID.iam.gserviceaccount.com \
- --instance=INSTANCE_NAME \
- --type=cloud_iam_service_account
-```
-
-**Using Console:**
-Instance → Users → Add User Account → Cloud IAM → Enter service account email
-
-References: [MySQL](https://cloud.google.com/sql/docs/mysql/add-manage-iam-users) | [PostgreSQL](https://cloud.google.com/sql/docs/postgres/add-manage-iam-users)
-
-#### Step 3: Connect from Bytebase
-
-1. Click **New Instance** in Bytebase
-2. Configure connection details:
- - **Host:** Your Cloud SQL connection name (`PROJECT_ID:REGION:INSTANCE_ID`)
- - Find this in Cloud SQL console → Instance details
- - **Port:** 3306 (MySQL) or 5432 (PostgreSQL)
- - **Username:**
- - MySQL: `bytebase` (service account name only)
- - PostgreSQL: `bytebase@PROJECT_ID.iam` (with project ID)
- - **Authentication:** Select `Google Cloud SQL IAM`
-3. Click **Test Connection** then **Create**
-
-### GCP Secret Manager
-
-Store database passwords securely in Google Cloud Secret Manager instead of Bytebase.
-
-
-Prerequisites: [Service account](#prerequisites-service-account-setup) with `Secret Manager Secret Accessor` role.
-
-
-#### Step 1: Create Secret
-
-1. Go to [Secret Manager Console](https://console.cloud.google.com/security/secret-manager)
-2. Click **Create Secret**
-3. Enter secret name (e.g., `db-password`) and your database password as value
-4. Click **Create** and note the resource name: `projects/PROJECT_ID/secrets/SECRET_NAME`
-
-#### Step 2: Configure in Bytebase
-
-1. In your database instance settings, find the password field
-2. Click the key icon to use external secret
-3. Select **GCP Secret Manager**
-4. Enter the secret resource name from Step 1
-5. Test connection and save
-
-## Azure Configuration
-
-### Azure SQL with Managed Identity Authentication
-
-This guide demonstrates the most secure method for connecting to Azure SQL Database and Azure SQL Managed Instance using VM-attached managed identities, eliminating the need to manage credentials or connection strings.
-
-For alternative authentication methods and detailed configuration options, refer to:
-- [Azure SQL authentication methods overview](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-overview)
-- [Managed identities for Azure resources](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)
-- [Configure Azure AD authentication for SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-configure)
-- [Connect to Azure SQL with managed identity](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-azure-ad-user-assigned-managed-identity)
-
-#### Step 1: Create Azure VM with System-Assigned Managed Identity
-
-1. **Create VM with Managed Identity**
- - Go to [Azure Portal → Virtual Machines](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.Compute%2FVirtualMachines)
- - Click **Create** → **Azure virtual machine**
- - Configure VM settings as needed
- - Under **Management** tab:
- - Enable **System assigned managed identity**: Set to **On**
- - Complete VM creation
-
- > **Security Best Practice:** System-assigned managed identities are automatically managed by Azure and tied to the VM lifecycle. This eliminates credential management and reduces security risks. Learn more: [Managed identity best practices](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/managed-identity-best-practice-recommendations)
-
-2. **Deploy Bytebase on the VM**
-
- Deploy Bytebase on your Azure VM. The VM's managed identity is automatically available - no credential configuration needed.
-
-#### Step 2: Configure Azure SQL Database
-
-1. **Enable Microsoft Entra Authentication**
- - Navigate to your Azure SQL Server in [Azure Portal](https://portal.azure.com)
- - Go to **Settings** → **Microsoft Entra ID**
- - Click **Set admin** and select an Entra admin account
- - Click **Save** to enable Entra authentication
-
- Reference: [Configure Entra authentication for Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-configure)
-
-2. **Grant Database Access to Managed Identity**
- - Note your VM's managed identity name (same as VM name)
- - Connect to Azure SQL using the Entra admin account
- - Run the following for each database:
-
- ```sql
- -- Create user for the VM's managed identity
- CREATE USER [your-vm-name] FROM EXTERNAL PROVIDER;
-
- -- Grant appropriate permissions (adjust as needed)
- ALTER ROLE db_datareader ADD MEMBER [your-vm-name];
- ALTER ROLE db_datawriter ADD MEMBER [your-vm-name];
- ALTER ROLE db_ddladmin ADD MEMBER [your-vm-name];
-
- -- For full database management in Bytebase:
- ALTER ROLE db_owner ADD MEMBER [your-vm-name];
- ```
-
- > **Production Best Practice:** Follow the principle of least privilege. Grant only the minimum permissions required for your use case. See [Azure SQL Database permissions](https://learn.microsoft.com/en-us/azure/azure-sql/database/logins-create-manage).
-
-#### Step 3: Connect from Bytebase
-
-1. Access Bytebase on your VM (typically `http://localhost:5678`)
-2. Click **New Instance**
-3. Configure the connection:
- - **Host:** Your Azure SQL server name (e.g., `yourserver.database.windows.net`)
- - **Port:** 1433
- - **Database:** Target database name
- - **Authentication:** Select `Azure Default Credential`
-4. Test and save the connection
-
-Bytebase automatically uses the VM's managed identity through Azure's Instance Metadata Service (IMDS) for authentication.
-
-
-**Advantages of this approach:**
-- No passwords or connection strings to manage
-- Automatic credential rotation handled by Azure
-- Enhanced security through Azure RBAC
-- Simplified compliance and auditing
-
-For troubleshooting, see [Troubleshoot managed identity authentication](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-azure-ad-user-assigned-managed-identity#troubleshooting).
-
-
-#### Alternative: User-Assigned Managed Identity
-
-For more granular control or cross-resource scenarios:
-
-1. **Create User-Assigned Managed Identity**
- - Go to [Managed Identities](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.ManagedIdentity%2FuserAssignedIdentities)
- - Create a new identity with a descriptive name
- - Assign it to your VM under **Settings** → **Identity** → **User assigned**
-
-2. **Configure Database Access**
- ```sql
- CREATE USER [managed-identity-name] FROM EXTERNAL PROVIDER;
- ALTER ROLE db_owner ADD MEMBER [managed-identity-name];
- ```
-
-3. **Set Environment Variable** (if using multiple identities)
- ```bash
- export AZURE_CLIENT_ID=
- ```
-
-Reference: [User-assigned managed identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities)
-
-## Database-Specific Guides
-
-Configure connection settings for specific database types:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-