Skip to content

docs: Update documentation for skills #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
twishabansal merged 6 commits into from
Apr 15, 2026
+227 −131
Merged

docs: Update documentation for skills #110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ef5afd0
docs: Update documentation for skills
twishabansal Apr 15, 2026
9a3749d
Update CLOUD-SQL-SQLSERVER.md
twishabansal Apr 15, 2026
bdb88bd
Update README.md
twishabansal Apr 15, 2026
f6bdb01
Merge branch 'main' into feature/docs-skills-updates
twishabansal Apr 15, 2026
b708a6f
Merge branch 'main' into feature/docs-skills-updates
twishabansal Apr 15, 2026
45bb297
Merge branch 'main' into feature/docs-skills-updates
twishabansal Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions CLOUD-SQL-SQLSERVER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ This section covers connecting to a Cloud SQL for SQL Server instance.
* `CLOUD_SQL_MSSQL_USER`: The database username.
* `CLOUD_SQL_MSSQL_PASSWORD`: The password for the database user.

If you need to update any of these values later, use the `gemini extensions config cloud-sql-sqlserver` command.

2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${CLOUD_SQL_MSSQL_PROJECT}`, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it.

3. **Handle Permission Errors**: If you encounter permission errors, ensure the user has the **Cloud SQL Client** (`roles/cloudsql.client`) role and the correct database-level permissions. You can provide these links for assistance:
Expand All @@ -42,9 +44,9 @@ This section covers administrative operations like managing clusters, instances,

---

# Additional Tools
# Additional Extensions

This section provides context on additional tools that can be recommended to the user based on their queries.
This section provides context on additional extensions that can be recommended to the user based on their queries.

#### Observability Extension

Expand All @@ -61,12 +63,12 @@ This section provides context on additional tools that can be recommended to the

## 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:
When you create a new Cloud SQL for SQL Server instance, or database using the available skills, 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 <your-tag>`
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
2. **Stop the CLI**: Terminate the Gemini CLI.
3. **Update Extension Configuration**: Use the command `gemini extensions config cloud-sql-sqlserver` to update your settings (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 <your-tag>`

**Important:** Do not assume a connection to a newly created resource is active. Always follow the steps above to reconfigure your connection.
Expand All @@ -80,11 +82,12 @@ Users may have set project environment variables:
* `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`.
Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting 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 verified by the user using the `gemini extensions config cloud-sql-sqlserver` command or by checking their local settings.

## Use Full Table Name Format "DATABASE_NAME.SCHEMA_NAME.TABLE_NAME"

**ALWAYS** use the full table name format, `DATABASE_NAME.SCHEMA_NAME.TABLE_NAME` in the generated SQL when using the `execute_sql` or `cloud_sql_sqlserver__execute_sql` tool.
**ALWAYS** use the full table name format, `DATABASE_NAME.SCHEMA_NAME.TABLE_NAME` in the generated SQL when using the `execute_sql` skill.
* Default to using "dbo" for the schema name.
* Use command `echo $CLOUD_SQL_MSSQL_DATABASE` to get the current database value.
38 changes: 11 additions & 27 deletions DEVELOPER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# DEVELOPER.md

This document provides instructions for setting up your development environment
and contributing to the Cloud SQL for SQL Server Gemini CLI Extension project.
and contributing to the Cloud SQL for SQL Server Agent skills project.

## Prerequisites

Expand All @@ -10,44 +10,30 @@ Before you begin, ensure you have the following:
1. **Gemini CLI:** Install the Gemini CLI version v0.6.0 or above. Installation
instructions can be found on the official Gemini CLI documentation. You can
verify your version by running `gemini --version`.
2. **Cloud SQL for SQL Server Instance:** For testing data plane tools, you will need access to an active Cloud SQL for SQL Server instance.
2. **Cloud SQL for SQL Server Instance:** For testing data plane tools, you will need access to an active Cloud SQL for SQL Server
instance.

## Developing the Extension

### Running from Local Source

The core logic for this extension is handled by a pre-built `toolbox` binary. The development process involves installing the extension locally into the Gemini CLI to test changes.

1. **Clone the Repository:**

```bash
git clone https://github.com/gemini-cli-extensions/cloud-sql-sqlserver.git
cd cloud-sql-sqlserver
```

2. **Download the Toolbox Binary:** The required version of the `toolbox` binary
is specified in `toolbox_version.txt`. Download it for your platform.

```bash
# Read the required version
VERSION=$(cat toolbox_version.txt)

# Example for macOS/amd64
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/geminicli/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox
```
Adjust the URL for your operating system (`linux/amd64`, `darwin/arm64`, `windows/amd64`).

3. **Link the Extension Locally:** Use the Gemini CLI to install the
2. **Install the Extension Locally:** Use the Gemini CLI to install the
extension from your local directory.

```bash
gemini extensions link .
gemini extensions install .
```
The CLI will prompt you to confirm the linking. Accept it to proceed.
The CLI will prompt you to confirm the installation. Accept it to proceed.

4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`).
You can now interact with the `cloud-sql-sqlserver` tools to manually test your changes
3. **Testing Changes:** After installation, start the Gemini CLI (`gemini`).
You can now interact with the `cloud-sql-sqlserver` skills to manually test your changes
against your connected database.

## Testing
Expand All @@ -58,9 +44,9 @@ A GitHub Actions workflow (`.github/workflows/presubmit-tests.yml`) is triggered
for every pull request. This workflow primarily verifies that the extension can
be successfully installed by the Gemini CLI.

Currently, there are no automated unit or integration test suites
within this repository. All functional testing must be performed manually. All tools
are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox).
All tools are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox).

The skills themselves are validated using the `skills-validate.yml` workflow.

### Other GitHub Checks

Expand All @@ -73,7 +59,6 @@ are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/m
* **Dependency Updates:** [Renovate](https://github.com/apps/forking-renovate)
is configured to automatically create pull requests for dependency updates.


## Maintainer Information

### Team
Expand Down Expand Up @@ -128,4 +113,3 @@ The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror-
2. **Merge Release PR:** A maintainer approves and merges the Release PR. This
action triggers `release-please` to create a new GitHub tag and a
corresponding GitHub Release.

Loading
Loading