From ebfcd7e5c172425c92b226a3202ee84139210a02 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 15:42:32 +0530 Subject: [PATCH 1/3] feat: add Claude Code plugin config and marketplace --- .claude-plugin/marketplace.json | 20 +++ .claude-plugin/plugin.json | 39 +++++ README.md | 267 +++++++++++++++++++++++--------- 3 files changed, 257 insertions(+), 69 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..e326265 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "spanner-marketplace", + "interface": { + "displayName": "Spanner Agent Skills" + }, + "plugins": [ + { + "name": "spanner", + "source": { + "source": "git", + "url": "https://github.com/gemini-cli-extensions/spanner.git" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Database" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..5a38633 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,39 @@ +{ + "name": "spanner", + "version": "0.2.6", + "description": "Connect and interact with Spanner data using natural language.", + "author": { + "name": "Google LLC", + "email": "data-cloud-ai-integrations@google.com" + }, + "homepage": "https://cloud.google.com/spanner", + "license": "Apache-2.0", + "repository": "https://github.com/gemini-cli-extensions/spanner", + "skills": "./skills/", + "userConfig": { + "spanner_project": { + "title": "Project ID", + "description": "ID of the Google Cloud project", + "type": "string", + "sensitive": false + }, + "spanner_instance": { + "title": "Instance", + "description": "ID of the Spanner instance", + "type": "string", + "sensitive": false + }, + "spanner_database": { + "title": "Database", + "description": "ID of the Spanner database", + "type": "string", + "sensitive": false + }, + "spanner_dialect": { + "title": "Database Dialect", + "description": "(Optional) The SQL dialect of the Spanner Database: 'googlesql' or 'postgresql'. (Default: 'googlesql')", + "type": "string", + "sensitive": false + } + } +} diff --git a/README.md b/README.md index b0c2e45..e014ea5 100644 --- a/README.md +++ b/README.md @@ -1,122 +1,251 @@ -# Gemini CLI Extension - Spanner +# Spanner Agent Skills > [!NOTE] -> This extension is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0). +> 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 [Google Cloud Spanner](https://cloud.google.com/spanner/docs) instances. It allows you to manage your databases, execute queries, and explore schemas directly from the [Gemini CLI](https://google-gemini.github.io/gemini-cli/), using natural language prompts. +This repository provides a set of agent skills to interact with [Google Cloud Spanner](https://cloud.google.com/spanner/docs) instances. These skills can be used with various AI agents, including [Gemini CLI](https://google-gemini.github.io/gemini-cli/), Claude Code, and Codex, to manage your databases, execute queries, explore schemas, and troubleshoot issues using natural language prompts. -Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md). > [!IMPORTANT] > **We Want Your Feedback!** -> Please share your thoughts with us by filling out our feedback [form][form]. +> Please share your thoughts with us by filling out our feedback [form][form]. > Your input is invaluable and helps us improve the project for everyone. [form]: https://docs.google.com/forms/d/e/1FAIpQLSfEGmLR46iipyNTgwTmIDJqzkAwDPXxbocpXpUbHXydiN1RTw/viewform?usp=pp_url&entry.157487=spanner -## Why Use the Spanner Extension? - -* **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. -* **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. -* **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas. - +## Table of Contents + +- [Why Use Spanner Agent Skills?](#why-use-spanner-agent-skills) +- [Prerequisites](#prerequisites) +- [Getting Started](#getting-started) + - [Configuration](#configuration) + - [Installation & Usage](#installation--usage) + - [Gemini CLI](#gemini-cli) + - [Claude Code](#claude-code) + - [Codex](#codex) + - [Antigravity](#antigravity) +- [Usage Examples](#usage-examples) +- [Supported Skills](#supported-skills) +- [Additional Agent Skills](#additional-agent-skills) +- [Troubleshooting](#troubleshooting) + +## Why Use Spanner Agent Skills? + +- **Seamless Workflow:** Integrates seamlessly into your AI agent's environment. No need to constantly switch contexts for common database tasks. +- **Natural Language Queries:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. +- **Full Lifecycle Control:** Manage your Spanner databases, from exploring schemas to running queries. +- **Code Generation:** Accelerate development by asking your agent 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**. -* Setup Gemini CLI [Authentication](https://github.com/google-gemini/gemini-cli/tree/main?tab=readme-ov-file#-authentication-options). -* A Google Cloud project with the **Spanner API** enabled. -* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -* IAM Permissions - * Cloud Spanner Database Reader (`roles/spanner.databaseReader`) - * Cloud Spanner Database User (`roles/spanner.databaseUser`) +- One of these AI agents installed + - [Gemini CLI](https://github.com/google-gemini/gemini-cli) version **v0.6.0** or higher + - [Claude Code](https://claude.com/product/claude-code) version **v2.1.94** or higher + - [Codex](https://developers.openai.com/codex) **v0.117.0** or higher + - [Antigravity](https://antigravity.google) **v1.14.2** or higher +- A Google Cloud project with the **Spanner API** enabled. +- Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. +- IAM Permissions: + - Cloud Spanner Database Reader (`roles/spanner.databaseReader`) + - Cloud Spanner Database User (`roles/spanner.databaseUser`) ## Getting Started -### Installation +### Configuration -To install the extension, use the command: +Please keep these env vars handy during the installation process: -```bash -gemini extensions install https://github.com/gemini-cli-extensions/spanner -``` +- `SPANNER_PROJECT`: The GCP project ID. +- `SPANNER_INSTANCE`: The Spanner instance ID. +- `SPANNER_DATABASE`: The Spanner database ID. +- `SPANNER_DIALECT`: (Optional) The SQL dialect of the Spanner Database: 'googlesql' or 'postgresql'. Defaults to "googlesql". -### Configuration +> [!NOTE] +> +> - Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -You will be prompted to configure the following settings during installation. These settings are saved in an `.env` file within the extension's directory. +### Installation & Usage -* `SPANNER_PROJECT`: The GCP project ID. -* `SPANNER_INSTANCE`: The Spanner instance ID. -* `SPANNER_DATABASE`: The Spanner database ID. -* `SPANNER_DIALECT`: (Optional) The SQL dialect of the Spanner database: 'googlesql' or 'postgresql'. Defaults to "googlesql". +To start interacting with your database, install the skills for your preferred AI agent, then launch the agent and use natural language to ask questions or perform tasks. -To view or update your configuration: +For the latest version, check the [releases page][releases]. -**List Settings:** -* Terminal: `gemini extensions list` -* Gemini CLI: `/extensions list` +[releases]: https://github.com/gemini-cli-extensions/spanner/releases -**Update Settings:** -* Terminal: `gemini extensions config spanner [setting name] [--scope ]` - * `setting name`: (Optional) The single setting to configure. - * `scope`: (Optional) The scope of the setting in (`user` or `workspace`). Defaults to `user`. -* Currently, you must restart the Gemini CLI for changes to take effect. We recommend using `gemini --resume` to resume your session. + -Alternatively, you can manually set these environment variables before starting the Gemini CLI: +
+Gemini CLI + +**1. Install the extension:** ```bash -export SPANNER_PROJECT="" -export SPANNER_INSTANCE="" -export SPANNER_DATABASE="" -export SPANNER_DIALECT="googlesql" # Optional: "googlesql" or "postgresql". Defaults to "googlesql". +gemini extensions install https://github.com/gemini-cli-extensions/spanner ``` -> [!NOTE] -> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -> * See [Troubleshooting](#troubleshooting) for debugging your configuration. +During the installation, enter your environment vars as described in the [configuration section](#configuration). + +**2. (Optional) Manage Configuration:** +To view or update your configuration in Gemini CLI: -### Start Gemini CLI +- Terminal: `gemini extensions config spanner [setting name] [--scope ]` +- Gemini CLI: `/extensions list` -To start the Gemini CLI, use the following command: +**3. Start the agent:** ```bash gemini ``` +_(Tip: Run `/extensions list` to verify your configuration and active extensions.)_ + > [!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 `. +> Currently, the database connection must be configured before starting the agent and can not be changed during a session. +> To save and resume conversation history in Gemini CLI use command: `/chat save ` and `/chat resume `. + +
+ +
+Claude Code + +**1. Set env vars:** +In your terminal, set your environment vars as described in the [configuration section](#configuration). + +**2. Start the agent:** + +```bash +claude +``` + +**3. Add the marketplace:** + +```bash +/plugin marketplace add https://github.com/gemini-cli-extensions/spanner.git#0.2.6 +``` + +**4. Install the plugin:** + +```bash +/plugin install spanner@spanner-marketplace +``` + +_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_ + +
+ +
+Codex + +**1. Clone the Repo:** + +```bash +git clone --branch 0.2.6 git@github.com:gemini-cli-extensions/spanner.git +``` + +**2. Install the plugin:** + +```bash +mkdir -p ~/.codex/plugins +cp -R /absolute/path/to/spanner ~/.codex/plugins/spanner +``` + +**3. Set env vars:** +Enter your environment vars as described in the [configuration section](#configuration). + +**4. Create or update marketplace.json:** +`~/.agents/plugins/marketplace.json` + +```json +{ + "name": "my-data-cloud-google-marketplace", + "interface": { + "displayName": "Google Data Cloud Skills" + }, + "plugins": [ + { + "name": "spanner", + "source": { + "source": "local", + "path": "./plugins/spanner" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Database" + } + ] +} +``` + +_(Tip: Run `codex plugin list` or use the `/plugins` interactive menu to verify your installed plugins.)_ + +
+ +
+Antigravity + +**1. Clone the Repo:** + +```bash +git clone --branch 0.2.6 https://github.com/gemini-cli-extensions/spanner.git +``` + +**2. Install the skills:** + +Choose a location for the skills: +- **Global (all workspaces):** `~/.gemini/antigravity/skills/` +- **Workspace-specific:** `/.agents/skills/` + +Copy the skill folders from the cloned repository's `skills/` directory to your chosen location: + +```bash +cp -R spanner/skills/* ~/.gemini/antigravity/skills/ +``` + +**3. Set env vars:** +Set your environment vars as described in the [configuration section](#configuration). + +_(Tip: Antigravity automatically discovers skills in these directories at the start of a session.)_ + +
+ + + +## Usage Examples + +Interact with Spanner using natural language: -## Usage +- **Explore Schemas and Data:** + - "Show me all tables in the 'orders' database." + - "What are the columns in the 'products' table?" + - "How many orders were placed in the last 30 days, and what were the top 5 most purchased items?" +- **Generate Code:** + - "Generate a Python dataclass to represent the 'customers' table." -* **Explore Schemas and Data:** - * "Show me all tables in the 'orders' database." - * "What are the columns in the 'products' table?" - * "How many orders were placed in the last 30 days, and what were the top 5 most purchased items?" +## Supported Skills -* **Generate Code:** - * "Generate a Python dataclass to represent the 'customers' tab +The following skills are available in this repository: -## Supported Tools +- [Spanner Data](./skills/spanner-data/SKILL.md) - Use these skills when you need to explore the database structure, discover schema objects like tables and graphs, and execute custom SQL queries to interact with your data. -* `list_tables`: Use this tool to list tables and descriptions. -* `list_graphs`: Use this tool to lists graphs in the database. -* `execute_sql`: Use this tool to execute any SQL statement. -* `execute_sql_dql`: Use this tool to execute DQL SQL statement. +## Additional Agent Skills -## Additional Extensions +Find additional skills to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions), including: -Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). +- [Generic PostgreSQL skills](https://github.com/gemini-cli-extensions/postgres) +- [Cloud SQL for PostgreSQL skills](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) +- and more! ## Troubleshooting -Use `gemini --debug` to enable debugging. +Use the debug mode of your agent (e.g., `gemini --debug`) to enable debugging. Common issues: -* "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) 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://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. +- "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) 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 .../toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using the latest version of your agent. +- "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://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. From 0069452a87048fd786bcc4b9f518f44a447d73da Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 15:43:58 +0530 Subject: [PATCH 2/3] revert readme chnges --- README.md | 267 ++++++++++++++---------------------------------------- 1 file changed, 69 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index e014ea5..b0c2e45 100644 --- a/README.md +++ b/README.md @@ -1,251 +1,122 @@ -# Spanner Agent Skills +# Gemini CLI Extension - Spanner > [!NOTE] -> Currently in beta (pre-v1.0), 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 repository provides a set of agent skills to interact with [Google Cloud Spanner](https://cloud.google.com/spanner/docs) instances. These skills can be used with various AI agents, including [Gemini CLI](https://google-gemini.github.io/gemini-cli/), Claude Code, and Codex, to manage your databases, execute queries, explore schemas, and troubleshoot issues using natural language prompts. +This Gemini CLI extension provides a set of tools to interact with [Google Cloud Spanner](https://cloud.google.com/spanner/docs) instances. It allows you to manage your databases, execute queries, and explore schemas directly from the [Gemini CLI](https://google-gemini.github.io/gemini-cli/), using natural language prompts. +Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md). > [!IMPORTANT] > **We Want Your Feedback!** -> Please share your thoughts with us by filling out our feedback [form][form]. +> Please share your thoughts with us by filling out our feedback [form][form]. > Your input is invaluable and helps us improve the project for everyone. [form]: https://docs.google.com/forms/d/e/1FAIpQLSfEGmLR46iipyNTgwTmIDJqzkAwDPXxbocpXpUbHXydiN1RTw/viewform?usp=pp_url&entry.157487=spanner -## Table of Contents - -- [Why Use Spanner Agent Skills?](#why-use-spanner-agent-skills) -- [Prerequisites](#prerequisites) -- [Getting Started](#getting-started) - - [Configuration](#configuration) - - [Installation & Usage](#installation--usage) - - [Gemini CLI](#gemini-cli) - - [Claude Code](#claude-code) - - [Codex](#codex) - - [Antigravity](#antigravity) -- [Usage Examples](#usage-examples) -- [Supported Skills](#supported-skills) -- [Additional Agent Skills](#additional-agent-skills) -- [Troubleshooting](#troubleshooting) - -## Why Use Spanner Agent Skills? - -- **Seamless Workflow:** Integrates seamlessly into your AI agent's environment. No need to constantly switch contexts for common database tasks. -- **Natural Language Queries:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. -- **Full Lifecycle Control:** Manage your Spanner databases, from exploring schemas to running queries. -- **Code Generation:** Accelerate development by asking your agent to generate data classes and other code snippets based on your table schemas. +## Why Use the Spanner Extension? + +* **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. +* **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. +* **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: -- One of these AI agents installed - - [Gemini CLI](https://github.com/google-gemini/gemini-cli) version **v0.6.0** or higher - - [Claude Code](https://claude.com/product/claude-code) version **v2.1.94** or higher - - [Codex](https://developers.openai.com/codex) **v0.117.0** or higher - - [Antigravity](https://antigravity.google) **v1.14.2** or higher -- A Google Cloud project with the **Spanner API** enabled. -- Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -- IAM Permissions: - - Cloud Spanner Database Reader (`roles/spanner.databaseReader`) - - Cloud Spanner Database User (`roles/spanner.databaseUser`) +* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version **+v0.6.0**. +* Setup Gemini CLI [Authentication](https://github.com/google-gemini/gemini-cli/tree/main?tab=readme-ov-file#-authentication-options). +* A Google Cloud project with the **Spanner API** enabled. +* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. +* IAM Permissions + * Cloud Spanner Database Reader (`roles/spanner.databaseReader`) + * Cloud Spanner Database User (`roles/spanner.databaseUser`) ## Getting Started -### Configuration - -Please keep these env vars handy during the installation process: - -- `SPANNER_PROJECT`: The GCP project ID. -- `SPANNER_INSTANCE`: The Spanner instance ID. -- `SPANNER_DATABASE`: The Spanner database ID. -- `SPANNER_DIALECT`: (Optional) The SQL dialect of the Spanner Database: 'googlesql' or 'postgresql'. Defaults to "googlesql". - -> [!NOTE] -> -> - Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. - -### Installation & Usage +### Installation -To start interacting with your database, install the skills for your preferred AI agent, then launch the agent and use natural language to ask questions or perform tasks. - -For the latest version, check the [releases page][releases]. - -[releases]: https://github.com/gemini-cli-extensions/spanner/releases - - - -
-Gemini CLI - -**1. Install the extension:** +To install the extension, use the command: ```bash gemini extensions install https://github.com/gemini-cli-extensions/spanner ``` -During the installation, enter your environment vars as described in the [configuration section](#configuration). - -**2. (Optional) Manage Configuration:** -To view or update your configuration in Gemini CLI: - -- Terminal: `gemini extensions config spanner [setting name] [--scope ]` -- Gemini CLI: `/extensions list` - -**3. Start the agent:** - -```bash -gemini -``` - -_(Tip: Run `/extensions list` to verify your configuration and active extensions.)_ - -> [!WARNING] -> **Changing Instance & Database Connections** -> Currently, the database connection must be configured before starting the agent and can not be changed during a session. -> To save and resume conversation history in Gemini CLI use command: `/chat save ` and `/chat resume `. - -
- -
-Claude Code - -**1. Set env vars:** -In your terminal, set your environment vars as described in the [configuration section](#configuration). - -**2. Start the agent:** - -```bash -claude -``` - -**3. Add the marketplace:** - -```bash -/plugin marketplace add https://github.com/gemini-cli-extensions/spanner.git#0.2.6 -``` - -**4. Install the plugin:** - -```bash -/plugin install spanner@spanner-marketplace -``` - -_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_ - -
- -
-Codex - -**1. Clone the Repo:** - -```bash -git clone --branch 0.2.6 git@github.com:gemini-cli-extensions/spanner.git -``` - -**2. Install the plugin:** +### Configuration -```bash -mkdir -p ~/.codex/plugins -cp -R /absolute/path/to/spanner ~/.codex/plugins/spanner -``` +You will be prompted to configure the following settings during installation. These settings are saved in an `.env` file within the extension's directory. -**3. Set env vars:** -Enter your environment vars as described in the [configuration section](#configuration). - -**4. Create or update marketplace.json:** -`~/.agents/plugins/marketplace.json` - -```json -{ - "name": "my-data-cloud-google-marketplace", - "interface": { - "displayName": "Google Data Cloud Skills" - }, - "plugins": [ - { - "name": "spanner", - "source": { - "source": "local", - "path": "./plugins/spanner" - }, - "policy": { - "installation": "AVAILABLE", - "authentication": "ON_INSTALL" - }, - "category": "Database" - } - ] -} -``` +* `SPANNER_PROJECT`: The GCP project ID. +* `SPANNER_INSTANCE`: The Spanner instance ID. +* `SPANNER_DATABASE`: The Spanner database ID. +* `SPANNER_DIALECT`: (Optional) The SQL dialect of the Spanner database: 'googlesql' or 'postgresql'. Defaults to "googlesql". -_(Tip: Run `codex plugin list` or use the `/plugins` interactive menu to verify your installed plugins.)_ +To view or update your configuration: -
+**List Settings:** +* Terminal: `gemini extensions list` +* Gemini CLI: `/extensions list` -
-Antigravity +**Update Settings:** +* Terminal: `gemini extensions config spanner [setting name] [--scope ]` + * `setting name`: (Optional) The single setting to configure. + * `scope`: (Optional) The scope of the setting in (`user` or `workspace`). Defaults to `user`. +* Currently, you must restart the Gemini CLI for changes to take effect. We recommend using `gemini --resume` to resume your session. -**1. Clone the Repo:** +Alternatively, you can manually set these environment variables before starting the Gemini CLI: ```bash -git clone --branch 0.2.6 https://github.com/gemini-cli-extensions/spanner.git +export SPANNER_PROJECT="" +export SPANNER_INSTANCE="" +export SPANNER_DATABASE="" +export SPANNER_DIALECT="googlesql" # Optional: "googlesql" or "postgresql". Defaults to "googlesql". ``` -**2. Install the skills:** +> [!NOTE] +> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. +> * See [Troubleshooting](#troubleshooting) for debugging your configuration. -Choose a location for the skills: -- **Global (all workspaces):** `~/.gemini/antigravity/skills/` -- **Workspace-specific:** `/.agents/skills/` +### Start Gemini CLI -Copy the skill folders from the cloned repository's `skills/` directory to your chosen location: +To start the Gemini CLI, use the following command: ```bash -cp -R spanner/skills/* ~/.gemini/antigravity/skills/ +gemini ``` -**3. Set env vars:** -Set your environment vars as described in the [configuration section](#configuration). - -_(Tip: Antigravity automatically discovers skills in these directories at the start of a session.)_ - -
- - - -## Usage Examples - -Interact with Spanner using natural language: +> [!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 `. -- **Explore Schemas and Data:** - - "Show me all tables in the 'orders' database." - - "What are the columns in the 'products' table?" - - "How many orders were placed in the last 30 days, and what were the top 5 most purchased items?" -- **Generate Code:** - - "Generate a Python dataclass to represent the 'customers' table." +## Usage -## Supported Skills +* **Explore Schemas and Data:** + * "Show me all tables in the 'orders' database." + * "What are the columns in the 'products' table?" + * "How many orders were placed in the last 30 days, and what were the top 5 most purchased items?" -The following skills are available in this repository: +* **Generate Code:** + * "Generate a Python dataclass to represent the 'customers' tab -- [Spanner Data](./skills/spanner-data/SKILL.md) - Use these skills when you need to explore the database structure, discover schema objects like tables and graphs, and execute custom SQL queries to interact with your data. +## Supported Tools -## Additional Agent Skills +* `list_tables`: Use this tool to list tables and descriptions. +* `list_graphs`: Use this tool to lists graphs in the database. +* `execute_sql`: Use this tool to execute any SQL statement. +* `execute_sql_dql`: Use this tool to execute DQL SQL statement. -Find additional skills to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions), including: +## Additional Extensions -- [Generic PostgreSQL skills](https://github.com/gemini-cli-extensions/postgres) -- [Cloud SQL for PostgreSQL skills](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) -- and more! +Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). ## Troubleshooting -Use the debug mode of your agent (e.g., `gemini --debug`) to enable debugging. +Use `gemini --debug` to enable debugging. Common issues: -- "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) 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 .../toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using the latest version of your agent. -- "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://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. +* "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) 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://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. From 1678f7b412d24bee051350ffa70c41b2d2407b72 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Wed, 15 Apr 2026 22:42:46 +0530 Subject: [PATCH 3/3] added marketplace descritpion --- .claude-plugin/marketplace.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e326265..565f6af 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -3,6 +3,9 @@ "interface": { "displayName": "Spanner Agent Skills" }, + "metadata": { + "description": "Agent skills to connect and interact with Spanner data using natural language." + }, "plugins": [ { "name": "spanner",