mcpField
G
gcp-cloud-sql

gcp-cloud-sql

github.com/bagelhole云与 DevOps1.2k330 次安装23 周前更新
代码仓库

关于 gcp-cloud-sql

面向在 Google Cloud 上部署和管理关系型数据库的工程师，介绍托管式 Cloud SQL 的操作方式。涵盖 PostgreSQL、MySQL 和 SQL Server，以及高可用、备份、复制和连接配置。

主要功能

  1. 01创建 PostgreSQL、MySQL 和 SQL Server 实例
  2. 02配置私有 IP 与连接代理
  3. 03管理只读副本和跨区域副本
  4. 04创建备份并执行时间点恢复
  5. 05使用 gcloud 和 Terraform 管理实例

适用场景

  1. 01将本地 PostgreSQL 或 MySQL 迁移到 Cloud SQL
  2. 02为生产数据库配置区域级高可用
  3. 03创建副本以支持灾难恢复
  4. 04通过代理或私有 IP 连接应用

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bagelhole/devops-security-agent-skills --skill gcp-cloud-sql

安装后在 Claude Code 中输入/gcp-cloud-sql确认已加载。

详细介绍

GCP Cloud SQL

在 Google Cloud 上部署和管理全托管的关系型数据库（PostgreSQL、MySQL、SQL Server）。

适用场景

  • 运行生产级关系型数据库，无需管理复制、修补或备份
  • 将本地部署的 PostgreSQL 或 MySQL 工作负载迁移到托管服务
  • 应用需要 ACID 事务、关系型架构和 SQL 查询支持
  • 工作负载需要通过区域故障切换实现自动高可用

前置条件

  • 已安装并完成身份验证的 Google Cloud SDK（gcloud）
  • 已启用 Cloud SQL Admin API 和 Service Networking API
  • 拥有 IAM 角色 roles/cloudsql.admin 以进行全面管理
gcloud services enable sqladmin.googleapis.com servicenetworking.googleapis.com

实例层级参考

层级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高流量生产环境

创建 PostgreSQL 实例

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)

创建 MySQL 实例

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)

私有 IP 配置

# Allocate IP range and create private connection
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
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

读取副本

# 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

# 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

# Promote a replica to standalone (disaster recovery)
gcloud sql instances promote-replica prod-db-replica-eu

备份与恢复

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"

# 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

Cloud SQL Auth Proxy

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)
./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"

连接方式概要

方式使用场景要求
公共 IP + SSL开发/测试访问已配置授权网络
Cloud SQL Auth Proxy生产环境中的 GCE/GKESA 具有 roles/cloudsql.client
私有 IPVPC 原生应用已配置 VPC 对等互连
Cloud SQL Connector 库应用级集成SA 凭据

Terraform 配置

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]
}

常见操作

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

故障排除

症状原因解决方法
通过公共 IP 连接时出现 Connection refusedIP 不在授权网络中使用 gcloud sql instances patch --authorized-networks 添加 IP
出现 SSL required 错误require_ssl=true，但客户端未使用 SSL使用 Cloud SQL Proxy，或传入 sslmode=require
复制延迟过高副本层级过低，或主实例写入负载过高提高副本层级；降低写入负载
实例状态为 RUNNABLE，但速度缓慢CPU/内存配置不足使用 gcloud sql instances patch --tier 扩展层级
Proxy 返回 ECONNREFUSED连接名称错误或缺少 IAM 角色确认格式为 project:region:instance；授予 roles/cloudsql.client
无法创建私有 IP 实例尚未建立 VPC 对等互连先运行 gcloud services vpc-peerings connect
备份恢复失败版本不兼容确保源数据库和目标数据库的主版本相同

相关技能

  • gcp-networking - 用于 Cloud SQL 私有 IP 的 VPC 和 Private Service Connect
  • terraform-gcp - 使用 Infrastructure as Code 配置 Cloud SQL
  • gcp-gke - 通过 sidecar proxy 将 Kubernetes 工作负载连接到 Cloud SQL
  • gcp-compute - 在 Compute Engine 上运行可连接到 Cloud SQL 的应用

评论

支持 Markdown