Merge branch 'main' into basic-presubmit

twishabansal · web-flow · commit 246db409ca48 · 2025-09-26T11:37:08.000+05:30
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -3,4 +3,4 @@
 # For syntax help see:
 # https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax
 
-*   @googleapis/senseai-eco
+* @gemini-cli-extensions/senseai-eco @gemini-cli-extensions/postgres-maintainers
diff --git a/.github/renovate.json5 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: ["(?<currentValue>[\\d\\.]+)"],
+      datasourceTemplate: "github-releases",
+      packageNameTemplate: "googleapis/genai-toolbox",
+      extractVersionTemplate: "^v(?<version>.*)$",
+    }
+  ]
+}
diff --git a/.github/workflows/json-lint.yml 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@v4
+
+      - name: Run JSON Lint
+        run: jq . gemini-extension.json
diff --git a/.github/workflows/markdown-checks.yml 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@v4
+
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v2.0.2
+        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
@@ -66,7 +66,9 @@ jobs:
           
           echo "Downloading binary from: ${DOWNLOAD_URL}"
           curl -L --fail -o "${SOURCE_BINARY}" "${DOWNLOAD_URL}"
-          
+
+          chmod +x ${SOURCE_BINARY}
+
           echo "Binary downloaded and prepared."
           ls -l
 
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.0.0"
+  ".": "0.1.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2025-09-21)
+
+
+### Features
+
+* Add Postgres Extension 
diff --git a/README.md b/README.md
@@ -1,7 +1,12 @@
 # Gemini CLI Extension - PostgreSQL
 
+> [!NOTE]
+> 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 [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.
 
+Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md).
+
 ## Why Use the Postgres Extension?
 
 *   **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English.
@@ -12,7 +17,7 @@ This Gemini CLI extension provides a set of tools to interact with [PostgreSQL](
 
 Before you begin, ensure you have the following:
 
-*   [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed.
+*   [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version **+v0.6.0**.
 *   A running PostgreSQL instance.
 *   User are granted database-level permissions to execute queries.
 
@@ -21,7 +26,7 @@ Before you begin, ensure you have the following:
 To install the extension, use the command:
 
 ```bash
-gemini extensions install github.com/gemini-cli-extensions/postgres
+gemini extensions install https://github.com/gemini-cli-extensions/postgres
 ```
 
 ## Configuration
diff --git a/gemini-extension.json b/gemini-extension.json
@@ -1,6 +1,6 @@
 {
   "name": "postgres",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Connect and interact with a PostgreSQL database and data",
   "mcpServers": {
     "PostgreSQL": {
diff --git a/release-please-config.json b/release-please-config.json
@@ -1,6 +1,8 @@
 {
   "bump-minor-pre-major": true,
   "bump-patch-for-minor-pre-major": true,
+  "include-component-in-tag": false,
+  "include-v-in-tag": false,
   "changelog-sections": [
     {
       "type": "feat",
diff --git a/tutorials/index.md b/tutorials/index.md
@@ -0,0 +1,9 @@
+# Tutorials
+
+This guide will help you get started with the PostgreSQL extension for the Gemini CLI.
+
+## Guides & Samples
+
+| Sample | Description |
+| ------ | ----------- |
+| [Quick Start](./quickstart.md) | This tutorial demonstrates how to get started with the Postgres extension. |
diff --git a/tutorials/quickstart.md b/tutorials/quickstart.md
@@ -0,0 +1,202 @@
+# Quickstart: Using the PostgreSQL Extension
+
+Gemini CLI includes a pre-built extension for connecting to any PostgreSQL database, allowing you to query and manage your database using natural language.
+
+## Prerequisites
+
+### Set up the database
+
+1. Create or select a PostgreSQL instance.
+
+    * [Install PostgreSQL locally](https://www.postgresql.org/download/)
+    * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/quickstart)
+
+1. Create or reuse [a database
+   user](https://cloud.google.com/alloydb/omni/current/docs/database-users/manage-users)
+   and have the username and password ready.
+
+### Installation
+
+1. Install the latest [Gemini CLI](https://github.com/google-gemini/gemini-cli):
+
+    ```bash
+    npm install -g @google/gemini-cli@latest
+    ```
+
+1. Install the extension:
+
+    ```bash
+    gemini extensions install https://github.com/gemini-cli-extensions/postgres
+    ```
+
+## Configuration
+
+After activating the extension, configure it by setting the following environment variables:
+
+- `POSTGRES_HOST`: The hostname or IP address of the PostgreSQL server.
+- `POSTGRES_PORT`: The port number for the PostgreSQL server.
+- `POSTGRES_DATABASE`: The name of the database to connect to.
+- `POSTGRES_USER`: The database username.
+- `POSTGRES_PASSWORD`: The password for the database user.
+- `POSTGRES_QUERY_PARAMS`: (Optional) Raw query to be added to the db connection string.
+
+### Permissions
+
+Ensure the configured database user has the necessary database-level permissions (e.g., `SELECT`, `INSERT`) to execute the desired queries.
+
+## Supported Tools
+
+This extension provides the following tools. Note that these can be used in combination with core Gemini CLI tools (like `write_file` and `run_shell_command`).
+
+- `execute_sql`: Executes a SQL query.
+- `list_tables`: Lists tables in the database.
+- `list_autovacuum_configurations`: Lists autovacuum configurations in the database.
+- `list_memory_configurations`: Lists memory-related configurations in the database.
+- `list_top_bloated_tables`: Lists the top bloated tables in the database.
+- `list_replication_slots`: Lists replication slots in the database.
+- `list_invalid_indexes`: Lists invalid indexes in the database.
+- `get_query_plan`: Generates the execution plan of a statement.
+
+## Usage Examples
+
+### A Developer's Story
+
+This section follows a developer, Alex, as they use the PostgreSQL extension to diagnose a slow user profile page in their application.
+
+#### Step 1: Exploring the Schema
+
+Alex's first step is to understand the database structure related to user profiles.
+
+> "List all tables in the database."
+*Tool Used*: `list_tables`
+
+#### Step 2: Analyzing the Slow Query
+
+After identifying the `users` and `user_profiles` tables, Alex suspects the query joining them is inefficient. They decide to check the execution plan.
+
+> "What is the execution plan for the query 'SELECT * FROM users u JOIN user_profiles up ON u.id = up.user_id WHERE u.id = 123'?"
+*Tool Used*: `get_query_plan`
+
+#### Step 3: Discovering an Indexing Problem
+
+The query plan reveals a slow sequential scan. Alex wonders if there's an issue with the indexes on the tables.
+
+> "Show me all invalid indexes."
+*Tool Used*: `list_invalid_indexes`
+
+#### Step 4: Checking Overall Database Health
+
+Finding an invalid index prompts Alex to run a broader health check, looking for other common performance issues like table bloat.
+
+> "Show me the top 10 most bloated tables."
+*Tool Used*: `list_top_bloated_tables`
+
+### Conclusion
+
+In just a few minutes, using natural language, Alex has gone from a vague performance complaint to a concrete action plan: fix the invalid index and address table bloat. This demonstrates how the extension can accelerate development and debugging workflows.
+
+### Data Analyst Journey: Extracting Data for a Report
+
+Maria, a data analyst, needs to pull data for a sales report.
+
+#### Step 1: Find Relevant Tables
+Maria starts by looking for tables related to sales and customers.
+> "List all tables that have 'sales' or 'customers' in their names."
+*Tool Used*: `list_tables`
+
+#### Step 2: Explore Table Schemas
+To understand how to join them, she inspects the schemas.
+> "Show me the schema for the 'sales' and 'customers' tables."
+*Tool Used*: `execute_sql`
+
+#### Step 3: Query the Data
+Maria writes a query to get the total sales for each customer.
+> "Write a SQL query to get the total sales amount for each customer by joining the 'sales' and 'customers' tables on the customer ID."
+*Tool Used*: `execute_sql`
+
+#### Step 4: Save the Results
+She saves the data to a CSV file for her report.
+> "Save the results of the previous query to a file named 'sales_by_customer.csv'."
+*Tool Used*: `write_file`
+
+### Database Administrator (DBA) Journey: Routine Maintenance
+
+David, a DBA, performs his daily checks to ensure the database is healthy.
+
+#### Step 1: Check for Long-Running Queries
+David looks for queries that might be slowing down the system.
+> "Are there any queries that have been running for more than 10 minutes?"
+*Tool Used*: `execute_sql` (querying `pg_stat_activity`)
+
+#### Step 2: Review Autovacuum Configurations
+He reviews the autovacuum settings to ensure they are optimized for the workload.
+> "Show me the autovacuum configurations."
+*Tool Used*: `list_autovacuum_configurations`
+
+#### Step 3: Check Memory Configurations
+David checks the memory-related configurations to prevent performance bottlenecks.
+> "List all memory-related configurations."
+*Tool Used*: `list_memory_configurations`
+
+#### Step 4: Monitor Database Size
+He checks the overall size of the database to track its growth.
+> "What's the total size of the database?"
+*Tool Used*: `execute_sql` (using `pg_database_size()`)
+
+#### Step 5: Verify Replication Status
+David ensures that the read replicas are in sync.
+> "Show me the current replication status and lag."
+*Tool Used*: `list_replication_slots`
+
+#### Step 6: Initiate a Backup
+He kicks off a manual backup of a critical database.
+> "Create a backup of the 'production' database and store it in the '/backups' directory."
+*Tool Used*: `run_shell_command` (using `pg_dump`)
+
+### New Developer Onboarding Journey: Learning the Ropes
+
+Sarah, a new developer, is getting acquainted with the project's database.
+
+#### Step 1: Get an Overview
+Her first step is to see all the tables in the database.
+> "List all the tables in the database."
+*Tool Used*: `list_tables`
+
+#### Step 2: Examine a Table
+She decides to dive deeper into the `products` table.
+> "Show me the columns and their data types for the 'products' table."
+*Tool Used*: `execute_sql`
+
+#### Step 3: Preview Table Data
+Sarah wants to see some sample data to understand the content.
+> "Show me the first 5 rows from the 'products' table."
+*Tool Used*: `execute_sql`
+
+#### Step 4: Understand Table Relationships
+She wants to know how products relate to other tables.
+> "What are the foreign key relationships for the 'products' table?"
+*Tool Used*: `execute_sql`
+
+### Test Data Generation Journey: Populating a New Table
+
+A developer, Sam, needs to create some test data for a new `products` table.
+
+#### Step 1: Create the Table
+Sam first needs to create the `products` table.
+> "Create a table named 'products' with columns for 'id' (integer, primary key), 'name' (varchar), and 'price' (decimal)."
+*Tool Used*: `execute_sql`
+
+#### Step 2: Insert a Single Row
+Sam inserts a single product to verify the table structure.
+> "Insert a product with id 1, name 'Laptop', and price 1200.00 into the 'products' table."
+*Tool Used*: `execute_sql`
+
+#### Step 3: Insert Multiple Rows
+Now, Sam wants to add a few more products in a single command.
+> "Insert the following products into the 'products' table: (2, 'Keyboard', 75.00), (3, 'Mouse', 25.00), (4, 'Monitor', 300.00)."
+*Tool Used*: `execute_sql`
+
+#### Step 4: Verify the Data
+Finally, Sam checks that the data was inserted correctly.
+> "Show me all the data from the 'products' table."
+*Tool Used*: `execute_sql`

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "0.0.0"`
	`2`	`+ ".": "0.1.0"`
`3`	`3`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "postgres",`
`3`		`- "version": "0.0.0",`
	`3`	`+ "version": "0.1.0",`
`4`	`4`	`"description": "Connect and interact with a PostgreSQL database and data",`
`5`	`5`	`"mcpServers": {`
`6`	`6`	`"PostgreSQL": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"bump-minor-pre-major": true,`
`3`	`3`	`"bump-patch-for-minor-pre-major": true,`
	`4`	`+ "include-component-in-tag": false,`
	`5`	`+ "include-v-in-tag": false,`
`4`	`6`	`"changelog-sections": [`
`5`	`7`	`{`
`6`	`8`	`"type": "feat",`