gcp-cloud-sql

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GCP Cloud SQL

GCP Cloud SQL

Deploy and manage fully managed relational databases (PostgreSQL, MySQL, SQL Server) on Google Cloud.
在Google Cloud上部署并管理全托管关系型数据库(PostgreSQL、MySQL、SQL Server)。

When to Use

使用场景

  • Running production relational databases without managing replication, patching, or backups
  • Migrating on-premises PostgreSQL or MySQL workloads to a managed service
  • Applications requiring ACID transactions, relational schemas, and SQL query support
  • Workloads that need automated high availability with regional failover
  • 运行生产级关系型数据库,无需管理复制、补丁或备份
  • 将本地PostgreSQL或MySQL工作负载迁移至托管服务
  • 需要ACID事务、关系型架构及SQL查询支持的应用
  • 需要具备区域故障转移能力的自动化高可用工作负载

Prerequisites

前置条件

  • Google Cloud SDK (
    gcloud
    ) installed and authenticated
  • Cloud SQL Admin API and Service Networking API enabled
  • IAM role
    roles/cloudsql.admin
    for full management
bash
gcloud services enable sqladmin.googleapis.com servicenetworking.googleapis.com
  • 已安装并完成身份验证的Google Cloud SDK(
    gcloud
  • 已启用Cloud SQL Admin API与Service Networking API
  • 拥有完整管理权限的IAM角色
    roles/cloudsql.admin
bash
gcloud services enable sqladmin.googleapis.com servicenetworking.googleapis.com

Instance Tiers Reference

实例层级参考

TiervCPUsMemoryUse Case
db-f1-microShared0.6 GBDev/test only
db-g1-smallShared1.7 GBLow-traffic staging
db-custom-2-819228 GBSmall production
db-custom-4-16384416 GBMedium production
db-custom-8-32768832 GBHigh-traffic production
层级vCPU内存适用场景
db-f1-micro共享0.6 GB仅用于开发/测试
db-g1-small共享1.7 GB低流量预发布环境
db-custom-2-819228 GB小型生产环境
db-custom-4-16384416 GB中型生产环境
db-custom-8-32768832 GB高流量生产环境

Create a PostgreSQL Instance

创建PostgreSQL实例

bash
gcloud sql instances create prod-db \
  --database-version=POSTGRES_16 \
  --tier=db-custom-4-16384 \
  --region=us-central1 \
  --availability-type=REGIONAL \
  --storage-type=SSD --storage-size=100GB --storage-auto-increase \
  --backup-start-time=02:00 --enable-point-in-time-recovery \
  --retained-backups-count=14 \
  --maintenance-window-day=SUN --maintenance-window-hour=4 \
  --database-flags=max_connections=200,log_min_duration_statement=1000 \
  --root-password=$(openssl rand -base64 24) \
  --labels=env=production,team=backend

gcloud sql databases create myapp --instance=prod-db --charset=UTF8
gcloud sql users create appuser --instance=prod-db \
  --password=$(openssl rand -base64 24)
bash
gcloud sql instances create prod-db \
  --database-version=POSTGRES_16 \
  --tier=db-custom-4-16384 \
  --region=us-central1 \
  --availability-type=REGIONAL \
  --storage-type=SSD --storage-size=100GB --storage-auto-increase \
  --backup-start-time=02:00 --enable-point-in-time-recovery \
  --retained-backups-count=14 \
  --maintenance-window-day=SUN --maintenance-window-hour=4 \
  --database-flags=max_connections=200,log_min_duration_statement=1000 \
  --root-password=$(openssl rand -base64 24) \
  --labels=env=production,team=backend

gcloud sql databases create myapp --instance=prod-db --charset=UTF8
gcloud sql users create appuser --instance=prod-db \
  --password=$(openssl rand -base64 24)

Create a MySQL Instance

创建MySQL实例

bash
gcloud sql instances create mysql-prod \
  --database-version=MYSQL_8_0 \
  --tier=db-custom-4-16384 --region=us-central1 \
  --availability-type=REGIONAL \
  --storage-type=SSD --storage-size=100GB --storage-auto-increase \
  --backup-start-time=02:00 --enable-bin-log --retained-backups-count=14 \
  --database-flags=slow_query_log=on,long_query_time=2,max_connections=500 \
  --root-password=$(openssl rand -base64 24)
bash
gcloud sql instances create mysql-prod \
  --database-version=MYSQL_8_0 \
  --tier=db-custom-4-16384 --region=us-central1 \
  --availability-type=REGIONAL \
  --storage-type=SSD --storage-size=100GB --storage-auto-increase \
  --backup-start-time=02:00 --enable-bin-log --retained-backups-count=14 \
  --database-flags=slow_query_log=on,long_query_time=2,max_connections=500 \
  --root-password=$(openssl rand -base64 24)

Private IP Configuration

私有IP配置

bash
undefined
bash
undefined

Allocate IP range and create private connection

分配IP范围并创建私有连接

gcloud compute addresses create google-managed-services
--global --purpose=VPC_PEERING --prefix-length=16 --network=my-vpc
gcloud services vpc-peerings connect
--service=servicenetworking.googleapis.com
--ranges=google-managed-services --network=my-vpc
gcloud compute addresses create google-managed-services
--global --purpose=VPC_PEERING --prefix-length=16 --network=my-vpc
gcloud services vpc-peerings connect
--service=servicenetworking.googleapis.com
--ranges=google-managed-services --network=my-vpc

Create instance with private IP only

创建仅含私有IP的实例

gcloud sql instances create private-db
--database-version=POSTGRES_16 --tier=db-custom-2-8192
--region=us-central1
--network=projects/${PROJECT_ID}/global/networks/my-vpc
--no-assign-ip --availability-type=REGIONAL
--storage-type=SSD --storage-size=50GB --storage-auto-increase
undefined
gcloud sql instances create private-db
--database-version=POSTGRES_16 --tier=db-custom-2-8192
--region=us-central1
--network=projects/${PROJECT_ID}/global/networks/my-vpc
--no-assign-ip --availability-type=REGIONAL
--storage-type=SSD --storage-size=50GB --storage-auto-increase
undefined

Read Replicas

只读副本

bash
undefined
bash
undefined

Same-region replica

同区域副本

gcloud sql instances create prod-db-replica-1
--master-instance-name=prod-db --tier=db-custom-4-16384
--region=us-central1 --availability-type=ZONAL
gcloud sql instances create prod-db-replica-1
--master-instance-name=prod-db --tier=db-custom-4-16384
--region=us-central1 --availability-type=ZONAL

Cross-region replica for DR

用于灾难恢复的跨区域副本

gcloud sql instances create prod-db-replica-eu
--master-instance-name=prod-db --tier=db-custom-4-16384
--region=europe-west1 --availability-type=ZONAL
gcloud sql instances create prod-db-replica-eu
--master-instance-name=prod-db --tier=db-custom-4-16384
--region=europe-west1 --availability-type=ZONAL

Promote a replica to standalone (disaster recovery)

将副本提升为独立实例(灾难恢复)

gcloud sql instances promote-replica prod-db-replica-eu
undefined
gcloud sql instances promote-replica prod-db-replica-eu
undefined

Backups and Restore

备份与恢复

bash
gcloud sql backups create --instance=prod-db --description="pre-migration"
gcloud sql backups list --instance=prod-db
bash
gcloud sql backups create --instance=prod-db --description="pre-migration"
gcloud sql backups list --instance=prod-db

Point-in-time recovery

时间点恢复

gcloud sql instances clone prod-db prod-db-pitr
--point-in-time="2026-03-23T10:00:00Z"
gcloud sql instances clone prod-db prod-db-pitr
--point-in-time="2026-03-23T10:00:00Z"

Export / import

导出/导入

gcloud sql export sql prod-db gs://my-bucket/export.sql.gz --database=myapp gcloud sql import sql prod-db gs://my-bucket/export.sql.gz --database=myapp
undefined
gcloud sql export sql prod-db gs://my-bucket/export.sql.gz --database=myapp gcloud sql import sql prod-db gs://my-bucket/export.sql.gz --database=myapp
undefined

Cloud SQL Auth Proxy

Cloud SQL认证代理

bash
curl -o cloud-sql-proxy \
  https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.0/cloud-sql-proxy.linux.amd64
chmod +x cloud-sql-proxy

./cloud-sql-proxy ${PROJECT_ID}:us-central1:prod-db --port=5432 --auto-iam-authn
bash
curl -o cloud-sql-proxy \
  https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.0/cloud-sql-proxy.linux.amd64
chmod +x cloud-sql-proxy

./cloud-sql-proxy ${PROJECT_ID}:us-central1:prod-db --port=5432 --auto-iam-authn

Unix socket (for Kubernetes sidecar pattern)

Unix套接字(适用于Kubernetes边车模式)

./cloud-sql-proxy ${PROJECT_ID}:us-central1:prod-db --unix-socket=/tmp/cloudsql psql "host=/tmp/cloudsql/${PROJECT_ID}:us-central1:prod-db user=appuser dbname=myapp"
undefined
./cloud-sql-proxy ${PROJECT_ID}:us-central1:prod-db --unix-socket=/tmp/cloudsql psql "host=/tmp/cloudsql/${PROJECT_ID}:us-central1:prod-db user=appuser dbname=myapp"
undefined

Connection Methods Summary

连接方式汇总

MethodUse CaseRequirement
Public IP + SSLDev/test accessAuthorized networks configured
Cloud SQL Auth ProxyProduction on GCE/GKESA with
roles/cloudsql.client
Private IPVPC-native appsVPC peering configured
Cloud SQL Connector libApp-level integrationSA credentials
方式适用场景要求
公网IP + SSL开发/测试访问已配置授权网络
Cloud SQL认证代理GCE/GKE上的生产环境拥有
roles/cloudsql.client
权限的服务账号
私有IPVPC原生应用已配置VPC对等连接
Cloud SQL Connector库应用级集成服务账号凭证

Terraform Configuration

Terraform配置

hcl
resource "google_sql_database_instance" "main" {
  name             = "prod-db"
  database_version = "POSTGRES_16"
  region           = "us-central1"

  settings {
    tier              = "db-custom-4-16384"
    availability_type = "REGIONAL"
    disk_type         = "PD_SSD"
    disk_size         = 100
    disk_autoresize   = true

    backup_configuration {
      enabled                        = true
      start_time                     = "02:00"
      point_in_time_recovery_enabled = true
      backup_retention_settings { retained_backups = 14 }
    }

    ip_configuration {
      ipv4_enabled    = false
      private_network = google_compute_network.vpc.id
      require_ssl     = true
    }

    maintenance_window { day = 7; hour = 4 }
    database_flags { name = "max_connections"; value = "200" }

    user_labels = { env = "production" }
  }

  deletion_protection = true
  depends_on          = [google_service_networking_connection.private_vpc]
}

resource "google_sql_database" "app" {
  name     = "myapp"
  instance = google_sql_database_instance.main.name
}

resource "google_sql_user" "app" {
  name     = "appuser"
  instance = google_sql_database_instance.main.name
  password = random_password.db_password.result
}

resource "google_sql_database_instance" "replica" {
  name                 = "prod-db-replica-1"
  master_instance_name = google_sql_database_instance.main.name
  region               = "us-central1"
  database_version     = "POSTGRES_16"

  replica_configuration { failover_target = false }

  settings {
    tier            = "db-custom-4-16384"
    disk_type       = "PD_SSD"
    disk_autoresize = true
    ip_configuration {
      ipv4_enabled    = false
      private_network = google_compute_network.vpc.id
    }
  }
}

resource "google_compute_global_address" "private_ip" {
  name          = "google-managed-services"
  purpose       = "VPC_PEERING"
  address_type  = "INTERNAL"
  prefix_length = 16
  network       = google_compute_network.vpc.id
}

resource "google_service_networking_connection" "private_vpc" {
  network                 = google_compute_network.vpc.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip.name]
}
hcl
resource "google_sql_database_instance" "main" {
  name             = "prod-db"
  database_version = "POSTGRES_16"
  region           = "us-central1"

  settings {
    tier              = "db-custom-4-16384"
    availability_type = "REGIONAL"
    disk_type         = "PD_SSD"
    disk_size         = 100
    disk_autoresize   = true

    backup_configuration {
      enabled                        = true
      start_time                     = "02:00"
      point_in_time_recovery_enabled = true
      backup_retention_settings { retained_backups = 14 }
    }

    ip_configuration {
      ipv4_enabled    = false
      private_network = google_compute_network.vpc.id
      require_ssl     = true
    }

    maintenance_window { day = 7; hour = 4 }
    database_flags { name = "max_connections"; value = "200" }

    user_labels = { env = "production" }
  }

  deletion_protection = true
  depends_on          = [google_service_networking_connection.private_vpc]
}

resource "google_sql_database" "app" {
  name     = "myapp"
  instance = google_sql_database_instance.main.name
}

resource "google_sql_user" "app" {
  name     = "appuser"
  instance = google_sql_database_instance.main.name
  password = random_password.db_password.result
}

resource "google_sql_database_instance" "replica" {
  name                 = "prod-db-replica-1"
  master_instance_name = google_sql_database_instance.main.name
  region               = "us-central1"
  database_version     = "POSTGRES_16"

  replica_configuration { failover_target = false }

  settings {
    tier            = "db-custom-4-16384"
    disk_type       = "PD_SSD"
    disk_autoresize = true
    ip_configuration {
      ipv4_enabled    = false
      private_network = google_compute_network.vpc.id
    }
  }
}

resource "google_compute_global_address" "private_ip" {
  name          = "google-managed-services"
  purpose       = "VPC_PEERING"
  address_type  = "INTERNAL"
  prefix_length = 16
  network       = google_compute_network.vpc.id
}

resource "google_service_networking_connection" "private_vpc" {
  network                 = google_compute_network.vpc.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip.name]
}

Common Operations

常见操作

bash
gcloud sql instances list
gcloud sql instances describe prod-db \
  --format="yaml(state,settings.tier,settings.availabilityType,ipAddresses)"
gcloud sql instances patch prod-db --storage-size=200GB
gcloud sql instances patch prod-db --database-flags=max_connections=300
gcloud sql instances restart prod-db
bash
gcloud sql instances list
gcloud sql instances describe prod-db \
  --format="yaml(state,settings.tier,settings.availabilityType,ipAddresses)"
gcloud sql instances patch prod-db --storage-size=200GB
gcloud sql instances patch prod-db --database-flags=max_connections=300
gcloud sql instances restart prod-db

Troubleshooting

故障排查

SymptomCauseFix
Connection refused
via public IP
IP not in authorized networksAdd IP with
gcloud sql instances patch --authorized-networks
SSL required
error
require_ssl=true
but client not using SSL
Use Cloud SQL Proxy or pass
sslmode=require
High replication lagReplica tier too small or write-heavy primaryIncrease replica tier; reduce write load
Instance slow despite RUNNABLEUnder-provisioned CPU/memoryScale tier with
gcloud sql instances patch --tier
Proxy returns
ECONNREFUSED
Wrong connection name or missing IAM roleVerify
project:region:instance
format; grant
roles/cloudsql.client
Cannot create private IP instanceVPC peering not establishedRun
gcloud services vpc-peerings connect
first
Backup restore failsIncompatible versionEnsure same major database version between source and target
症状原因解决方法
公网IP连接时出现
Connection refused
IP不在授权网络中使用
gcloud sql instances patch --authorized-networks
添加IP
出现
SSL required
错误
已设置
require_ssl=true
但客户端未使用SSL
使用Cloud SQL代理或传递
sslmode=require
参数
复制延迟过高副本层级过小或主实例写入负载过重提升副本层级;降低写入负载
实例状态为RUNNABLE但运行缓慢CPU/内存资源不足使用
gcloud sql instances patch --tier
升级实例层级
代理返回
ECONNREFUSED
连接名称错误或缺少IAM角色验证
project:region:instance
格式;授予
roles/cloudsql.client
角色
无法创建私有IP实例VPC对等连接未建立先执行
gcloud services vpc-peerings connect
命令
备份恢复失败版本不兼容确保源实例与目标实例的数据库主版本一致

Related Skills

相关技能

  • gcp-networking - VPC and private service connect for Cloud SQL private IP
  • terraform-gcp - Provision Cloud SQL with Infrastructure as Code
  • gcp-gke - Connecting Kubernetes workloads to Cloud SQL via sidecar proxy
  • gcp-compute - Running applications on Compute Engine that connect to Cloud SQL
  • gcp-networking - 用于Cloud SQL私有IP的VPC与私有服务连接
  • terraform-gcp - 使用基础设施即代码配置Cloud SQL
  • gcp-gke - 通过边车代理将Kubernetes工作负载连接至Cloud SQL
  • gcp-compute - 在Compute Engine上运行连接Cloud SQL的应用