From a4650f8fc5d3a0d136662204d1eabdb1b9c972fe Mon Sep 17 00:00:00 2001 From: Yuan Teoh Date: Tue, 16 Sep 2025 14:26:51 -0700 Subject: [PATCH 1/3] docs: update files --- POSTGRESQL.md | 15 +++++++++++---- README.md | 18 +++++++----------- gemini-extension.json | 2 +- 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/POSTGRESQL.md b/POSTGRESQL.md index b42eb37..16ee96f 100644 --- a/POSTGRESQL.md +++ b/POSTGRESQL.md @@ -1,12 +1,16 @@ -# PostgreSQL Extension +You are a highly skilled database engineer and database administrator. Your purpose is to +help the developer build and interact with databases and utilize data context throughout the entire +software delivery cycle. -This document provides instructions for the Gemini agent to assist users with the PostgreSQL extension. +-- + +# Setup ## PostgreSQL MCP Server (Data Plane: Connecting and Querying) This section covers connecting to a PostgreSQL database instance. -1. **Verify Environment Variables**: Before attempting to connect, confirm with the user that the following environment variables are set in the extension configuration or their shell environment. +1. **Verify Environment Variables**: The extension requires the following environment variables to be set before the Gemini CLI is started: * `POSTGRES_HOST`: The hostname or IP address of the PostgreSQL server. * `POSTGRES_PORT`: The port number of the PostgreSQL server. @@ -16,4 +20,7 @@ This section covers connecting to a PostgreSQL database instance. 2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${POSTGRES_HOST}`, 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 privileges on the PostgreSQL database. +3. **Handle Permission Errors**: If an operation fails due to permission, it is + likely that the user do not have the correct privileges on the PostgreSQL + database. Database-level permissions (e.g., `SELECT`, `INSERT`) are required + to execute queries. diff --git a/README.md b/README.md index 1b0ec1a..3c14ddb 100644 --- a/README.md +++ b/README.md @@ -9,21 +9,17 @@ This Gemini CLI extension provides a set of tools to interact with [PostgreSQL]( * **Explore Database Schema:** List databases, tables, views, and schemas. * **Query your Database:** Execute SQL queries against your database. -## Supported Tools - -* list-tables: Use this tool to list tables and descriptions. -* execute-sql: Use this tool to execute any SQL statement. - ## Prerequisites Before you begin, ensure you have the following: * [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed. * A running PostgreSQL instance. +* User are granted database-level permissions to execute queries. ## Installation -To install the extension, use the `gemini extensions install` command: +To install the extension, use the command: ```bash gemini extensions install github.com/gemini-cli-extensions/postgresql.git @@ -43,11 +39,11 @@ gemini extensions install github.com/gemini-cli-extensions/postgresql.git * Explore Schemas and Data * Generate code +## Supported Tools -## Security - -This extension executes commands against your PostgreSQL database. Always review the generated SQL queries before execution, especially for write operations. +* `list_tables`: Use this tool to list tables and descriptions. +* `execute_sql`: Use this tool to execute any SQL statement. -## Disclaimer +## Security -This is not an officially supported Google product. This extension is under active development, and breaking changes may be introduced. +This extension executes commands against your PostgreSQL database. Always review the generated SQL queries before execution, especially for write operations. \ No newline at end of file diff --git a/gemini-extension.json b/gemini-extension.json index c3aa8dd..2d48738 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,5 +1,5 @@ { - "name": "PostgreSQL", + "name": "postgres", "version": "0.1.0", "description": "Connect to PostgreSQL", "mcpServers": { From d9f75b1768a695e98f28dae8c4ab3bbf47786968 Mon Sep 17 00:00:00 2001 From: Yuan Teoh Date: Wed, 17 Sep 2025 11:37:08 -0700 Subject: [PATCH 2/3] update files --- POSTGRESQL.md | 2 +- README.md | 38 +++++++++++++++++++++++++------------- gemini-extension.json | 2 +- 3 files changed, 27 insertions(+), 15 deletions(-) diff --git a/POSTGRESQL.md b/POSTGRESQL.md index 16ee96f..3bb07f1 100644 --- a/POSTGRESQL.md +++ b/POSTGRESQL.md @@ -2,7 +2,7 @@ You are a highly skilled database engineer and database administrator. Your purp help the developer build and interact with databases and utilize data context throughout the entire software delivery cycle. --- +--- # Setup diff --git a/README.md b/README.md index 3c14ddb..d316403 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ This Gemini CLI extension provides a set of tools to interact with [PostgreSQL](https://www.postgresql.org/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. -## Features +## Why Use the Postgres Extension? -* **Integrated with Gemini CLI:** As a Google-developed extension, it integrates seamlessly into the Gemini CLI environment, making security an accessible part of your workflow. -* **Connect to PostgreSQL:** Securely connect to your PostgreSQL instances. -* **Explore Database Schema:** List databases, tables, views, and schemas. -* **Query your Database:** Execute SQL queries against your database. +* **Natural Language Management:** Stop wrestling with complex commands. Provision infrastructure, manage users, and query data by describing what you want in plain English. +* **Seamless Workflow:** Stay in your CLI. No need to constantly switch contexts to the GCP console for common database tasks. +* **Full Lifecycle Control:** Manage the entire lifecycle of your database, from creating clusters and instances to exploring schemas and running queries. +* **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas. ## Prerequisites @@ -22,28 +22,40 @@ Before you begin, ensure you have the following: To install the extension, use the command: ```bash -gemini extensions install github.com/gemini-cli-extensions/postgresql.git +gemini extensions install github.com/gemini-cli-extensions/postgres ``` ## Configuration +Set the following environment variables before starting the Gemini CLI: + * `POSTGRES_HOST`: The hostname or IP address of the PostgreSQL server. * `POSTGRES_PORT`: The port number of the PostgreSQL server. * `POSTGRES_DATABASE`: The name of the database to connect to. * `POSTGRES_USER`: The username for authentication. * `POSTGRES_PASSWORD`: The password for authentication. +## Usage Examples + +Interact with Postgres using natural language right from your IDE: -## 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?" -* Explore Schemas and Data -* Generate code +* **Generate Code:** + * "Generate a Python dataclass to represent the 'customers' table." ## Supported Tools -* `list_tables`: Use this tool to list tables and descriptions. -* `execute_sql`: Use this tool to execute any SQL statement. +* `list_tables`: Lists tables in the database. +* `execute_sql`: Executes a SQL query. + +## Additional Extensions + +Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). -## Security +## Troubleshooting -This extension executes commands against your PostgreSQL database. Always review the generated SQL queries before execution, especially for write operations. \ No newline at end of file +* "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. \ No newline at end of file diff --git a/gemini-extension.json b/gemini-extension.json index 2d48738..044d6cb 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,7 +1,7 @@ { "name": "postgres", "version": "0.1.0", - "description": "Connect to PostgreSQL", + "description": "Connect and interact with a PostgreSQL database and data", "mcpServers": { "PostgreSQL": { "command": "${extensionPath}${/}toolbox", From 64e9d3744ab4409d06327cf497fb1a55db701699 Mon Sep 17 00:00:00 2001 From: Averi Kitsch Date: Wed, 17 Sep 2025 13:48:22 -0700 Subject: [PATCH 3/3] Apply suggestions from code review --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index d316403..5739ef1 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,8 @@ This Gemini CLI extension provides a set of tools to interact with [PostgreSQL]( ## Why Use the Postgres Extension? -* **Natural Language Management:** Stop wrestling with complex commands. Provision infrastructure, manage users, and query data by describing what you want in plain English. +* **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. * **Seamless Workflow:** Stay in your CLI. No need to constantly switch contexts to the GCP console for common database tasks. -* **Full Lifecycle Control:** Manage the entire lifecycle of your database, from creating clusters and instances to exploring schemas and running queries. * **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas. ## Prerequisites