chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,99 @@
|
||||
---
|
||||
name: cloud-sql-basics
|
||||
description: Creates and manages Cloud SQL instances for MySQL, PostgreSQL, and SQL Server. Handles backups, high availability, and secure connectivity for relational database workloads on Google Cloud.
|
||||
source: google/skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# 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.*
|
||||
@@ -0,0 +1,84 @@
|
||||
# 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`).
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,62 @@
|
||||
# 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)):
|
||||
|
||||
- **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).
|
||||
@@ -0,0 +1,46 @@
|
||||
# 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)
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# 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)
|
||||
- [About Access Control - Cloud SQL for PostgreSQL](https://docs.cloud.google.com/sql/docs/postgres/instance-access-control)
|
||||
- [About Access Control - Cloud SQL for SQL Server](https://docs.cloud.google.com/sql/docs/sqlserver/instance-access-control)
|
||||
@@ -0,0 +1,51 @@
|
||||
# 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),
|
||||
[MySQL](https://docs.cloud.google.com/sql/docs/mysql/use-cloudsql-mcp), or
|
||||
[SQL Server](https://docs.cloud.google.com/sql/docs/sqlserver/use-cloudsql-mcp).
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user