diff --git a/POSTGRESQL.md b/POSTGRESQL.md index b42eb37..3bb07f1 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..5739ef1 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,11 @@ 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. - -## Supported Tools - -* list-tables: Use this tool to list tables and descriptions. -* execute-sql: Use this tool to execute any SQL statement. +* **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. +* **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas. ## Prerequisites @@ -20,34 +14,47 @@ 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 +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 -## Usage +Interact with Postgres using natural language right from your IDE: -* Explore Schemas and Data -* Generate code +* **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." + +## Supported Tools +* `list_tables`: Lists tables in the database. +* `execute_sql`: Executes a SQL query. -## Security +## Additional Extensions -This extension executes commands against your PostgreSQL database. Always review the generated SQL queries before execution, especially for write operations. +Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). -## Disclaimer +## Troubleshooting -This is not an officially supported Google product. This extension is under active development, and breaking changes may be introduced. +* "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 c3aa8dd..044d6cb 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,7 +1,7 @@ { - "name": "PostgreSQL", + "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",