gcp-cloud-sql
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGCP 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 () installed and authenticated
gcloud - Cloud SQL Admin API and Service Networking API enabled
- IAM role for full management
roles/cloudsql.admin
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.comInstance Tiers Reference
实例层级参考
| Tier | vCPUs | Memory | Use Case |
|---|---|---|---|
| db-f1-micro | Shared | 0.6 GB | Dev/test only |
| db-g1-small | Shared | 1.7 GB | Low-traffic staging |
| db-custom-2-8192 | 2 | 8 GB | Small production |
| db-custom-4-16384 | 4 | 16 GB | Medium production |
| db-custom-8-32768 | 8 | 32 GB | High-traffic production |
| 层级 | vCPU | 内存 | 适用场景 |
|---|---|---|---|
| db-f1-micro | 共享 | 0.6 GB | 仅用于开发/测试 |
| db-g1-small | 共享 | 1.7 GB | 低流量预发布环境 |
| db-custom-2-8192 | 2 | 8 GB | 小型生产环境 |
| db-custom-4-16384 | 4 | 16 GB | 中型生产环境 |
| db-custom-8-32768 | 8 | 32 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
undefinedbash
undefinedAllocate IP range and create private connection
分配IP范围并创建私有连接
gcloud compute addresses create google-managed-services
--global --purpose=VPC_PEERING --prefix-length=16 --network=my-vpc
--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
--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
--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
--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
--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
undefinedgcloud 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
--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
undefinedRead Replicas
只读副本
bash
undefinedbash
undefinedSame-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
--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
--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
--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
--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
undefinedgcloud sql instances promote-replica prod-db-replica-eu
undefinedBackups and Restore
备份与恢复
bash
gcloud sql backups create --instance=prod-db --description="pre-migration"
gcloud sql backups list --instance=prod-dbbash
gcloud sql backups create --instance=prod-db --description="pre-migration"
gcloud sql backups list --instance=prod-dbPoint-in-time recovery
时间点恢复
gcloud sql instances clone prod-db prod-db-pitr
--point-in-time="2026-03-23T10:00:00Z"
--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"
--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
undefinedgcloud 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
undefinedCloud 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-authnbash
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-authnUnix 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"
undefinedConnection Methods Summary
连接方式汇总
| Method | Use Case | Requirement |
|---|---|---|
| Public IP + SSL | Dev/test access | Authorized networks configured |
| Cloud SQL Auth Proxy | Production on GCE/GKE | SA with |
| Private IP | VPC-native apps | VPC peering configured |
| Cloud SQL Connector lib | App-level integration | SA credentials |
| 方式 | 适用场景 | 要求 |
|---|---|---|
| 公网IP + SSL | 开发/测试访问 | 已配置授权网络 |
| Cloud SQL认证代理 | GCE/GKE上的生产环境 | 拥有 |
| 私有IP | VPC原生应用 | 已配置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-dbbash
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-dbTroubleshooting
故障排查
| Symptom | Cause | Fix |
|---|---|---|
| IP not in authorized networks | Add IP with |
| | Use Cloud SQL Proxy or pass |
| High replication lag | Replica tier too small or write-heavy primary | Increase replica tier; reduce write load |
| Instance slow despite RUNNABLE | Under-provisioned CPU/memory | Scale tier with |
Proxy returns | Wrong connection name or missing IAM role | Verify |
| Cannot create private IP instance | VPC peering not established | Run |
| Backup restore fails | Incompatible version | Ensure same major database version between source and target |
| 症状 | 原因 | 解决方法 |
|---|---|---|
公网IP连接时出现 | IP不在授权网络中 | 使用 |
出现 | 已设置 | 使用Cloud SQL代理或传递 |
| 复制延迟过高 | 副本层级过小或主实例写入负载过重 | 提升副本层级;降低写入负载 |
| 实例状态为RUNNABLE但运行缓慢 | CPU/内存资源不足 | 使用 |
代理返回 | 连接名称错误或缺少IAM角色 | 验证 |
| 无法创建私有IP实例 | VPC对等连接未建立 | 先执行 |
| 备份恢复失败 | 版本不兼容 | 确保源实例与目标实例的数据库主版本一致 |
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的应用