wehub/googleapis--mcp-toolbox
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
CF: Deploy Dev Docs / deploy (push) Has been cancelled
Details
Sync Labels / build (push) Has been cancelled
Details
tests / unit tests (macos-latest) (push) Has been cancelled
Details
tests / unit tests (windows-latest) (push) Has been cancelled
Details
tests / unit tests (ubuntu-latest) (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:32:45 +08:00
commit e04ed9c211
1798 changed files with 307905 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/integrations/postgres/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: "PostgreSQL"
weight: 1
---
docs/en/integrations/postgres/prebuilt-configs/_index.md
+5
View File
@@ -0,0 +1,5 @@
---
title: "Prebuilt Configs"
type: docs
description: "Prebuilt configurations for Postgres."
---
docs/en/integrations/postgres/prebuilt-configs/alloydb-omni.md
+52
View File
@@ -0,0 +1,52 @@
---
title: "AlloyDB Omni"
type: docs
description: "Details of the AlloyDB Omni prebuilt configuration."
---
## AlloyDB Omni
* `--prebuilt` value: `alloydb-omni`
* **Environment Variables:**
* `ALLOYDB_OMNI_HOST`: (Optional) The hostname or IP address (Default: localhost).
* `ALLOYDB_OMNI_PORT`: (Optional) The port number (Default: 5432).
* `ALLOYDB_OMNI_DATABASE`: The name of the database to connect to.
* `ALLOYDB_OMNI_USER`: The database username.
* `ALLOYDB_OMNI_PASSWORD`: (Optional) The password for the database user.
* `ALLOYDB_OMNI_QUERY_PARAMS`: (Optional) Connection query parameters.
* **Tools:**
* `execute_sql`: Executes a SQL query.
* `list_tables`: Lists tables in the database.
* `list_active_queries`: Lists ongoing queries.
* `list_available_extensions`: Discover all PostgreSQL extensions available for installation.
* `list_installed_extensions`: List all installed PostgreSQL extensions.
* `long_running_transactions`: Identifies and lists database transactions that exceed a specified time limit.
* `list_locks`: Identifies all locks held by active processes.
* `replication_stats`: Lists each replica's process ID and sync state.
* `list_autovacuum_configurations`: Lists autovacuum configurations in the
database.
* `list_columnar_configurations`: List AlloyDB Omni columnar-related configurations.
* `list_columnar_recommended_columns`: Lists columns that AlloyDB Omni recommends adding to the columnar engine.
* `list_memory_configurations`: Lists memory-related configurations in the
database.
* `list_top_bloated_tables`: List 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`: Generate the execution plan of a statement.
* `list_views`: Lists views in the database from pg_views with a default
limit of 50 rows. Returns schemaname, viewname and the ownername.
* `list_schemas`: Lists schemas in the database.
* `database_overview`: Fetches the current state of the PostgreSQL server.
* `list_triggers`: Lists triggers in the database.
* `list_indexes`: List available user indexes in a PostgreSQL database.
* `list_sequences`: List sequences in a PostgreSQL database.
* `list_query_stats`: Lists query statistics.
* `get_column_cardinality`: Gets column cardinality.
* `list_table_stats`: Lists table statistics.
* `list_publication_tables`: List publication tables in a PostgreSQL database.
* `list_tablespaces`: Lists tablespaces in the database.
* `list_pg_settings`: List configuration parameters for the PostgreSQL server.
* `list_database_stats`: Lists the key performance and activity statistics for
each database in the AlloyDB instance.
* `list_roles`: Lists all the user-created roles in PostgreSQL database.
* `list_stored_procedure`: Lists stored procedures.
docs/en/integrations/postgres/prebuilt-configs/postgresql.md
+54
View File
@@ -0,0 +1,54 @@
---
title: "PostgreSQL"
type: docs
description: "Details of the PostgreSQL prebuilt configuration."
---
## PostgreSQL
* `--prebuilt` value: `postgres`
* **Environment Variables:**
* `POSTGRES_HOST`: (Optional) The hostname or IP address of the PostgreSQL server.
* `POSTGRES_PORT`: (Optional) 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:**
* Database-level permissions (e.g., `SELECT`, `INSERT`) are required to
execute queries.
* **Tools:**
* `execute_sql`: Executes a SQL query.
* `list_tables`: Lists tables in the database.
* `list_active_queries`: Lists ongoing queries.
* `list_available_extensions`: Discover all PostgreSQL extensions available for installation.
* `list_installed_extensions`: List all installed PostgreSQL extensions.
* `long_running_transactions`: Identifies and lists database transactions that exceed a specified time limit.
* `list_locks`: Identifies all locks held by active processes.
* `replication_stats`: Lists each replica's process ID and sync state.
* `list_autovacuum_configurations`: Lists autovacuum configurations in the
database.
* `list_memory_configurations`: Lists memory-related configurations in the
database.
* `list_top_bloated_tables`: List 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`: Generate the execution plan of a statement.
* `list_views`: Lists views in the database from pg_views with a default
limit of 50 rows. Returns schemaname, viewname and the ownername.
* `list_schemas`: Lists schemas in the database.
* `database_overview`: Fetches the current state of the PostgreSQL server.
* `list_triggers`: Lists triggers in the database.
* `list_indexes`: List available user indexes in a PostgreSQL database.
* `list_sequences`: List sequences in a PostgreSQL database.
* `list_query_stats`: Lists query statistics.
* `get_column_cardinality`: Gets column cardinality.
* `list_table_stats`: Lists table statistics.
* `list_publication_tables`: List publication tables in a PostgreSQL database.
* `list_tablespaces`: Lists tablespaces in the database.
* `list_pg_settings`: List configuration parameters for the PostgreSQL server.
* `list_database_stats`: Lists the key performance and activity statistics for
each database in the PostgreSQL server.
* `list_roles`: Lists all the user-created roles in PostgreSQL database.
* `list_stored_procedure`: Lists stored procedures.
docs/en/integrations/postgres/source.md
+69
View File
@@ -0,0 +1,69 @@
---
title: "PostgreSQL Source"
linkTitle: "Source"
type: docs
weight: 1
description: >
PostgreSQL is a powerful, open source object-relational database.
no_list: true
---
## About
[PostgreSQL][pg-docs] is a powerful, open source object-relational database
system with over 35 years of active development that has earned it a strong
reputation for reliability, feature robustness, and performance.
[pg-docs]: https://www.postgresql.org/
## Available Tools
{{< list-tools >}}
### Pre-built Configurations
- [PostgreSQL using MCP](../../documentation/connect-to/ides/postgres_mcp.md)
Connect your IDE to PostgreSQL using Toolbox.
## Requirements
### Database User
This source only uses standard authentication. You will need to [create a
PostgreSQL user][pg-users] to login to the database with.
[pg-users]: https://www.postgresql.org/docs/current/sql-createuser.html
## Example
```yaml
kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: my_db
user: ${USER_NAME}
password: ${PASSWORD}
```
{{< notice tip >}}
Use environment variable replacement with the format ${ENV_NAME}
instead of hardcoding your secrets into the configuration file.
{{< /notice >}}
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:------------------:|:------------:|------------------------------------------------------------------------|
| type | string | true | Must be "postgres". |
| host | string | true | IP address to connect to (e.g. "127.0.0.1") |
| port | string | true | Port to connect to (e.g. "5432") |
| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). |
| user | string | true | Name of the Postgres user to connect as (e.g. "my-pg-user"). |
| password | string | true | Password of the Postgres user (e.g. "my-password"). |
| queryParams | map[string]string | false | Raw query to be added to the db connection string. |
| queryExecMode | string | false | pgx query execution mode. Valid values: `cache_statement` (default), `cache_describe`, `describe_exec`, `exec`, `simple_protocol`. Useful with connection poolers that don't support prepared statement caching. |
| sqlCommenter | boolean | false | Overrides the global `--sql-commenter` flag for this source. When set, it takes priority; when omitted, the global flag applies. |
docs/en/integrations/postgres/tools/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: "Tools"
weight: 2
---
docs/en/integrations/postgres/tools/postgres-database-overview.md
+52
View File
@@ -0,0 +1,52 @@
---
title: "postgres-database-overview"
type: docs
weight: 1
description: >
The "postgres-database-overview" fetches the current state of the PostgreSQL server.
---
## About
The `postgres-database-overview` fetches the current state of the PostgreSQL
server.
`postgres-database-overview` fetches the current state of the PostgreSQL server
This tool does not take any input parameters.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: database_overview
type: postgres-database-overview
source: cloudsql-pg-source
description: |
fetches the current state of the PostgreSQL server. It returns the postgres version, whether it's a replica, uptime duration, maximum connection limit, number of current connections, number of active connections and the percentage of connections in use.
```
The response is a JSON object with the following elements:
```json
{
"pg_version": "PostgreSQL server version string",
"is_replica": "boolean indicating if the instance is in recovery mode",
"uptime": "interval string representing the total server uptime",
"max_connections": "integer maximum number of allowed connections",
"current_connections": "integer number of current connections",
"active_connections": "integer number of currently active connections",
"pct_connections_used": "float percentage of max_connections currently in use"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-database-overview". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-execute-sql.md
+41
View File
@@ -0,0 +1,41 @@
---
title: "postgres-execute-sql"
type: docs
weight: 1
description: >
A "postgres-execute-sql" tool executes a SQL statement against a Postgres
database.
---
## About
A `postgres-execute-sql` tool executes a SQL statement against a Postgres
database.
`postgres-execute-sql` takes one input parameter `sql` and run the sql
statement against the `source`.
> **Note:** This tool is intended for developer assistant workflows with
> human-in-the-loop and shouldn't be used for production agents.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: execute_sql_tool
type: postgres-execute-sql
source: my-pg-instance
description: Use this tool to execute sql statement.
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| type | string | true | Must be "postgres-execute-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
docs/en/integrations/postgres/tools/postgres-get-column-cardinality.md
+61
View File
@@ -0,0 +1,61 @@
---
title: "postgres-get-column-cardinality"
type: docs
weight: 1
description: >
The "postgres-get-column-cardinality" tool estimates the number of unique values in one or all columns of a Postgres database table.
---
## About
The `postgres-get-column-cardinality` tool estimates the number of unique values
(cardinality) for one or all columns in a specific PostgreSQL table by using the
database's internal statistics.
`postgres-get-column-cardinality` returns detailed information as JSON about column
cardinality values, ordered by estimated cardinality in descending order. The tool takes
the following input parameters:
- `schema_name` (required): The schema name in which the table is present.
- `table_name` (required): The table name in which the column is present.
- `column_name` (optional): The column name for which the cardinality is to be found.
If not provided, cardinality for all columns will be returned. Default: `""`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: get_column_cardinality
type: postgres-get-column-cardinality
source: postgres-source
description: Estimates the number of unique values (cardinality) quickly for one or all columns in a specific PostgreSQL table by using the database's internal statistics, returning the results in descending order of estimated cardinality. Please run ANALYZE on the table before using this tool to get accurate results. The tool returns the column_name and the estimated_cardinality. If the column_name is not provided, the tool returns all columns along with their estimated cardinality.
```
The response is a json array with the following elements:
```json
[
{
"column_name": "name of the column",
"estimated_cardinality": "estimated number of unique values in the column"
}
]
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-get-column-cardinality". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
## Advanced Usage
For accurate results, it's recommended to run `ANALYZE` on the table before using this
tool. The `ANALYZE` command updates the database statistics that this tool relies on
to estimate cardinality.
docs/en/integrations/postgres/tools/postgres-list-active-queries.md
+66
View File
@@ -0,0 +1,66 @@
---
title: "postgres-list-active-queries"
type: docs
weight: 1
description: >
The "postgres-list-active-queries" tool lists currently active queries in a Postgres database.
---
## About
The `postgres-list-active-queries` tool retrieves information about currently
active queries in a Postgres database.
`postgres-list-active-queries` lists detailed information as JSON for currently
active queries. The tool takes the following input parameters:
- `min_duraton` (optional): Only show queries running at least this long (e.g.,
'1 minute', '1 second', '2 seconds'). Default: '1 minute'.
- `exclude_application_names` (optional): A comma-separated list of application
names to exclude from the query results. This is useful for filtering out
queries from specific applications (e.g., 'psql', 'pgAdmin', 'DBeaver'). The
match is case-sensitive. Whitespace around commas and names is automatically
handled. If this parameter is omitted, no applications are excluded.
- `limit` (optional): The maximum number of rows to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_active_queries
type: postgres-list-active-queries
source: postgres-source
description: List the top N (default 50) currently running queries (state='active') from pg_stat_activity, ordered by longest-running first. Returns pid, user, database, application_name, client_addr, state, wait_event_type/wait_event, backend/xact/query start times, computed query_duration, and the SQL text.
```
The response is a json array with the following elements:
```json
{
"pid": "process id",
"user": "database user name",
"datname": "database name",
"application_name": "connecting application name",
"client_addr": "connecting client ip address",
"state": "connection state",
"wait_event_type": "connection wait event type",
"wait_event": "connection wait event",
"backend_start": "connection start time",
"xact_start": "transaction start time",
"query_start": "query start time",
"query_duration": "query duration",
"query": "query text"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|----------------------------------------------------|
| type | string | true | Must be "postgres-list-active-queries". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
docs/en/integrations/postgres/tools/postgres-list-available-extensions.md
+41
View File
@@ -0,0 +1,41 @@
---
title: "postgres-list-available-extensions"
type: docs
weight: 1
description: >
The "postgres-list-available-extensions" tool retrieves all PostgreSQL
extensions available for installation on a Postgres database.
---
## About
The `postgres-list-available-extensions` tool retrieves all PostgreSQL
extensions available for installation on a Postgres database.
`postgres-list-available-extensions` lists all PostgreSQL extensions available
for installation (extension name, default version description) as JSON. The does
not support any input parameter.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_available_extensions
type: postgres-list-available-extensions
source: postgres-source
description: Discover all PostgreSQL extensions available for installation on this server, returning name, default_version, and description.
```
## Reference
| **name** | **default_version** | **description** |
|----------------------|---------------------|---------------------------------------------------------------------------------------------------------------------|
| address_standardizer | 3.5.2 | Used to parse an address into constituent elements. Generally used to support geocoding address normalization step. |
| amcheck | 1.4 | functions for verifying relation integrity |
| anon | 1.0.0 | Data anonymization tools |
| autoinc | 1.0 | functions for autoincrementing fields |
docs/en/integrations/postgres/tools/postgres-list-database-stats.md
+92
View File
@@ -0,0 +1,92 @@
---
title: "postgres-list-database-stats"
type: docs
weight: 1
description: >
The "postgres-list-database-stats" tool lists lists key performance and activity statistics of PostgreSQL databases.
---
## About
The `postgres-list-database-stats` lists the key performance and activity statistics for each PostgreSQL database in the instance, offering insights into cache efficiency, transaction throughput, row-level activity, temporary file usage, and contention.
`postgres-list-database-stats` lists detailed information as JSON for each database. The tool
takes the following input parameters:
- `database_name` (optional): A text to filter results by database name. Default: `""`
- `include_templates` (optional): Boolean, set to `true` to include template databases in the results. Default: `false`
- `database_owner` (optional): A text to filter results by database owner. Default: `""`
- `default_tablespace` (optional): A text to filter results by the default tablespace name. Default: `""`
- `order_by` (optional): Specifies the sorting order. Valid values are `'size'` (descending) or `'commit'` (descending). Default: `database_name` ascending.
- `limit` (optional): The maximum number of databases to return. Default: `10`
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_database_stats
type: postgres-list-database-stats
source: postgres-source
description: |
Lists the key performance and activity statistics for each PostgreSQL
database in the instance, offering insights into cache efficiency,
transaction throughput row-level activity, temporary file usage, and
contention. It returns: the database name, whether the database is
connectable, database owner, default tablespace name, the percentage of
data blocks found in the buffer cache rather than being read from disk
(a higher value indicates better cache performance), the total number of
disk blocks read from disk, the total number of times disk blocks were
found already in the cache; the total number of committed transactions,
the total number of rolled back transactions, the percentage of rolled
back transactions compared to the total number of completed
transactions, the total number of rows returned by queries, the total
number of live rows fetched by scans, the total number of rows inserted,
the total number of rows updated, the total number of rows deleted, the
number of temporary files created by queries, the total size of
temporary files used by queries in bytes, the number of query
cancellations due to conflicts with recovery, the number of deadlocks
detected, the current number of active backend connections, the
timestamp when the database statistics were last reset, and the total
database size in bytes.
```
The response is a json array with the following elements:
```json
{
"database_name": "Name of the database",
"is_connectable": "Boolean indicating Whether the database allows connections",
"database_owner": "Username of the database owner",
"default_tablespace": "Name of the default tablespace for the database",
"cache_hit_ratio_percent": "The percentage of data blocks found in the buffer cache rather than being read from disk",
"blocks_read_from_disk": "The total number of disk blocks read for this database",
"blocks_hit_in_cache": "The total number of times disk blocks were found already in the cache.",
"xact_commit": "The total number of committed transactions",
"xact_rollback": "The total number of rolled back transactions",
"rollback_ratio_percent": "The percentage of rolled back transactions compared to the total number of completed transactions",
"rows_returned_by_queries": "The total number of rows returned by queries",
"rows_fetched_by_scans": "The total number of live rows fetched by scans",
"tup_inserted": "The total number of rows inserted",
"tup_updated": "The total number of rows updated",
"tup_deleted": "The total number of rows deleted",
"temp_files": "The number of temporary files created by queries",
"temp_size_bytes": "The total size of temporary files used by queries in bytes",
"conflicts": "Number of query cancellations due to conflicts",
"deadlocks": "Number of deadlocks detected",
"active_connections": "The current number of active backend connections",
"statistics_last_reset": "The timestamp when the database statistics were last reset",
"database_size_bytes": "The total disk size of the database in bytes"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-database-stats". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-indexes.md
+69
View File
@@ -0,0 +1,69 @@
---
title: "postgres-list-indexes"
type: docs
weight: 1
description: >
The "postgres-list-indexes" tool lists indexes in a Postgres database.
---
## About
The `postgres-list-indexes` tool lists available user indexes in the database
excluding those in `pg_catalog` and `information_schema`.
`postgres-list-indexes` lists detailed information as JSON for indexes. The tool
takes the following input parameters:
- `table_name` (optional): A text to filter results by table name. Default: `""`
- `index_name` (optional): A text to filter results by index name. Default: `""`
- `schema_name` (optional): A text to filter results by schema name. Default: `""`
- `only_unused` (optional): If true, returns indexes that have never been used.
- `limit` (optional): The maximum number of rows to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_indexes
type: postgres-list-indexes
source: postgres-source
description: |
Lists available user indexes in the database, excluding system schemas (pg_catalog,
information_schema). For each index, the following properties are returned:
schema name, table name, index name, index type (access method), a boolean
indicating if it's a unique index, a boolean indicating if it's for a primary key,
the index definition, index size in bytes, the number of index scans, the number of
index tuples read, the number of table tuples fetched via index scans, and a boolean
indicating if the index has been used at least once.
```
The response is a json array with the following elements:
```json
{
"schema_name": "schema name",
"table_name": "table name",
"index_name": "index name",
"index_type": "index access method (e.g btree, hash, gin)",
"is_unique": "boolean indicating if the index is unique",
"is_primary": "boolean indicating if the index is for a primary key",
"index_definition": "index definition statement",
"index_size_bytes": "index size in bytes",
"index_scans": "Number of index scans initiated on this index",
"tuples_read": "Number of index entries returned by scans on this index",
"tuples_fetched": "Number of live table rows fetched by simple index scans using this index",
"is_used": "boolean indicating if the index has been scanned at least once"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-indexes". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-installed-extensions.md
+39
View File
@@ -0,0 +1,39 @@
---
title: "postgres-list-installed-extensions"
type: docs
weight: 1
description: >
The "postgres-list-installed-extensions" tool retrieves all PostgreSQL
extensions installed on a Postgres database.
---
## About
The `postgres-list-installed-extensions` tool retrieves all PostgreSQL
extensions installed on a Postgres database.
`postgres-list-installed-extensions` lists all installed PostgreSQL extensions
(extension name, version, schema, owner, description) as JSON. The does not
support any input parameter.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_installed_extensions
type: postgres-list-installed-extensions
source: postgres-source
description: List all installed PostgreSQL extensions with their name, version, schema, owner, and description.
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|----------------------------------------------------|
| type | string | true | Must be "postgres-list-active-queries". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
docs/en/integrations/postgres/tools/postgres-list-locks.md
+76
View File
@@ -0,0 +1,76 @@
---
title: "postgres-list-locks"
type: docs
weight: 1
description: >
The "postgres-list-locks" tool lists active locks in the database, including the associated process, lock type, relation, mode, and the query holding or waiting on the lock.
---
## About
The `postgres-list-locks` tool displays information about active locks by joining pg_stat_activity with pg_locks. This is useful to find transactions holding or waiting for locks and to troubleshoot contention.
This tool identifies all locks held by active processes showing the process ID, user, query text, and an aggregated list of all transactions and specific locks (relation, mode, grant status) associated with each process.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_locks
type: postgres-list-locks
source: postgres-source
description: "Lists active locks with associated process and query information."
```
### Query
The tool aggregates locks per backend (process) and returns the concatenated transaction ids and lock entries. The SQL used by the tool looks like:
```sql
SELECT
locked.pid,
locked.usename,
locked.query,
string_agg(locked.transactionid::text,':') as trxid,
string_agg(locked.lockinfo,'||') as locks
FROM
(SELECT
a.pid,
a.usename,
a.query,
l.transactionid,
(l.granted::text||','||coalesce(l.relation::regclass,0)::text||','||l.mode::text)::text as lockinfo
FROM
pg_stat_activity a
JOIN pg_locks l ON l.pid = a.pid AND a.pid != pg_backend_pid()) as locked
GROUP BY
locked.pid, locked.usename, locked.query;
```
## Output Format
Example response element (aggregated per process):
```json
{
"pid": 23456,
"usename": "dbuser",
"query": "INSERT INTO orders (...) VALUES (...);",
"trxid": "12345:0",
"locks": "true,public.orders,RowExclusiveLock||false,0,ShareUpdateExclusiveLock"
}
```
## Reference
| field | type | required | description |
|:--------|:--------|:--------:|:------------|
| pid | integer | true | Process id (backend pid). |
| usename | string | true | Database user. |
| query | string | true | SQL text associated with the session. |
| trxid | string | true | Aggregated transaction ids for the process, joined by ':' (string). Each element is the transactionid as text. |
| locks | string | true | Aggregated lock info entries for the process, joined by '||'. Each entry is a comma-separated triple: `granted,relation,mode` where `relation` may be `0` when not resolvable via regclass. |
docs/en/integrations/postgres/tools/postgres-list-pg-settings.md
+57
View File
@@ -0,0 +1,57 @@
---
title: "postgres-list-pg-settings"
type: docs
weight: 1
description: >
The "postgres-list-pg-settings" tool lists PostgreSQL run-time configuration settings.
---
## About
The `postgres-list-pg-settings` tool lists the configuration parameters for the postgres server, their current values, and related information.
`postgres-list-pg-settings` lists detailed information as JSON for each setting. The tool
takes the following input parameters:
- `setting_name` (optional): A text to filter results by setting name. Default: `""`
- `limit` (optional): The maximum number of rows to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_indexes
type: postgres-list-pg-settings
source: postgres-source
description: |
Lists configuration parameters for the postgres server ordered lexicographically,
with a default limit of 50 rows. It returns the parameter name, its current setting,
unit of measurement, a short description, the source of the current setting (e.g.,
default, configuration file, session), and whether a restart is required when the
parameter value is changed."
```
The response is a json array with the following elements:
```json
{
"name": "Setting name",
"current_value": "Current value of the setting",
"unit": "Unit of the setting",
"short_desc": "Short description of the setting",
"source": "Source of the current value (e.g., default, configuration file, session)",
"requires_restart": "Indicates if a server restart is required to apply a change ('Yes', 'No', or 'No (Reload sufficient)')"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-pg-settings". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-publication-tables.md
+64
View File
@@ -0,0 +1,64 @@
---
title: "postgres-list-publication-tables"
type: docs
weight: 1
description: >
The "postgres-list-publication-tables" tool lists publication tables in a Postgres database.
---
## About
The `postgres-list-publication-tables` tool lists all publication tables in the database.
`postgres-list-publication-tables` lists detailed information as JSON for publication tables. A publication table in PostgreSQL is a
table that is explicitly included as a source for replication within a publication (a set of changes generated from a table or group
of tables) as part of the logical replication feature. The tool takes the following input parameters:
- `table_names` (optional): Filters by a comma-separated list of table names. Default: `""`
- `publication_names` (optional): Filters by a comma-separated list of publication names. Default: `""`
- `schema_names` (optional): Filters by a comma-separated list of schema names. Default: `""`
- `limit` (optional): The maximum number of rows to return. Default: `50`
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_indexes
type: postgres-list-publication-tables
source: postgres-source
description: |
Lists all tables that are explicitly part of a publication in the database.
Tables that are part of a publication via 'FOR ALL TABLES' are not included,
unless they are also explicitly added to the publication.
Returns the publication name, schema name, and table name, along with
definition details indicating if it publishes all tables, whether it
replicates inserts, updates, deletes, or truncates, and the publication
owner.
```
The response is a JSON array with the following elements:
```json
{
"publication_name": "Name of the publication",
"schema_name": "Name of the schema the table belongs to",
"table_name": "Name of the table",
"publishes_all_tables": "boolean indicating if the publication was created with FOR ALL TABLES",
"publishes_inserts": "boolean indicating if INSERT operations are replicated",
"publishes_updates": "boolean indicating if UPDATE operations are replicated",
"publishes_deletes": "boolean indicating if DELETE operations are replicated",
"publishes_truncates": "boolean indicating if TRUNCATE operations are replicated",
"publication_owner": "Username of the database role that owns the publication"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-publication-tables". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-query-stats.md
+68
View File
@@ -0,0 +1,68 @@
---
title: "postgres-list-query-stats"
type: docs
weight: 1
description: >
The "postgres-list-query-stats" tool lists query statistics from a Postgres database.
---
## About
The `postgres-list-query-stats` tool retrieves query statistics from the
`pg_stat_statements` extension in a PostgreSQL database. It provides detailed
performance metrics for executed queries.
`postgres-list-query-stats` lists detailed query statistics as JSON, ordered by
total execution time in descending order. The tool takes the following input parameters:
- `database_name` (optional): The database name to filter query stats for. The input is
used within a LIKE clause. Default: `""` (all databases).
- `limit` (optional): The maximum number of results to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Requirements
This tool requires the `pg_stat_statements` extension to be installed and enabled
on the PostgreSQL database. The `pg_stat_statements` extension tracks execution
statistics for all SQL statements executed by the server, which is useful for
identifying slow queries and understanding query performance patterns.
## Example
```yaml
kind: tool
name: list_query_stats
type: postgres-list-query-stats
source: postgres-source
description: List query statistics from pg_stat_statements, showing performance metrics for queries including execution counts, timing information, and resource usage. Results are ordered by total execution time descending.
```
The response is a json array with the following elements:
```json
[
{
"datname": "database name",
"query": "the SQL query text",
"calls": "number of times the query was executed",
"total_exec_time": "total execution time in milliseconds",
"min_exec_time": "minimum execution time in milliseconds",
"max_exec_time": "maximum execution time in milliseconds",
"mean_exec_time": "mean execution time in milliseconds",
"rows": "total number of rows retrieved or affected",
"shared_blks_hit": "number of shared block cache hits",
"shared_blks_read": "number of shared block disk reads"
}
]
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-query-stats". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
docs/en/integrations/postgres/tools/postgres-list-roles.md
+67
View File
@@ -0,0 +1,67 @@
---
title: "postgres-list-roles"
type: docs
weight: 1
description: >
The "postgres-list-roles" tool lists user-created roles in a Postgres database.
---
## About
The `postgres-list-roles` tool lists all the user-created roles in the instance, excluding system roles (like `cloudsql%` or `pg_%`). It provides details about each role's attributes and memberships.
`postgres-list-roles` lists detailed information as JSON for each role. The tool
takes the following input parameters:
- `role_name` (optional): A text to filter results by role name. Default: `""`
- `limit` (optional): The maximum number of roles to return. Default: `50`
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_indexes
type: postgres-list-roles
source: postgres-source
description: |
Lists all the user-created roles in the instance . It returns the role name,
Object ID, the maximum number of concurrent connections the role can make,
along with boolean indicators for: superuser status, privilege inheritance
from member roles, ability to create roles, ability to create databases,
ability to log in, replication privilege, and the ability to bypass
row-level security, the password expiration timestamp, a list of direct
members belonging to this role, and a list of other roles/groups that this
role is a member of.
```
The response is a json array with the following elements:
```json
{
"role_name": "Name of the role",
"oid": "Object ID of the role",
"connection_limit": "Maximum concurrent connections allowed (-1 for no limit)",
"is_superuser": "Boolean, true if the role is a superuser",
"inherits_privileges": "Boolean, true if the role inherits privileges of roles it is a member of",
"can_create_roles": "Boolean, true if the role can create other roles",
"can_create_db": "Boolean, true if the role can create databases",
"can_login": "Boolean, true if the role can log in",
"is_replication_role": "Boolean, true if this is a replication role",
"bypass_rls": "Boolean, true if the role bypasses row-level security policies",
"valid_until": "Timestamp until the password is valid (null if forever)",
"direct_members": ["Array of role names that are direct members of this role"],
"member_of": ["Array of role names that this role is a member of"]
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-roles". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-schemas.md
+54
View File
@@ -0,0 +1,54 @@
---
title: "postgres-list-schemas"
type: docs
weight: 1
description: >
The "postgres-list-schemas" tool lists user-defined schemas in a database.
---
## About
The `postgres-list-schemas` tool retrieves information about schemas in a
database excluding system and temporary schemas.
`postgres-list-schemas` lists detailed information as JSON for each schema. The
tool takes the following input parameters:
- `schema_name` (optional): A text to filter results by schema name. Default: `""`
- `owner` (optional): A text to filter results by owner name. Default: `""`
- `limit` (optional): The maximum number of rows to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_schemas
type: postgres-list-schemas
source: postgres-source
description: "Lists all schemas in the database ordered by schema name and excluding system and temporary schemas. It returns the schema name, schema owner, grants, number of functions, number of tables and number of views within each schema."
```
The response is a json array with the following elements:
```json
{
"schema_name": "name of the schema.",
"owner": "role that owns the schema",
"grants": "A JSON object detailing the privileges (e.g., USAGE, CREATE) granted to different roles or PUBLIC on the schema.",
"tables": "The total count of tables within the schema",
"views": "The total count of views within the schema",
"functions": "The total count of functions",
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|----------------------------------------------------|
| type | string | true | Must be "postgres-list-schemas". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the LLM. |
docs/en/integrations/postgres/tools/postgres-list-sequences.md
+64
View File
@@ -0,0 +1,64 @@
---
title: "postgres-list-sequences"
type: docs
weight: 1
description: >
The "postgres-list-sequences" tool lists sequences in a Postgres database.
---
## About
The `postgres-list-sequences` tool retrieves information about sequences in a
Postgres database.
`postgres-list-sequences` lists detailed information as JSON for all sequences.
The tool takes the following input parameters:
- `sequence_name` (optional): A text to filter results by sequence name. The
input is used within a LIKE clause. Default: `""`
- `schema_name` (optional): A text to filter results by schema name. The input is
used within a LIKE clause. Default: `""`
- `limit` (optional): The maximum number of rows to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_indexes
type: postgres-list-sequences
source: postgres-source
description: |
Lists all the sequences in the database ordered by sequence name.
Returns sequence name, schema name, sequence owner, data type of the
sequence, starting value, minimum value, maximum value of the sequence,
the value by which the sequence is incremented, and the last value
generated by generated by the sequence in the current session.
```
The response is a json array with the following elements:
```json
{
"sequence_name": "sequence name",
"schema_name": "schema name",
"sequence_owner": "owner of the sequence",
"data_type": "data type of the sequence",
"start_value": "starting value of the sequence",
"min_value": "minimum value of the sequence",
"max_value": "maximum value of the sequence",
"increment_by": "increment value of the sequence",
"last_value": "last value of the sequence"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-sequences". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-stored-procedure.md
+140
View File
@@ -0,0 +1,140 @@
---
title: "postgres-list-stored-procedure"
type: docs
weight: 1
description: >
The "postgres-list-stored-procedure" tool retrieves metadata for stored procedures in PostgreSQL, including procedure definitions, owners, languages, and descriptions.
---
## About
The `postgres-list-stored-procedure` tool queries PostgreSQL system catalogs (`pg_proc`, `pg_namespace`, `pg_roles`, and `pg_language`) to retrieve comprehensive metadata about stored procedures in the database. It filters for procedures (kind = 'p') and provides the full procedure definition along with ownership and language information.
The tool returns a JSON array where each element represents a stored procedure with its schema, name, owner, language, complete definition, and optional description. Results are sorted by schema name and procedure name, with a default limit of 20 procedures.
### Use Cases
- **Code review and auditing**: Export procedure definitions for version control or compliance audits.
- **Documentation generation**: Automatically extract procedure metadata and descriptions for documentation.
- **Permission auditing**: Identify procedures owned by specific users or in specific schemas.
- **Migration planning**: Retrieve all procedure definitions when planning database migrations.
- **Dependency analysis**: Review procedure definitions to understand dependencies and call chains.
- **Security assessment**: Audit which roles own and can modify stored procedures.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Parameters
| parameter | type | required | default | description |
|--------------|---------|----------|---------|-------------|
| role_name | string | false | null | Optional: The owner name to filter stored procedures by (supports partial matching) |
| schema_name | string | false | null | Optional: The schema name to filter stored procedures by (supports partial matching) |
| limit | integer | false | 20 | Optional: The maximum number of stored procedures to return |
## Example
```yaml
kind: tool
name: list_stored_procedure
type: postgres-list-stored-procedure
source: postgres-source
description: "Retrieves stored procedure metadata including definitions and owners."
```
### Example Requests
**List all stored procedures (default limit 20):**
```json
{}
```
**Filter by specific owner (role):**
```json
{
"role_name": "app_user"
}
```
**Filter by schema:**
```json
{
"schema_name": "public"
}
```
**Filter by owner and schema with custom limit:**
```json
{
"role_name": "postgres",
"schema_name": "public",
"limit": 50
}
```
**Filter by partial schema name:**
```json
{
"schema_name": "audit"
}
```
### Example Response
```json
[
{
"schema_name": "public",
"name": "process_payment",
"owner": "postgres",
"language": "plpgsql",
"definition": "CREATE OR REPLACE PROCEDURE public.process_payment(p_order_id integer, p_amount numeric)\n LANGUAGE plpgsql\nAS $procedure$\nBEGIN\n UPDATE orders SET status = 'paid', amount = p_amount WHERE id = p_order_id;\n INSERT INTO payment_log (order_id, amount, timestamp) VALUES (p_order_id, p_amount, now());\n COMMIT;\nEND\n$procedure$",
"description": "Processes payment for an order and logs the transaction"
},
{
"schema_name": "public",
"name": "cleanup_old_records",
"owner": "postgres",
"language": "plpgsql",
"definition": "CREATE OR REPLACE PROCEDURE public.cleanup_old_records(p_days_old integer)\n LANGUAGE plpgsql\nAS $procedure$\nDECLARE\n v_deleted integer;\nBEGIN\n DELETE FROM audit_logs WHERE created_at < now() - (p_days_old || ' days')::interval;\n GET DIAGNOSTICS v_deleted = ROW_COUNT;\n RAISE NOTICE 'Deleted % records', v_deleted;\nEND\n$procedure$",
"description": "Removes audit log records older than specified days"
},
{
"schema_name": "audit",
"name": "audit_table_changes",
"owner": "app_user",
"language": "plpgsql",
"definition": "CREATE OR REPLACE PROCEDURE audit.audit_table_changes()\n LANGUAGE plpgsql\nAS $procedure$\nBEGIN\n INSERT INTO audit.change_log (table_name, operation, changed_at) VALUES (TG_TABLE_NAME, TG_OP, now());\nEND\n$procedure$",
"description": null
}
]
```
## Output Format
| field | type | description |
|-------------|---------|-------------|
| schema_name | string | Name of the schema containing the stored procedure. |
| name | string | Name of the stored procedure. |
| owner | string | PostgreSQL role/user who owns the stored procedure. |
| language | string | Programming language in which the procedure is written (e.g., plpgsql, sql, c). |
| definition | string | Complete SQL definition of the stored procedure, including the CREATE PROCEDURE statement. |
| description | string | Optional description or comment for the procedure (may be null if no comment is set). |
## Advanced Usage
### Performance Considerations
- The tool filters at the database level using LIKE pattern matching, so partial matches are supported.
- Procedure definitions can be large; consider using the `limit` parameter for large databases with many procedures.
- Results are ordered by schema name and procedure name for consistent output.
- The default limit of 20 procedures is suitable for most use cases; increase as needed.
### Notes
- Only stored **procedures** are returned; functions and other callable objects are excluded via the `prokind = 'p'` filter.
- Filtering uses `LIKE` pattern matching, so filter values support partial matches (e.g., `role_name: "app"` will match "app_user", "app_admin", etc.).
- The `definition` field contains the complete, runnable CREATE PROCEDURE statement.
- The `description` field is populated from comments set via PostgreSQL's COMMENT command and may be null.
docs/en/integrations/postgres/tools/postgres-list-table-stats.md
+170
View File
@@ -0,0 +1,170 @@
---
title: "postgres-list-table-stats"
type: docs
weight: 1
description: >
The "postgres-list-table-stats" tool reports table statistics including size, scan metrics, and bloat indicators for PostgreSQL tables.
---
## About
The `postgres-list-table-stats` tool queries `pg_stat_all_tables` to provide comprehensive statistics about tables in the database. It calculates useful metrics like index scan ratio and dead row ratio to help identify performance issues and table bloat.
The tool returns a JSON array where each element represents statistics for a table, including scan metrics, row counts, and vacuum history. Results are sorted by sequential scans by default and limited to 50 rows.
### Use Cases
- **Finding ineffective indexes**: Identify tables with low `idx_scan_ratio_percent` to evaluate index strategy.
- **Detecting table bloat**: Sort by `dead_rows` to find tables needing VACUUM.
- **Monitoring growth**: Track `total_size_bytes` over time for capacity planning.
- **Audit maintenance**: Check `last_autovacuum` and `last_autoanalyze` timestamps to ensure maintenance tasks are running.
- **Understanding workload**: Examine `seq_scan` vs `idx_scan` ratios to understand query patterns.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Parameters
| parameter | type | required | default | description |
|-------------|---------|----------|---------|-------------|
| schema_name | string | false | "public" | Optional: A specific schema name to filter by (supports partial matching) |
| table_name | string | false | null | Optional: A specific table name to filter by (supports partial matching) |
| owner | string | false | null | Optional: A specific owner to filter by (supports partial matching) |
| sort_by | string | false | null | Optional: The column to sort by. Valid values: `size`, `dead_rows`, `seq_scan`, `idx_scan` (defaults to `seq_scan`) |
| limit | integer | false | 50 | Optional: The maximum number of results to return |
## Example
```yaml
kind: tool
name: list_table_stats
type: postgres-list-table-stats
source: postgres-source
description: "Lists table statistics including size, scans, and bloat metrics."
```
### Example Requests
**List default tables in public schema:**
```json
{}
```
**Filter by specific table name:**
```json
{
"table_name": "users"
}
```
**Filter by owner and sort by size:**
```json
{
"owner": "app_user",
"sort_by": "size",
"limit": 10
}
```
**Find tables with high dead row ratio:**
```json
{
"sort_by": "dead_rows",
"limit": 20
}
```
### Example Response
```json
[
{
"schema_name": "public",
"table_name": "users",
"owner": "postgres",
"total_size_bytes": 8388608,
"seq_scan": 150,
"idx_scan": 450,
"idx_scan_ratio_percent": 75.0,
"live_rows": 50000,
"dead_rows": 1200,
"dead_row_ratio_percent": 2.34,
"n_tup_ins": 52000,
"n_tup_upd": 12500,
"n_tup_del": 800,
"last_vacuum": "2025-11-27T10:30:00Z",
"last_autovacuum": "2025-11-27T09:15:00Z",
"last_autoanalyze": "2025-11-27T09:16:00Z"
},
{
"schema_name": "public",
"table_name": "orders",
"owner": "postgres",
"total_size_bytes": 16777216,
"seq_scan": 50,
"idx_scan": 1200,
"idx_scan_ratio_percent": 96.0,
"live_rows": 100000,
"dead_rows": 5000,
"dead_row_ratio_percent": 4.76,
"n_tup_ins": 120000,
"n_tup_upd": 45000,
"n_tup_del": 15000,
"last_vacuum": "2025-11-26T14:22:00Z",
"last_autovacuum": "2025-11-27T02:30:00Z",
"last_autoanalyze": "2025-11-27T02:31:00Z"
}
]
```
## Output Format
| field | type | description |
|------------------------|-----------|-------------|
| schema_name | string | Name of the schema containing the table. |
| table_name | string | Name of the table. |
| owner | string | PostgreSQL user who owns the table. |
| total_size_bytes | integer | Total size of the table including all indexes in bytes. |
| seq_scan | integer | Number of sequential (full table) scans performed on this table. |
| idx_scan | integer | Number of index scans performed on this table. |
| idx_scan_ratio_percent | decimal | Percentage of total scans (seq_scan + idx_scan) that used an index. A low ratio may indicate missing or ineffective indexes. |
| live_rows | integer | Number of live (non-deleted) rows in the table. |
| dead_rows | integer | Number of dead (deleted but not yet vacuumed) rows in the table. |
| dead_row_ratio_percent | decimal | Percentage of dead rows relative to total rows. High values indicate potential table bloat. |
| n_tup_ins | integer | Total number of rows inserted into this table. |
| n_tup_upd | integer | Total number of rows updated in this table. |
| n_tup_del | integer | Total number of rows deleted from this table. |
| last_vacuum | timestamp | Timestamp of the last manual VACUUM operation on this table (null if never manually vacuumed). |
| last_autovacuum | timestamp | Timestamp of the last automatic vacuum operation on this table. |
| last_autoanalyze | timestamp | Timestamp of the last automatic analyze operation on this table. |
## Advanced Usage
### Interpretation Guide
#### Index Scan Ratio (`idx_scan_ratio_percent`)
- **High ratio (> 80%)**: Table queries are efficiently using indexes. This is typically desirable.
- **Low ratio (< 20%)**: Many sequential scans indicate missing indexes or queries that cannot use existing indexes effectively. Consider adding indexes to frequently searched columns.
- **0%**: No index scans performed; all queries performed sequential scans. May warrant index investigation.
#### Dead Row Ratio (`dead_row_ratio_percent`)
- **< 2%**: Healthy table with minimal bloat.
- **2-5%**: Moderate bloat; consider running VACUUM if not recent.
- **> 5%**: High bloat; may benefit from manual VACUUM or VACUUM FULL.
#### Vacuum History
- **Null `last_vacuum`**: Table has never been manually vacuumed; relies on autovacuum.
- **Recent `last_autovacuum`**: Autovacuum is actively managing the table.
- **Stale timestamps**: Consider running manual VACUUM and ANALYZE if maintenance windows exist.
### Performance Considerations
- Statistics are collected from `pg_stat_all_tables`, which resets on PostgreSQL restart.
- Run `ANALYZE` on tables to update statistics for accurate query planning.
- The tool defaults to limiting results to 50 rows; adjust the `limit` parameter for larger result sets.
- Filtering by schema, table name, or owner uses `LIKE` pattern matching (supports partial matches).
docs/en/integrations/postgres/tools/postgres-list-tables.md
+45
View File
@@ -0,0 +1,45 @@
---
title: "postgres-list-tables"
type: docs
weight: 1
description: >
The "postgres-list-tables" tool lists schema information for all or specified
tables in a Postgres database.
---
## About
The `postgres-list-tables` tool retrieves schema information for all or
specified tables in a Postgres database.
`postgres-list-tables` lists detailed schema information (object type, columns,
constraints, indexes, triggers, owner, comment) as JSON for user-created tables
(ordinary or partitioned). The tool takes the following input parameters: *
`table_names` (optional): Filters by a comma-separated list of names. By
default, it lists all tables in user schemas.* `output_format` (optional):
Indicate the output format of table schema. `simple` will return only the
table names, `detailed` will return the full table information. Default:
`detailed`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: postgres_list_tables
type: postgres-list-tables
source: postgres-source
description: Use this tool to retrieve schema information for all or
specified tables. Output format can be simple (only table names) or detailed.
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-tables". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-tablespaces.md
+54
View File
@@ -0,0 +1,54 @@
---
title: "postgres-list-tablespaces"
type: docs
weight: 1
description: >
The "postgres-list-tablespaces" tool lists tablespaces in a Postgres database.
---
## About
The `postgres-list-tablespaces` tool lists available tablespaces in the database.
`postgres-list-tablespaces` lists detailed information as JSON for tablespaces. The tool takes the following input parameters:
- `tablespace_name` (optional): A text to filter results by tablespace name. Default: `""`
- `limit` (optional): The maximum number of tablespaces to return. Default: `50`
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_tablespaces
type: postgres-list-tablespaces
source: postgres-source
description: |
Lists all tablespaces in the database. Returns the tablespace name,
owner name, size in bytes(if the current user has CREATE privileges on
the tablespace, otherwise NULL), internal object ID, the access control
list regarding permissions, and any specific tablespace options.
```
The response is a json array with the following elements:
```json
{
"tablespace_name": "name of the tablespace",
"owner_username": "owner of the tablespace",
"size_in_bytes": "size in bytes if the current user has CREATE privileges on the tablespace, otherwise NULL",
"oid": "Object ID of the tablespace",
"spcacl": "Access privileges",
"spcoptions": "Tablespace-level options (e.g., seq_page_cost, random_page_cost)"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:-------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-tablespaces". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-triggers.md
+62
View File
@@ -0,0 +1,62 @@
---
title: "postgres-list-triggers"
type: docs
weight: 1
description: >
The "postgres-list-triggers" tool lists triggers in a Postgres database.
---
## About
The `postgres-list-triggers` tool lists available non-internal triggers in the
database.
`postgres-list-triggers` lists detailed information as JSON for triggers. The
tool takes the following input parameters:
- `trigger_name` (optional): A text to filter results by trigger name. The input
is used within a LIKE clause. Default: `""`
- `schema_name` (optional): A text to filter results by schema name. The input
is used within a LIKE clause. Default: `""`
- `table_name` (optional): A text to filter results by table name. The input is
used within a LIKE clause. Default: `""`
- `limit` (optional): The maximum number of triggers to return. Default: `50`
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_triggers
type: postgres-list-triggers
source: postgres-source
description: |
Lists all non-internal triggers in a database. Returns trigger name, schema name, table name, wether its enabled or disabled, timing (e.g BEFORE/AFTER of the event), the events that cause the trigger to fire such as INSERT, UPDATE, or DELETE, whether the trigger activates per ROW or per STATEMENT, the handler function executed by the trigger and full definition.
```
The response is a json array with the following elements:
```json
{
"trigger_name": "trigger name",
"schema_name": "schema name",
"table_name": "table name",
"status": "Whether the trigger is currently active (ENABLED, DISABLED, REPLICA, ALWAYS).",
"timing": "When it runs relative to the event (BEFORE, AFTER, INSTEAD OF).",
"events": "The specific operations that fire it (INSERT, UPDATE, DELETE, TRUNCATE)",
"activation_level": "Granularity of execution (ROW vs STATEMENT).",
"function_name": "The function it executes",
"definition": "Full SQL definition of the trigger"
}
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-triggers". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-list-views.md
+42
View File
@@ -0,0 +1,42 @@
---
title: "postgres-list-views"
type: docs
weight: 1
description: >
The "postgres-list-views" tool lists views in a Postgres database, with a default limit of 50 rows.
---
## About
The `postgres-list-views` tool retrieves a list of top N (default 50) views from
a Postgres database, excluding those in system schemas (`pg_catalog`,
`information_schema`).
`postgres-list-views` lists detailed view information (schemaname, viewname,
ownername, definition) as JSON for views in a database. The tool takes the following input
parameters:
- `view_name` (optional): A string pattern to filter view names. Default: `""`
- `schema_name` (optional): A string pattern to filter schema names. Default: `""`
- `limit` (optional): The maximum number of rows to return. Default: `50`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: list_views
type: postgres-list-views
source: cloudsql-pg-source
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------|
| type | string | true | Must be "postgres-list-views". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | false | Description of the tool that is passed to the agent. |
docs/en/integrations/postgres/tools/postgres-long-running-transactions.md
+104
View File
@@ -0,0 +1,104 @@
---
title: "postgres-long-running-transactions"
type: docs
weight: 1
description: >
The postgres-long-running-transactions tool Identifies and lists database transactions that exceed a specified time limit. For each of the long running transactions, the output contains the process id, database name, user name, application name, client address, state, connection age, transaction age, query age, last activity age, wait event type, wait event, and query string.
---
## About
The `postgres-long-running-transactions` tool reports transactions that exceed a configured duration threshold by scanning `pg_stat_activity` for sessions where `xact_start` is set and older than the configured interval.
The tool returns a JSON array with one object per matching session (non-idle). Each object contains the process id, database and user, application name, client address, session state, several age intervals (connection, transaction, query, and last activity), wait event info, and the SQL text currently associated with the session.
Parameters:
- `min_duration` (optional): Only show transactions running at least this long (Postgres interval format, e.g., '5 minutes'). Default: `5 minutes`.
- `limit` (optional): Maximum number of results to return. Default: `20`.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Parameters
| field | type | required | description |
|:---------------------|:--------|:--------:|:------------|
| pid | integer | true | Process id (backend pid). |
| datname | string | true | Database name. |
| usename | string | true | Database user name. |
| appname | string | false | Application name (client application). |
| client_addr | string | false | Client IPv4/IPv6 address (may be null for local connections). |
| state | string | true | Session state (e.g., active, idle in transaction). |
| conn_age | string | true | Age of the connection: `now() - backend_start` (Postgres interval serialized as string). |
| xact_age | string | true | Age of the transaction: `now() - xact_start` (Postgres interval serialized as string). |
| query_age | string | true | Age of the currently running query: `now() - query_start` (Postgres interval serialized as string). |
| last_activity_age | string | true | Time since last state change: `now() - state_change` (Postgres interval serialized as string). |
| wait_event_type | string | false | Type of event the backend is waiting on (may be null). |
| wait_event | string | false | Specific wait event name (may be null). |
| query | string | true | SQL text associated with the session. |
## Example
```yaml
kind: tool
name: long_running_transactions
type: postgres-long-running-transactions
source: postgres-source
description: "Identifies transactions open longer than a threshold and returns details including query text and durations."
```
Example response element:
```json
{
"pid": 12345,
"datname": "my_database",
"usename": "dbuser",
"appname": "my_app",
"client_addr": "10.0.0.5",
"state": "idle in transaction",
"conn_age": "00:12:34",
"xact_age": "00:06:00",
"query_age": "00:02:00",
"last_activity_age": "00:01:30",
"wait_event_type": null,
"wait_event": null,
"query": "UPDATE users SET last_seen = now() WHERE id = 42;"
}
```
### Query
The SQL used by the tool looks like:
```sql
SELECT
pid,
datname,
usename,
application_name as appname,
client_addr,
state,
now() - backend_start as conn_age,
now() - xact_start as xact_age,
now() - query_start as query_age,
now() - state_change as last_activity_age,
wait_event_type,
wait_event,
query
FROM
pg_stat_activity
WHERE
state <> 'idle'
AND (now() - xact_start) > COALESCE($1::INTERVAL, interval '5 minutes')
AND xact_start IS NOT NULL
AND pid <> pg_backend_pid()
ORDER BY
xact_age DESC
LIMIT
COALESCE($2::int, 20);
```
docs/en/integrations/postgres/tools/postgres-replication-stats.md
+63
View File
@@ -0,0 +1,63 @@
---
title: "postgres-replication-stats"
type: docs
weight: 1
description: >
The "postgres-replication-stats" tool reports replication-related metrics for WAL streaming replicas, including lag sizes presented in human-readable form.
---
## About
The `postgres-replication-stats` tool queries pg_stat_replication to surface the status of connected replicas. It reports application_name, client address, connection and sync state, and human-readable lag sizes (sent, write, flush, replay, and total) computed using WAL LSN differences.
This tool takes no parameters. It returns a JSON array; each element represents a replication connection on the primary and includes lag metrics formatted by pg_size_pretty.
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
```yaml
kind: tool
name: replication_stats
type: postgres-replication-stats
source: postgres-source
description: "Lists replication connections and readable WAL lag metrics."
```
Example response element:
```json
{
"pid": 12345,
"usename": "replication_user",
"application_name": "replica-1",
"backend_xmin": "0/0",
"client_addr": "10.0.0.7",
"state": "streaming",
"sync_state": "sync",
"sent_lag": "1234 kB",
"write_lag": "12 kB",
"flush_lag": "0 bytes",
"replay_lag": "0 bytes",
"total_lag": "1234 kB"
}
```
## Reference
| field | type | required | description |
|------------------:|:-------:|:--------:|:------------|
| pid | integer | true | Process ID of the replication backend on the primary. |
| usename | string | true | Name of the user performing the replication connection. |
| application_name | string | true | Name of the application (replica) connecting to the primary. |
| backend_xmin | string | false | Standby's xmin horizon reported by hot_standby_feedback (may be null). |
| client_addr | string | false | Client IP address of the replica (may be null). |
| state | string | true | Connection state (e.g., streaming). |
| sync_state | string | true | Sync state (e.g., async, sync, potential). |
| sent_lag | string | true | Human-readable size difference between current WAL LSN and sent_lsn. |
| write_lag | string | true | Human-readable write lag between sent_lsn and write_lsn. |
| flush_lag | string | true | Human-readable flush lag between write_lsn and flush_lsn. |
| replay_lag | string | true | Human-readable replay lag between flush_lsn and replay_lsn. |
| total_lag | string | true | Human-readable total lag between current WAL LSN and replay_lsn. |
docs/en/integrations/postgres/tools/postgres-sql.md
+107
View File
@@ -0,0 +1,107 @@
---
title: "postgres-sql"
type: docs
weight: 1
description: >
A "postgres-sql" tool executes a pre-defined SQL statement against a Postgres
database.
---
## About
A `postgres-sql` tool executes a pre-defined SQL statement against a Postgres
database.
The specified SQL statement is executed as a [prepared statement][pg-prepare],
and specified parameters will be inserted according to their position: e.g. `$1`
will be the first parameter specified, `$2` will be the second parameter, and so
on. If template parameters are included, they will be resolved before execution
of the prepared statement.
[pg-prepare]: https://www.postgresql.org/docs/current/sql-prepare.html
## Compatible Sources
{{< compatible-sources others="integrations/alloydb, integrations/cloud-sql-pg">}}
## Example
> **Note:** This tool uses parameterized queries to prevent SQL injections.
> Query parameters can be used as substitutes for arbitrary expressions.
> Parameters cannot be used as substitutes for identifiers, column names, table
> names, or other parts of the query.
```yaml
kind: tool
name: search_flights_by_number
type: postgres-sql
source: my-pg-instance
statement: |
SELECT * FROM flights
WHERE airline = $1
AND flight_number = $2
LIMIT 10
description: |
Use this tool to get information for a specific flight.
Takes an airline code and flight number and returns info on the flight.
Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number.
A airline code is a code for an airline service consisting of two-character
airline designator and followed by flight number, which is 1 to 4 digit number.
For example, if given CY 0123, the airline is "CY", and flight_number is "123".
Another example for this is DL 1234, the airline is "DL", and flight_number is "1234".
If the tool returns more than one option choose the date closes to today.
Example:
{{
"airline": "CY",
"flight_number": "888",
}}
Example:
{{
"airline": "DL",
"flight_number": "1234",
}}
parameters:
- name: airline
type: string
description: Airline unique 2 letter identifier
- name: flight_number
type: string
description: 1 to 4 digit number
```
### Example with Template Parameters
> **Note:** This tool allows direct modifications to the SQL statement,
> including identifiers, column names, and table names. **This makes it more
> vulnerable to SQL injections**. Using basic parameters only (see above) is
> recommended for performance and safety reasons. For more details, please check
> [templateParameters](../../../documentation/configuration/tools/_index.md#template-parameters).
```yaml
kind: tool
name: list_table
type: postgres-sql
source: my-pg-instance
statement: |
SELECT * FROM {{.tableName}}
description: |
Use this tool to list all information from a specific table.
Example:
{{
"tableName": "flights",
}}
templateParameters:
- name: tableName
type: string
description: Table to select from
```
## Reference
| **field** | **type** | **required** | **description** |
|--------------------|:--------------------------------------------:|:------------:|----------------------------------------------------------------------------------------------------------------------------------------|
| type | string | true | Must be "postgres-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute on. |
| parameters | [parameters](../../../documentation/configuration/tools/_index.md#specifying-parameters) | false | List of [parameters](../../../documentation/configuration/tools/_index.md#specifying-parameters) that will be inserted into the SQL statement. |
| templateParameters | [templateParameters](../../../documentation/configuration/tools/_index.md#template-parameters) | false | List of [templateParameters](../../../documentation/configuration/tools/_index.md#template-parameters) that will be inserted into the SQL statement before executing prepared statement. |