Cloud Sql Basics

Cloud SQL Basics

Cloud SQL is a fully managed relational database service for MySQL, PostgreSQL, and SQL Server. It automates time-consuming tasks like patches, updates, backups, and replicas, while providing high performance and availability for your applications.

Prerequisites

Ensure you have the necessary IAM permissions to create and manage Cloud SQL instances. The Cloud SQL Admin (roles/cloudsql.admin) role provides full access to Cloud SQL resources.

Quick Start (PostgreSQL)

1. Enable the API:

    gcloud services enable sqladmin.googleapis.com --quiet

2. Create an Instance:

    gcloud sql instances create INSTANCE_NAME \
      --database-version=POSTGRES_18 \
      --cpu=2 \
      --memory=7680MiB \
      --region=REGION \
      --quiet

3. Set a password for the default user:

Because this is a Cloud SQL for PostgreSQL instance, the default admin user is postgres:

    gcloud sql users set-password postgres \
      --instance=INSTANCE_NAME --password=PASSWORD \
      --quiet

4. Create a database:

    gcloud sql databases create DATABASE_NAME \
      --instance=INSTANCE_NAME \
      --quiet

5. Get the instance connection name:

You need the instance connection name (which is formatted as PROJECT_ID:REGION:INSTANCE_NAME) to connect using the Cloud SQL Auth Proxy. Retrieve it with the following command:

    gcloud sql instances describe INSTANCE_NAME \
      --format="value(connectionName)" \
      --quiet

6. Connect to the instance:

The Cloud SQL Auth Proxy must be running to be able to connect to the instance. In a separate terminal, start the proxy using the connection name:

    ./cloud-sql-proxy INSTANCE_CONNECTION_NAME

With the proxy running, connect using psql in another terminal:

    psql "host=127.0.0.1 port=5432 user=postgres dbname=DATABASE_NAME password=PASSWORD sslmode=disable"

Reference Directory

• Core Concepts: Instance architecture, high

availability (HA), and supported database engines.

• CLI Usage: Essential gcloud sql commands for

instance, database, and user management.

• Client Libraries & Connectors:

Connecting to Cloud SQL using Python, Java, Node.js, and Go.

• MCP Usage: Using the Cloud SQL remote MCP

server and Gemini CLI extension.

• Infrastructure as Code: Terraform

configuration for instances, databases, and users.

• IAM & Security: Predefined roles, SSL/TLS

certificates, and Auth Proxy configuration.

If you need product information not found in these references, use the Developer Knowledge MCP server `search_documents` tool.

Cloud SQL CLI Usage

The gcloud sql command group is used to manage Cloud SQL instances and related resources.

Basic Syntax

gcloud sql [GROUP] [COMMAND] [FLAGS]

Essential Commands

Instance Management

• Create an instance:

  gcloud sql instances create my-instance --database-version=MYSQL_8_0 \
      --tier=db-f1-micro --region=us-central1 \
      --quiet

• List instances:

  gcloud sql instances list --quiet

• Describe an instance:

  gcloud sql instances describe my-instance --quiet

• Restart an instance:

  gcloud sql instances restart my-instance --quiet

Database and User Management

• Create a database:

  gcloud sql databases create my-db --instance=my-instance --quiet

• Create a user:

  gcloud sql users create my-user --instance=my-instance \
      --password=my-password \
      --quiet

Operations and Backups

• List operations:

  gcloud sql operations list --instance=my-instance --quiet

• Create a backup:

  gcloud sql backups create --instance=my-instance --quiet

• Restore from a backup:

  gcloud sql backups restore backup_id --restore-instance=my-instance --quiet

Common Flags

• --project: Specifies the project ID.

• --region: The region where the instance is located.

• --format: Changes output format (e.g., json, yaml).

Cloud SQL Client Libraries

Google Cloud provides client libraries and connectors to simplify connecting to Cloud SQL from various programming languages.

Getting Started

Ensure you have the latest version of the Google Cloud SDK installed and authenticated. Install Google Cloud SDK

Language Connectors

The Cloud SQL Language Connectors (Python, Java, Go, Node.js) provide a secure way to connect to the Cloud SQL instance without managing IP allowlists or SSL certificates.

Python

• Installation for a Cloud SQL for PostgreSQL instance:

    pip install "cloud-sql-python-connector[pg8000]"

• Usage Example:

    from google.cloud.sql.connector import Connector
    connector = Connector()
    def getconn():
      conn = connector.connect(
          "project:region:instance",
          "pg8000",
          user="my-user",
          password="my-password",
          db="my-db"
      )
      return conn

Java

• Maven Dependencies:

The recommended method is to use the Cloud SQL JDBC Socket Factory. Add the BOM to your <dependencyManagement> section:

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>com.google.cloud.sql</groupId>
          <artifactId>jdbc-socket-factory-bom</artifactId>
          <version>1.18.0</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>

Then add dependencies for your database:

• PostgreSQL:

        <dependencies>
          <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.7.3</version>
          </dependency>
          <dependency>
            <groupId>com.google.cloud.sql</groupId>
            <artifactId>postgres-socket-factory</artifactId>
          </dependency>
        </dependencies>

• MySQL:

        <dependencies>
          <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.0.33</version>
          </dependency>
          <dependency>
            <groupId>com.google.cloud.sql</groupId>
            <artifactId>mysql-socket-factory-connector-j-8</artifactId>
          </dependency>
        </dependencies>

Node.js (TypeScript)

• Installation:

    npm install @google-cloud/cloud-sql-connector

Go

• Installation:

    go get cloud.google.com/go/cloudsqlconn

Cloud SQL Admin API

To manage Cloud SQL resources (e.g., list instances) programmatically, use the sqladmin libraries.

• Cloud SQL Admin API Overview

Cloud SQL Core Concepts

Cloud SQL provides managed relational databases, abstracting the underlying infrastructure while offering standard database engines.

Supported Engines

Cloud SQL supports the following database engines (see supported versions):

• MySQL: Versions 5.6, 5.7, 8.0, and 8.4.

• PostgreSQL: Versions 9.6, 10, 11, 12, 13, 14, 15, 16, 17, and 18

(default).

• SQL Server: 2017 (Express, Web, Standard, Enterprise), 2019, 2022, and

2025 (Express, Enterprise, Standard).

Instance Architecture

Each Cloud SQL instance is powered by a virtual machine (VM) running the database program.

• Primary Instance: The main read/write connection point.

• High Availability (HA): Provides a standby VM in a different zone with

automatic failover.

• Read Replicas: Used to scale read traffic and provide local access in

different regions.

Storage and Networking

• Persistent Disk: Scalable and durable network storage attached to the

VM.

• Connectivity: Supports Private IP (using VPC peering for MySQL and

PostgreSQL only; or using private services access or Private Service Connect for all Cloud SQL engines) and Public IP (with authorized networks or Auth Proxy).

Pricing

Cloud SQL pricing is based on:

• Instance Type: vCPUs and RAM.

• Storage: Amount of data stored and IOPS.

• Networking: Network egress and IP address usage.

• DNS pricing: Charge is per zone per month (regardless of whether you use

your zone). You also pay for queries against your zones.

• Licensing: Applies to SQL Server only. In addition to instance and

resource pricing, SQL Server also has a licensing component. High availability, or regional instances, will only incur the cost for a single license for the active resource. As a managed service, Cloud SQL does not support BYOL (Bring your own license).

For the latest pricing, visit: Cloud SQL Pricing.

Cloud SQL Infrastructure as Code

Cloud SQL resources can be provisioned and managed using Terraform and other IaC tools.

Terraform

The Google Cloud Terraform provider supports Cloud SQL instances, databases, and users.

Cloud SQL Instance Example

resource "google_sql_database_instance" "default" {
  name             = "master-instance"
  region           = "us-central1"
  database_version = "POSTGRES_15"

  settings {
    tier = "db-f1-micro"
    backup_configuration {
      enabled = true
    }
  }
}

resource "google_sql_database" "database" {
  name     = "my-database"
  instance = google_sql_database_instance.default.name
}

resource "google_sql_user" "users" {
  name     = "me"
  instance = google_sql_database_instance.default.name
  password = "changeme"
}

Reference Documentation

• Terraform Google Provider - SQL Database Instance

• Terraform Google Provider - SQL Database

• Terraform Google Provider - SQL User

Cloud SQL IAM & Security

Cloud SQL uses Identity and Access Management (IAM) to control access to instances and databases.

Predefined IAM Roles

permissions, nor modify users or ssl Certs. Cannot import data or restore from a backup, nor clone, delete, or promote instances. Cannot start or stop replicas. Cannot delete databases, replicas, or backups. | | roles/cloudsql.viewer | Read-only access to Cloud SQL resources. | | roles/cloudsql.client | Connectivity access to Cloud SQL instances from App Engine and the Cloud SQL Auth Proxy. Not required for accessing an instance using IP addresses. | | roles/cloudsql.instanceUser | Permission to log in to a Cloud SQL instance. | | roles/cloudsql.schemaViewer | Role allowing access to a Cloud SQL instance schema in Knowledge Catalog. | | roles/cloudsql.studioUser | Role allowing access to Cloud SQL Studio. |

Secure Connectivity

• Cloud SQL Auth Proxy: The recommended way to connect securely. It

provides IAM-based authentication and end-to-end encryption without requiring SSL/TLS certificates or authorized networks.

• Private IP: Use VPC, private services access, or Private Service Connect

(PSC) to keep database traffic within the Google Cloud network.

• Authorized Networks: If using Public IP, restrict access to specific

CIDR ranges.

Data Security

• Encryption at Rest: All data is encrypted by default. Use

Customer-Managed Encryption Keys (CMEK) for additional control.

• IAM Database Authentication: Authenticate to the database using IAM

users or service accounts instead of static passwords (available for MySQL and PostgreSQL).

Organization Policies

• Cloud SQL organization policies: Organization policies let organization

administrators set restrictions on how users can configure instances under that organization.

Service Accounts

• Service Identity: Cloud SQL uses an instance service account

(p[PROJECT_NUMBER]-[UNIQUE_ID]@gcp-sa-cloud-sql.iam.gserviceaccount.com) for tasks like exporting a SQL dump file to Cloud Storage. Service agent accounts (service-PROJECT_NUMBER@gcp-sa-cloud-sql.iam.gserviceaccount.com) are used only for internal management tasks.

• App Connectivity: Grant the service account running your app (e.g., on

Cloud Run or GKE) the roles/cloudsql.client role.

For more information, see:

• About Access Control - Cloud SQL for MySQL
• About Access Control - Cloud SQL for PostgreSQL
• About Access Control - Cloud SQL for SQL Server

Cloud SQL MCP Usage

Cloud SQL can be managed via the Model Context Protocol (MCP), which allows agents to manage database instances and execute SQL queries. MCP is available via remote servers and through local execution with the MCP Toolbox:

• Cloud SQL for PostgreSQL
• Cloud SQL for MySQL
• Cloud SQL for SQL Server

MCP Tools for Cloud SQL

The Cloud SQL MCP server typically includes the following tools:

• clone_instance: creates a Cloud SQL instance as a clone of source

instance.

• create_instance: initiates the creation of a Cloud SQL instance.
• create_user: creates a database user for a Cloud SQL instance.
• execute_sql: executes any valid SQL statements (DDL, DCL, DQL, DML) on a

Cloud SQL instance.

• get_instance: gets the details of a Cloud SQL instance.
• get_operation: gets the status of a long-running operation in Cloud SQL.
• list_instances: lists all Cloud SQL instances in a project.
• list_users: lists all database users for a Cloud SQL instance.
• import_data: imports data into a Cloud SQL instance from Cloud Storage.
• update_instance: updates supported settings of a Cloud SQL instance.
• update_user: updates a database user for a Cloud SQL instance.

For additional specialized skills including health auditing, performance monitoring, and lifecycle management, install the Gemini CLI extension or Claude Plugin:

• Cloud SQL for PostgreSQL
• Cloud SQL for MySQL
• Cloud SQL for SQL Server

Setup Instructions

Setup varies by database engine and whether you are connecting to a remote server or using the MCP Toolbox. For remote server setup, see Setting up Cloud SQL MCP for PostgreSQL, MySQL, or SQL Server.

Supported Operations

Agents using the Cloud SQL MCP can:

• Automate database schema migrations.
• Perform health checks and monitor operation logs.
• Assist in debugging SQL performance issues.