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:

spanner

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:

parameter	type	default	description
table_names	string	""	Comma-separated list of table names to filter. If empty, lists all tables in user-accessible schemas
output_format	string	“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

Database Documentation: Generate comprehensive documentation of your database schema
Schema Validation: Verify that expected tables and columns exist
Migration Planning: Understand the current schema before making changes
Development Tools: Build tools that need to understand database structure
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

field	type	required	description
kind	string	true	Must be “spanner-list-tables”
source	string	true	Name of the Spanner source to query
description	string	false	Description of the tool that is passed to the LLM
authRequired	string[]	false	List 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 November 7, 2025: fix: unmarshal object_details json string into map to make response have nested json in spannerlisttables (a30f83de26)