GCP Database Connections

Configure secure database connections for Cloud SQL and other GCP-managed databases

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 | Best practices | ADC

Create Service Account

1. Go to IAM & Admin → Service Accounts
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
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

# 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

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.

1. Create a service account with required roles
2. Download the JSON key file
3. Set environment variable:
   -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
   

Reference: Service account keys authentication

Cloud SQL with IAM Authentication

Prerequisites: Service account with Cloud SQL roles.

References: IAM authentication | Configure instances

Step 1: Configure Cloud SQL Instance

1. In Cloud SQL, 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:

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 | PostgreSQL

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 with Secret Manager Secret Accessor role.

Step 1: Create Secret

1. Go to Secret Manager Console
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:
   gcloud compute addresses create google-managed-services-default \
     --global \
     --purpose=VPC_PEERING \
     --prefix-length=16 \
     --network=default
   
3. Create private connection:
   gcloud services vpc-peerings connect \
     --service=servicenetworking.googleapis.com \
     --ranges=google-managed-services-default \
     --network=default
   

Reference: Private IP configuration

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:

Cloud SQL PostgreSQL

If the connecting instance is managed by the cloud provider, then SUPERUSER is not available and you should create the role via that provider’s admin console. The created role will have provider specific restricted semi-SUPERUSER privileges:

• In AWS RDS, the roll is rds_superuser.

• In Google Cloud SQL, the role is cloudsqlsuperuser.

You should grant Bytebase privileges with that semi-SUPERUSER role, e.g.:

-- For AWS RDS
GRANT rds_superuser TO bytebase

-- For Google Cloud SQL
GRANT cloudsqlsuperuser TO bytebase

Besides, you may need to grant Bytebase privileges with GRANT role_name TO bytebase; for all existing roles. Otherwise, Bytebase may not access existing databases or tables.

To prevent blocking operations for a long time, consider setting a lock_timeout on the Bytebase user.

Cloud SQL MySQL

Follow standard MySQL configuration with IAM authentication enabled as described above.

Cloud Spanner

For connecting to Google Cloud Spanner, you need to provide the following info:

1. Google cloud project ID.

2. Google cloud Spanner instance ID.

3. Google cloud service account credentials.

   

Specify Google Cloud Project ID and Spanner Instance ID

From the Spanner database detail page, you can get the project ID and the instance ID from the URL.

For example, the project ID and instance ID are spanner-test-3717002 and spanner-bb1 respectively for the above database.

Create a Google Cloud Service Account as the Credential

1. Go to Google Cloud console.
2. Click APIs & Services and then Credentials. You might have to click Menu on the top left first.
3. Click Create Credentials and then Service account.
4. For Service account name, enter a name for the service account.
5. Click Create and Continue.
6. For Select a role, select Cloud Spanner Database Admin for the service account.
7. Click Done.
8. Click the created service account.
9. At the top, click Keys and then Add Key and then Create new key. Make sure the key type is set to JSON and click Create.
10. You’ll get a message that the service account’s private key JSON file was downloaded to your computer. Make a note of the file name and where your browser saves it. You’ll need it later.

Upload the JSON file to the Credentials input.

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