Merge branch 'main' into ci-updates

averikitsch · web-flow · commit d25785c36bc7 · 2025-09-30T15:37:37.000-07:00
diff --git a/.github/workflows/json-lint.yml b/.github/workflows/json-lint.yml
@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
 
       - name: Run JSON Lint
         run: jq . gemini-extension.json
diff --git a/.github/workflows/markdown-checks.yml b/.github/workflows/markdown-checks.yml
@@ -24,10 +24,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
 
       - name: Link Checker
-        uses: lycheeverse/lychee-action@v2.0.2
+        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
@@ -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 }}
 
@@ -102,7 +102,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 }}
@@ -116,10 +116,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
@@ -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=.
diff --git a/README.md b/README.md
@@ -23,15 +23,17 @@ Before you begin, ensure you have the following:
     * Cloud Spanner Database Reader (`roles/spanner.databaseReader`)
     * Cloud Spanner Database User (`roles/spanner.databaseUser`)
 
-## Installation
+## Getting Started
+
+### Installation
 
 To install the extension, use the command:
 
 ```bash
 gemini extensions install https://github.com/gemini-cli-extensions/spanner
 ```
 
-## Configuration
+### Configuration
 
 Set the following environment variables before starting the Gemini CLI:
 
@@ -42,6 +44,19 @@ 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.
 
+### 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 <tag>` and `/chat resume <tag>`.
+
 ## Usage
 
 *   **Explore Schemas and Data:**
@@ -64,4 +79,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/<USER>/.gemini/extensions/spanner/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.
diff --git a/SPANNER.md b/SPANNER.md
@@ -4,6 +4,11 @@ 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`.
 
 ## Spanner MCP Server (Data Plane: Connecting and Querying)
 
@@ -14,11 +19,37 @@ This section covers connecting to a Spanner instance.
     *   `SPANNER_PROJECT`: The GCP project ID.
     *   `SPANNER_INSTANCE`: The Spanner instance ID.
     *   `SPANNER_DATABASE`: The Spanner database ID.
-    * `SPANNER_DIALECT`: The Spanner database dialect e.g. "googlesql" or "postgresql"
+    *   `SPANNER_DIALECT`: The Spanner database dialect e.g. "googlesql" or "postgresql"
 
 2.  **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${SPANNER_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 correct Spanner permissions (e.g., `spanner.databases.get`, `spanner.databases.select`). The user likely lacks the role **Cloud Spanner Database User**
 (`roles/spanner.databaseUser`) or **Cloud Spanner Database Reader** (`roles/spanner.databaseReader`). You can provide these links for assistance:
     *   Granting Roles: https://cloud.google.com/iam/docs/grant-role-console
     *   Spanner Permissions: https://cloud.google.com/iam/docs/roles-permissions/spanner
+
+---
+
+# Usage Guidelines
+
+## Connecting to New Resources
+
+You will need to perform the following steps to change the current database connection:
+
+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. `SPANNER_INSTANCE`, `SPANNER_DATABASE`) 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>`
+
+## Reusing Project Values
+
+Users may have set project environment variables:
+
+*   `SPANNER_PROJECT`: The GCP project ID.
+*   `SPANNER_INSTANCE`: The Spanner instance ID.
+*   `SPANNER_DATABASE`: The Spanner database ID.
+*   `SPANNER_DIALECT`: The Spanner database dialect e.g. "googlesql" or "postgresql"
+
+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 `SPANNER_PROJECT`, `${SPANNER_PROJECT}`, or `$SPANNER_PROJECT`. The value can be found by using command: `echo $SPANNER_PROJECT`.
diff --git a/gemini-extension.json b/gemini-extension.json
@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "description": "Connect and interact with Spanner data using natural language.",
   "mcpServers": {
-    "Spanner": {
+    "spanner": {
       "command": "${extensionPath}${/}toolbox",
       "args": [
         "--prebuilt",
diff --git a/toolbox_version.txt b/toolbox_version.txt
@@ -1 +1 @@
-0.15.0
+0.16.0
