spanner-list-tables

A “spanner-list-tables” tool retrieves schema information about tables in a Google Cloud Spanner database.

About

A spanner-list-tables tool retrieves comprehensive schema information about tables in a Cloud Spanner database. It automatically adapts to the database dialect (GoogleSQL or PostgreSQL) and returns detailed metadata including columns, constraints, and indexes. It’s compatible with:

This tool is read-only and executes pre-defined SQL queries against the INFORMATION_SCHEMA tables to gather metadata. The tool automatically detects the database dialect from the source configuration and uses the appropriate SQL syntax.

Features

  • Automatic Dialect Detection: Adapts queries based on whether the database uses GoogleSQL or PostgreSQL dialect
  • Comprehensive Schema Information: Returns columns, data types, constraints, indexes, and table relationships
  • Flexible Filtering: Can list all tables or filter by specific table names
  • Output Format Options: Choose between simple (table names only) or detailed (full schema information) output

Example

Basic Usage - List All Tables

sources:
  my-spanner-db:
    kind: spanner
    project: ${SPANNER_PROJECT}
    instance: ${SPANNER_INSTANCE}
    database: ${SPANNER_DATABASE}
    dialect: googlesql  # or postgresql

tools:
  list_all_tables:
    kind: spanner-list-tables
    source: my-spanner-db
    description: Lists all tables with their complete schema information

List Specific Tables

tools:
  list_specific_tables:
    kind: spanner-list-tables
    source: my-spanner-db
    description: |
      Lists schema information for specific tables.
      Example usage:
      {
        "table_names": "users,orders,products",
        "output_format": "detailed"
      }

Parameters

The tool accepts two optional parameters:

parametertypedefaultdescription
table_namesstring""Comma-separated list of table names to filter. If empty, lists all tables in user-accessible schemas
output_formatstring“detailed”Output format: “simple” returns only table names, “detailed” returns full schema information

Output Format

Simple Format

When output_format is set to “simple”, the tool returns a minimal JSON structure:

[
  {
    "schema_name": "public",
    "object_name": "users",
    "object_details": "{\"name\":\"users\"}"
  },
  {
    "schema_name": "public",
    "object_name": "orders",
    "object_details": "{\"name\":\"orders\"}"
  }
]

Detailed Format

When output_format is set to “detailed” (default), the tool returns comprehensive schema information:

[
  {
    "schema_name": "public",
    "object_name": "users",
    "object_details": "{
      \"schema_name\": \"public\",
      \"object_name\": \"users\",
      \"object_type\": \"BASE TABLE\",
      \"columns\": [
        {
          \"column_name\": \"id\",
          \"data_type\": \"INT64\",
          \"ordinal_position\": 1,
          \"is_not_nullable\": true,
          \"column_default\": null
        },
        {
          \"column_name\": \"email\",
          \"data_type\": \"STRING(255)\",
          \"ordinal_position\": 2,
          \"is_not_nullable\": true,
          \"column_default\": null
        }
      ],
      \"constraints\": [
        {
          \"constraint_name\": \"PK_users\",
          \"constraint_type\": \"PRIMARY KEY\",
          \"constraint_definition\": \"PRIMARY KEY (id)\",
          \"constraint_columns\": [\"id\"],
          \"foreign_key_referenced_table\": null,
          \"foreign_key_referenced_columns\": []
        }
      ],
      \"indexes\": [
        {
          \"index_name\": \"idx_users_email\",
          \"index_type\": \"INDEX\",
          \"is_unique\": true,
          \"is_null_filtered\": false,
          \"interleaved_in_table\": null,
          \"index_key_columns\": [
            {\"column_name\": \"email\", \"ordering\": \"ASC\"}
          ],
          \"storing_columns\": []
        }
      ]
    }"
  }
]

Use Cases

  1. Database Documentation: Generate comprehensive documentation of your database schema
  2. Schema Validation: Verify that expected tables and columns exist
  3. Migration Planning: Understand the current schema before making changes
  4. Development Tools: Build tools that need to understand database structure
  5. Audit and Compliance: Track schema changes and ensure compliance with data governance policies

Example with Agent Integration

sources:
  spanner-db:
    kind: spanner
    project: my-project
    instance: my-instance
    database: my-database
    dialect: googlesql

tools:
  schema_inspector:
    kind: spanner-list-tables
    source: spanner-db
    description: |
      Use this tool to inspect database schema information.
      You can:
      - List all tables by leaving table_names empty
      - Get specific table schemas by providing comma-separated table names
      - Choose between simple (names only) or detailed (full schema) output
      
      Examples:
      1. List all tables with details: {"output_format": "detailed"}
      2. Get specific tables: {"table_names": "users,orders", "output_format": "detailed"}
      3. Just get table names: {"output_format": "simple"}

Reference

fieldtyperequireddescription
kindstringtrueMust be “spanner-list-tables”
sourcestringtrueName of the Spanner source to query
descriptionstringfalseDescription of the tool that is passed to the LLM
authRequiredstring[]falseList of auth services required to invoke this tool

Notes

  • This tool is read-only and does not modify any data
  • The tool automatically handles both GoogleSQL and PostgreSQL dialects
  • Large databases with many tables may take longer to query
Last modified September 18, 2025: docs: fix docs linting (#1520) (3d8a041782)