diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0416ae2..e299f1b 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -3,5 +3,4 @@ # For syntax help see: # https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax -* @gemini-cli-extensions/senseai-eco -* @gemini-cli-extensions/cloud-sql-sqlserver-maintainers +* @gemini-cli-extensions/senseai-eco @gemini-cli-extensions/cloud-sql-sqlserver-maintainers diff --git a/.github/renovate.json5 b/.github/renovate.json5 new file mode 100644 index 0000000..f3eb783 --- /dev/null +++ b/.github/renovate.json5 @@ -0,0 +1,34 @@ +{ + extends: [ + 'config:recommended', + ':semanticCommitTypeAll(chore)', + ':ignoreUnstable', + ':separateMajorReleases', + ':prConcurrentLimitNone', + ':prHourlyLimitNone', + ':preserveSemverRanges', + ], + rebaseWhen: 'conflicted', + dependencyDashboardLabels: [ + 'type: process', + ], + packageRules: [ + { + groupName: 'GitHub Actions', + matchManagers: [ + 'github-actions', + ], + pinDigests: true, + }, + ], + customManagers: [ + { + customType: "regex", + managerFilePatterns: ["/toolbox_version\\.txt$/"], + matchStrings: ["(?[\\d\\.]+)"], + datasourceTemplate: "github-releases", + packageNameTemplate: "googleapis/genai-toolbox", + extractVersionTemplate: "^v(?.*)$", + } + ] +} diff --git a/.github/workflows/json-lint.yml b/.github/workflows/json-lint.yml new file mode 100644 index 0000000..7969d49 --- /dev/null +++ b/.github/workflows/json-lint.yml @@ -0,0 +1,29 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Lint JSON + +on: + pull_request: + branches: [ main ] + +jobs: + json-lint: + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5 + + - name: Run JSON Lint + run: jq . gemini-extension.json \ No newline at end of file diff --git a/.github/workflows/markdown-checks.yml b/.github/workflows/markdown-checks.yml new file mode 100644 index 0000000..6900fd4 --- /dev/null +++ b/.github/workflows/markdown-checks.yml @@ -0,0 +1,33 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Lint Markdown + +on: + pull_request: + branches: [ main ] + +jobs: + link-check: + name: Run link check + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5 + + - name: Link Checker + uses: lycheeverse/lychee-action@885c65f3dc543b57c898c8099f4e08c8afd178a2 # v2.6.1 + with: + # There is no security token. So, it would fail on any links which aren't public. + args: "--verbose --no-progress **/*.md" diff --git a/.github/workflows/package-and-upload-assets.yml b/.github/workflows/package-and-upload-assets.yml index 5f1f52c..efc038b 100644 --- a/.github/workflows/package-and-upload-assets.yml +++ b/.github/workflows/package-and-upload-assets.yml @@ -39,7 +39,7 @@ jobs: steps: - name: Checkout code at the new tag - uses: actions/checkout@v4 + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5 with: ref: ${{ github.event.release.tag_name }} @@ -103,7 +103,7 @@ jobs: echo "ARCHIVE_PATH=${ARCHIVE_NAME}" >> $GITHUB_OUTPUT - name: Upload archive as workflow artifact - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: name: ${{ steps.vars.outputs.archive_name }} path: ${{ steps.create_archive.outputs.ARCHIVE_PATH }} @@ -117,10 +117,10 @@ jobs: contents: write steps: - name: Checkout code - uses: actions/checkout@v4 + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5 - name: Download all archives from workflow artifacts - uses: actions/download-artifact@v4 + uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5 with: path: release-archives diff --git a/.github/workflows/presubmit-tests.yml b/.github/workflows/presubmit-tests.yml new file mode 100644 index 0000000..787c919 --- /dev/null +++ b/.github/workflows/presubmit-tests.yml @@ -0,0 +1,37 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +name: Presubmit Tests + +on: + pull_request: + branches: [ main ] + +jobs: + run-presubmit-tests: + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5 + + - name: Install Gemini CLI + run: npm install @google/gemini-cli + + - name: Install toolbox binary + run: | + VERSION=$(cat toolbox_version.txt) + curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox + chmod +x toolbox + + - name: Install Extension + run: yes | npx gemini extensions install --path=. \ No newline at end of file diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 0000000..fc49c06 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1 @@ +https://github.com/gemini-cli-extensions/cloud-sql-sqlserver/compare/ diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 3d2ac0b..5547f83 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.1.0" + ".": "0.1.1" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 095936d..bf064f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## [0.1.1](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver/compare/0.1.0...0.1.1) (2025-09-30) + + +### Features + +* additional instructions for the context file ([#33](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver/issues/33)) ([782e50b](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver/commit/782e50bccb9a76d8b10bfb30400e2dd8e1c0f652)) + + +### Bug Fixes + +* standardize mcp server names ([#31](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver/issues/31)) ([8c7b2c5](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver/commit/8c7b2c52d3e85a643c03f5cecce69a45a633430a)) + ## 0.1.0 (2025-09-20) 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 diff --git a/README.md b/README.md index 5d53335..0384333 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Gemini CLI Extension - Cloud SQL for SQL Server > [!NOTE] -> This extension is currently in beta, and may see breaking changes until the first stable release (v1.0). +> This extension is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0). This Gemini CLI extension provides a set of tools to interact with [Cloud SQL for SQL Server](https://cloud.google.com/sql/docs/sqlserver) instances. It allows you to manage your databases, execute queries, explore schemas, and troubleshoot issues directly from the [Gemini CLI](https://google-gemini.github.io/gemini-cli/), using natural language prompts. @@ -12,28 +12,32 @@ Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini * **Seamless Workflow:** As a Google-developed extension, it integrates seamlessly into the Gemini CLI environment. No need to constantly switch contexts for common database tasks. * **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. * **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas. + ## Prerequisites Before you begin, ensure you have the following: -* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version +v0.6.0. +* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version **+v0.6.0**. * A Google Cloud project with the **Cloud SQL Admin API** enabled. * IAM Permissions: * Cloud SQL Client (`roles/cloudsql.client`) * Cloud SQL Viewer (`roles/cloudsql.viewer`) * Cloud SQL Admin (`roles/cloudsql.admin`) -## Installation +## Getting Started + +### Installation -To install the extension, use the command: +To install the extension, use the following command before starting the Gemini CLI: ```bash -gemini extensions install github.com/gemini-cli-extensions/cloud-sql-sqlserver +gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-sqlserver ``` -## Configuration +### Configuration -Set the following environment variables before starting the Gemini CLI: +Set the following environment variables before starting the Gemini CLI. +This configuration is not required if utilizing the [Admin toolset](#supported-tools). * `CLOUD_SQL_MSSQL_PROJECT`: The GCP project ID. * `CLOUD_SQL_MSSQL_REGION`: The region of your Cloud SQL instance. @@ -47,7 +51,59 @@ Set the following environment variables before starting the Gemini CLI: Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. > [!NOTE] -> When using private IPs with Cloud SQL for SQL Server, you must use a Virtual Private Cloud (VPC) network. +> If your Cloud SQL for SQL Server instance uses private IPs, you must run Gemini CLI in the same 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 `. + +### 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 `. + +### 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 `. + +### 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 @@ -66,9 +122,9 @@ Interact with Cloud SQL for SQL Server using natural language: ## Supported Tools * **Admin:** - * `create_instance`: Use this tool to create an Postgres instance. - * `create_user`: Use this tool to create Postgres-BUILT-IN or IAM-based users. - * `get_instance`: Use this tool to get details about an Postgres instance. + * `create_instance`: Use this tool to create an SQL Server instance. + * `create_user`: Use this tool to create SQL Server-BUILT-IN or IAM-based users. + * `get_instance`: Use this tool to get details about an SQL Server instance. * `get_user`: Use this tool to get details about a user. * `list_instances`: Use this tool to list instances in a given project and location. * `list_users`: Use this tool to list users in a given project and location. @@ -80,8 +136,13 @@ Interact with Cloud SQL for SQL Server using natural language: ## Additional Extensions -Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). +Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions), including: +* [Generic SQL Server extension](https://github.com/gemini-cli-extensions/sql-server) +* [Cloud SQL for SQL Server Observability extension](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) +* and more! ## 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 diff --git a/gemini-extension.json b/gemini-extension.json index dd45855..8f1f54a 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,9 +1,9 @@ { "name": "cloud-sql-sqlserver", - "version": "0.1.0", + "version": "0.1.1", "description": "Connect to Cloud SQL for SQL Server", "mcpServers": { - "Cloud SQL for SQL Server Admin": { + "cloud_sql_sqlserver_admin": { "command": "${extensionPath}${/}toolbox", "args": [ "--prebuilt", @@ -11,7 +11,7 @@ "--stdio" ] }, - "Cloud SQL for SQL Server": { + "cloud_sql_sqlserver": { "command": "${extensionPath}${/}toolbox", "args": [ "--prebuilt", @@ -29,4 +29,4 @@ } }, "contextFileName": "CLOUD-SQL-SQLSERVER.md" -} +} \ No newline at end of file diff --git a/release-please-config.json b/release-please-config.json index 748844d..f1de0f5 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -4,10 +4,24 @@ "include-component-in-tag": false, "include-v-in-tag": false, "changelog-sections": [ - { "type": "feat", "section": "Features" }, - { "type": "fix", "section": "Bug Fixes" }, - { "type": "chore", "section": "Miscellaneous Chores", "hidden": false }, - { "type": "docs", "section": "Documentation", "hidden": false } + { + "type": "feat", + "section": "Features" + }, + { + "type": "fix", + "section": "Bug Fixes" + }, + { + "type": "chore", + "section": "Miscellaneous Chores", + "hidden": true + }, + { + "type": "docs", + "section": "Documentation", + "hidden": true + } ], "packages": { ".": { @@ -22,4 +36,4 @@ ] } } -} +} \ No newline at end of file diff --git a/toolbox_version.txt b/toolbox_version.txt index 7092c7c..d183d4a 100644 --- a/toolbox_version.txt +++ b/toolbox_version.txt @@ -1 +1 @@ -0.15.0 \ No newline at end of file +0.16.0 \ No newline at end of file