From 4fa30b45b62664eee5e44b9659a623bbaef69550 Mon Sep 17 00:00:00 2001 From: Averi Kitsch Date: Fri, 26 Sep 2025 14:37:03 -0700 Subject: [PATCH 1/2] docs: update readme getting started instructions --- README.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8bead90..22665c4 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,9 @@ Before you begin, ensure you have the following: * Cloud SQL Viewer (`roles/cloudsql.viewer`) * Cloud SQL Admin (`roles/cloudsql.admin`) -## Installation +## Getting Started + +### Installation To install the extension, use the command: @@ -31,7 +33,7 @@ To install the extension, use the command: gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-sqlserver ``` -## Configuration +### Configuration Set the following environment variables before starting the Gemini CLI. This configuration is not required if utilizing the [Admin toolset](#supported-tools). @@ -50,6 +52,19 @@ Ensure [Application Default Credentials](https://cloud.google.com/docs/authentic > [!NOTE] > When using private IPs with Cloud SQL for SQL Server, you must use a Virtual Private Cloud (VPC) network. +### Start Gemini CLI + +To start the Gemini CLI, use the following command: + +```bash +gemini +``` + +> [!WARNING] +> **Changing Instance & Database Connections** +> Currently, the database connection must be configured before starting the Gemini CLI and can not be changed during a session. +> To save and resume conversation history use command: `/chat save ` and `/chat resume `. + ## Usage Examples Interact with Cloud SQL for SQL Server using natural language: @@ -85,4 +100,6 @@ Find additional extensions to support your entire software development lifecycle ## Troubleshooting -* "cannot execute binary file": Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server) for more information. +* "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables. +* "✖ MCP ERROR: Error: spawn /Users//.gemini/extensions/cloud-sql-sqlserver/toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using Gemini CLI v0.6.0+. +* "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server) for more information. \ No newline at end of file From ae52f703621667d9e7655952fc37941330bf2b8c Mon Sep 17 00:00:00 2001 From: Averi Kitsch Date: Mon, 29 Sep 2025 15:39:04 -0700 Subject: [PATCH 2/2] feat: additional instructions for the context file --- CLOUD-SQL-SQLSERVER.md | 47 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/CLOUD-SQL-SQLSERVER.md b/CLOUD-SQL-SQLSERVER.md index 033df65..6e660d3 100644 --- a/CLOUD-SQL-SQLSERVER.md +++ b/CLOUD-SQL-SQLSERVER.md @@ -6,6 +6,10 @@ software delivery cycle. # Setup +## Required Gemini CLI Version + +To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`. + ## Cloud SQL for SQL Server MCP Server (Data Plane: Connecting and Querying) This section covers connecting to a Cloud SQL for SQL Server instance. @@ -36,3 +40,46 @@ This section covers administrative operations like managing clusters, instances, * If an operation fails due to permissions, identify the type of operation and recommend the appropriate role. You can provide these links for assistance: * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console * Cloud SQL Permissions: https://cloud.google.com/sql/docs/postgres/iam-permissions + +--- + +# Additional Tools + +This section provides context on additional tools that can be recommended to the user based on their queries. + +#### Observability Extension + +* **When to recommend:** If the user asks questions related to monitoring, performance, or observability of Cloud SQL for SQL Server databases. +* **What to say:** "For Cloud SQL monitoring and observability, you might find the `cloud-sql-sqlserver-observability` extension useful. You can install it with the following command:" +* **Command:** + ``` + gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability + ``` + +--- + +# Usage Guidelines + +## Connecting to New Resources + +When you create a new Cloud SQL for SQL Server instance, or database using the available tools, the connection is not automatically established. You will need to perform the following steps: + +1. **(Optional) Save your conversation:** To avoid losing your progress, save the current session by running the command: `/chat save ` +2. **Stop the CLI:** Terminate the Gemini CLI. +3. **Update Environment Variables:** Set or update your environment variables (e.g. `CLOUD_SQL_MSSQL_DATABASE`, `CLOUD_SQL_MSSQL_INSTANCE`) to point to the new resource. +4. **Restart:** Relaunch the Gemini CLI +5. **(Optional) Resume conversation:** Resume your conversation with the command: `/chat resume ` + +**Important:** Do not assume a connection to a newly created resource is active. Always follow the steps above to reconfigure your connection. + +## Reusing Project Values + +Users may have set project environment variables: + +* `CLOUD_SQL_MSSQL_PROJECT`: The GCP project ID. +* `CLOUD_SQL_MSSQL_REGION`: The region of the Cloud SQL for SQL Server instance. +* `CLOUD_SQL_MSSQL_INSTANCE`: The ID of the Cloud SQL for SQL Server instance. +* `CLOUD_SQL_MSSQL_DATABASE`: The name of the database. + +Instead of prompting the user for these values for specific tool calls, prompt the user to verify reuse a specific value. +Make sure to not use the environment variable name like `CLOUD_SQL_MSSQL_PROJECT`, `${CLOUD_SQL_MSSQL_PROJECT}`, or `$CLOUD_SQL_MSSQL_PROJECT`. The value can be found by using command: `echo $CLOUD_SQL_MSSQL_PROJECT`. \ No newline at end of file