# SkillPatch skill: cloud-sql-basics

This skill guides agents in creating and managing Google Cloud SQL instances for MySQL, PostgreSQL, and SQL Server. It provides step-by-step CLI workflows for enabling the API, provisioning instances, setting up users and databases, and connecting via the Cloud SQL Auth Proxy. It also references supporting documentation for IAM, Terraform IaC, client libraries, and MCP usage.

You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it:

**1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs.

**2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined):

```bash
mkdir -p .claude/skills/cloud-sql-basics
curl -sSL https://skillpatch.dev/install_skill/cloud-sql-basics | tar -xz -C .claude/skills/
```

(`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.)


---

## Skill files (7)

- `SKILL.md`
- `references/cli-usage.md`
- `references/client-library-usage.md`
- `references/core-concepts.md`
- `references/iac-usage.md`
- `references/iam-security.md`
- `references/mcp-usage.md`


### `SKILL.md`

````markdown
---
name: cloud-sql-basics
metadata:
  category: Databases
description: >-
  This file generates or explains Cloud SQL resources. Use this file when the
  user asks to create a Cloud SQL instance or database for MySQL, PostgreSQL, or
  SQL Server.

  Cloud SQL manages third-party MySQL, PostgreSQL, and SQL Server instances as
  resources in Cloud SQL. For example, when Cloud SQL creates an open-source
  MySQL instance, the resulting resource is a Cloud SQL for MySQL instance that
  Google Cloud manages.

  Cloud SQL handles backups, high availability, and secure connectivity for
  relational database workloads.
---

# 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:**
    
    ```bash
    gcloud services enable sqladmin.googleapis.com --quiet
    ```

2.  **Create an Instance:**
    
    ```bash
    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`:
    
    ```bash
    gcloud sql users set-password postgres \
      --instance=INSTANCE_NAME --password=PASSWORD \
      --quiet
    ```

4.  **Create a database:**
    
    ```bash
    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:
    
    ```bash
    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:
    
    ```bash
    ./cloud-sql-proxy INSTANCE_CONNECTION_NAME
    ```

    With the proxy running, connect using `psql` in another terminal:
    
    ```bash
    psql "host=127.0.0.1 port=5432 user=postgres dbname=DATABASE_NAME password=PASSWORD sslmode=disable"
    ```

## Reference Directory

-   [Core Concepts](references/core-concepts.md): Instance architecture, high
    availability (HA), and supported database engines.

-   [CLI Usage](references/cli-usage.md): Essential `gcloud sql` commands for
    instance, database, and user management.

-   [Client Libraries & Connectors](references/client-library-usage.md):
    Connecting to Cloud SQL using Python, Java, Node.js, and Go.

-   [MCP Usage](references/mcp-usage.md): Using the Cloud SQL remote MCP
    server and Gemini CLI extension.

-   [Infrastructure as Code](references/iac-usage.md): Terraform
    configuration for instances, databases, and users.

-   [IAM & Security](references/iam-security.md): 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.*

````


### `references/cli-usage.md`

````markdown
# Cloud SQL CLI Usage

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

## Basic Syntax

```bash
gcloud sql [GROUP] [COMMAND] [FLAGS]
```

## Essential Commands

### Instance Management

- **Create an instance:**

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

- **List instances:**

  ```bash
  gcloud sql instances list --quiet
  ```

- **Describe an instance:**

  ```bash
  gcloud sql instances describe my-instance --quiet
  ```

- **Restart an instance:**

  ```bash
  gcloud sql instances restart my-instance --quiet
  ```

### Database and User Management

- **Create a database:**

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

- **Create a user:**

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

### Operations and Backups

- **List operations:**

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

- **Create a backup:**

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

- **Restore from a backup:**

  ```bash
  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`).

````


### `references/client-library-usage.md`

````markdown
# 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](https://cloud.google.com/sdk/docs/install)

### 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:**

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

-   **Usage Example:**

    ```python
    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:

    ```xml
    <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:**
        ```xml  
        <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:**
        ```xml 
        <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:**

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

#### Go

-   **Installation:**

    ```bash
    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](https://docs.cloud.google.com/sql/docs/mysql/admin-api.md.txt)

````


### `references/core-concepts.md`

```markdown
# 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](https://docs.cloud.google.com/sql/docs/db-versions.md.txt)):

-   **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](https://cloud.google.com/sql/pricing).

```


### `references/iac-usage.md`

````markdown
# 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

```terraform
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](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/sql_database_instance)

- [Terraform Google Provider - SQL Database](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/sql_database)

- [Terraform Google Provider - SQL User](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/sql_user)


````


### `references/iam-security.md`

```markdown
# Cloud SQL IAM & Security

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

## Predefined IAM Roles

| Predefined Role | Usage |
| :--- | :--- |
| `roles/cloudsql.admin` | Full control over all Cloud SQL resources. |
| `roles/cloudsql.editor` | Manage Cloud SQL resources. Cannot see or modify

 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](https://docs.cloud.google.com/sql/docs/mysql/instance-access-control.md.txt)
- [About Access Control - Cloud SQL for PostgreSQL](https://docs.cloud.google.com/sql/docs/postgres/instance-access-control.md.txt)
- [About Access Control - Cloud SQL for SQL Server](https://docs.cloud.google.com/sql/docs/sqlserver/instance-access-control.md.txt)
```


### `references/mcp-usage.md`

```markdown
# 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](https://mcp-toolbox.dev/integrations/cloud-sql-pg/source/)
*   [Cloud SQL for MySQL](https://mcp-toolbox.dev/integrations/cloud-sql-mysql/source/)
*   [Cloud SQL for SQL Server](https://mcp-toolbox.dev/integrations/cloud-sql-mssql/source/)

## 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](https://github.com/gemini-cli-extensions/cloud-sql-postgresql)
*   [Cloud SQL for MySQL](https://github.com/gemini-cli-extensions/cloud-sql-mysql)
*   [Cloud SQL for SQL Server](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver)

## 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](https://docs.cloud.google.com/sql/docs/postgres/use-cloudsql-mcp.md.txt),
[MySQL](https://docs.cloud.google.com/sql/docs/mysql/use-cloudsql-mcp.md.txt), or
[SQL Server](https://docs.cloud.google.com/sql/docs/sqlserver/use-cloudsql-mcp.md.txt).

## 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.

```