genai-toolbox/internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml

# 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.

sources:
    cloudsql-pg-source:
        kind: cloud-sql-postgres
        project: ${CLOUD_SQL_POSTGRES_PROJECT}
        region: ${CLOUD_SQL_POSTGRES_REGION}
        instance: ${CLOUD_SQL_POSTGRES_INSTANCE}
        database: ${CLOUD_SQL_POSTGRES_DATABASE}
        user: ${CLOUD_SQL_POSTGRES_USER:}
        password: ${CLOUD_SQL_POSTGRES_PASSWORD:}
        ipType: ${CLOUD_SQL_POSTGRES_IP_TYPE:public}

tools:
    execute_sql:
        kind: postgres-execute-sql
        source: cloudsql-pg-source
        description: Use this tool to execute sql.

    list_tables:
        kind: postgres-list-tables
        source: cloudsql-pg-source
        description: "Lists detailed schema information (object type, columns, constraints, indexes, triggers, owner, comment) as JSON for user-created tables (ordinary or partitioned). Filters by a comma-separated list of names. If names are omitted, lists all tables in user schemas."

    list_active_queries:
        kind: postgres-list-active-queries
        source: cloudsql-pg-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."

    list_available_extensions:
        kind: postgres-list-available-extensions
        source: cloudsql-pg-source
        description: "Discover all PostgreSQL extensions available for installation on this server, returning name, default_version, and description."

    list_installed_extensions:
        kind: postgres-list-installed-extensions
        source: cloudsql-pg-source
        description: "List all installed PostgreSQL extensions with their name, version, schema, owner, and description."

    list_autovacuum_configurations:
        kind: postgres-sql
        source: cloudsql-pg-source
        description: "List PostgreSQL autovacuum-related configurations (name and current setting) from pg_settings."
        statement: |
            SELECT name,
                setting
            FROM   pg_settings
            WHERE  category = 'Autovacuum';

    list_memory_configurations:
        kind: postgres-sql
        source: cloudsql-pg-source
        description: "List PostgreSQL memory-related configurations (name and current setting) from pg_settings."
        statement: |
            (
                SELECT
                name,
                pg_size_pretty((setting::bigint * 1024)::bigint) setting
                FROM pg_settings
                WHERE name IN ('work_mem', 'maintenance_work_mem')
            )
            UNION ALL
            (
                SELECT
                name,
                pg_size_pretty((((setting::bigint) * 8) * 1024)::bigint)
                FROM pg_settings
                WHERE name IN ('shared_buffers', 'wal_buffers', 'effective_cache_size', 'temp_buffers')
            )
            ORDER BY 1 DESC;

    list_top_bloated_tables:
        kind: postgres-sql
        source: cloudsql-pg-source
        description: |
            List the top tables by dead-tuple (approximate bloat signal), returning schema, table, live/dead tuples, percentage, and last vacuum/analyze times.
        statement: |
            SELECT
                schemaname AS schema_name,
                relname AS relation_name,
                n_live_tup AS live_tuples,
                n_dead_tup AS dead_tuples,
                TRUNC((n_dead_tup::NUMERIC / NULLIF(n_live_tup + n_dead_tup, 0)) * 100, 2) AS dead_tuple_percentage,
                last_vacuum,
                last_autovacuum,
                last_analyze,
                last_autoanalyze
            FROM pg_stat_user_tables
            ORDER BY n_dead_tup DESC
            LIMIT COALESCE($1::int, 50);
        parameters:
            - name: limit
              description: "The maximum number of results to return."
              type: integer
              default: 50

    list_replication_slots:
        kind: postgres-sql
        source: cloudsql-pg-source
        description: "List key details for all PostgreSQL replication slots (e.g., type, database, active status) and calculates the size of the outstanding WAL that is being prevented from removal by the slot."
        statement: |
            SELECT
            slot_name,
            slot_type,
            plugin,
            database,
            temporary,
            active,
            restart_lsn,
            confirmed_flush_lsn,
            xmin,
            catalog_xmin,
            pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
            FROM pg_replication_slots;

    list_invalid_indexes:
        kind: postgres-sql
        source: cloudsql-pg-source
        description: "Lists all invalid PostgreSQL indexes which are taking up disk space but are unusable by the query planner. Typically created by failed CREATE INDEX CONCURRENTLY operations."
        statement: |
            SELECT
                nspname AS schema_name,
                indexrelid::regclass AS index_name,
                indrelid::regclass AS table_name,
                pg_size_pretty(pg_total_relation_size(indexrelid)) AS index_size,
                indisready,
                indisvalid,
                pg_get_indexdef(pg_class.oid) AS index_def
            FROM pg_index
            JOIN pg_class ON pg_class.oid = pg_index.indexrelid
            JOIN pg_namespace ON pg_namespace.oid = pg_class.relnamespace
            WHERE indisvalid = FALSE;

    get_query_plan:
        kind: postgres-sql
        source: cloudsql-pg-source
        description: "Generate a PostgreSQL EXPLAIN plan in JSON format for a single SQL statement—without executing it. This returns the optimizer's estimated plan, costs, and rows (no ANALYZE, no extra options). Use in production safely for plan inspection, regression checks, and query tuning workflows."
        statement: |
            EXPLAIN (FORMAT JSON) {{.query}};
        templateParameters:
            - name: query
              type: string
              description: "The SQL statement for which you want to generate plan (omit the EXPLAIN keyword)."
              required: true

    list_views:
        kind: postgres-list-views
        source: cloudsql-pg-source

    list_schemas:
        kind: postgres-list-schemas
        source: cloudsql-pg-source

toolsets:
    cloud_sql_postgres_database_tools:
        - execute_sql
        - list_tables
        - list_active_queries
        - list_available_extensions
        - list_installed_extensions
        - list_autovacuum_configurations
        - list_memory_configurations
        - list_top_bloated_tables
        - list_replication_slots
        - list_invalid_indexes
        - get_query_plan
        - list_views
        - list_schemas