googlesql

This package contains the GoogleSQL protobuf schemas and generated Python bindings for the local service.

Install the protobuf-only package with:

uv add googlesql

Install the generated gRPC client bindings with:

uv add 'googlesql[grpc]'

The generated modules are available under googlesql.local_service. For example:

import grpc

from googlesql.local_service import local_service_pb2
from googlesql.local_service import local_service_pb2_grpc

channel = grpc.insecure_channel("127.0.0.1:50051")
client = local_service_pb2_grpc.GoogleSqlLocalServiceStub(channel)
response = client.GetAnalyzerOptions(
    local_service_pb2.AnalyzerOptionsRequest()
)

The package follows the current checkout's local_service.proto API. It does not include the GoogleSQL service implementation.

Analyzing with a client-owned catalog

googlesql.client_catalog drives the AnalyzeWithClientCatalog stream: the client sends one AnalyzeRequest, the server sends back each catalog lookup it needs while analyzing, the client answers from its own catalog, and the server finishes with the resolved AST. Lookup answers use the JSON object formats from googlesql_service/CATALOG_PROTOCOL.md section 6. The module needs the grpc extra.

import grpc

from googlesql import client_catalog
from googlesql.local_service import local_service_pb2
from googlesql.local_service import local_service_pb2_grpc


class Catalog:
  def lookup(self, object_kind, name_path):
    if object_kind == "table" and list(name_path) == ["orders"]:
      return {
          "kind": "table",
          "name": "orders",
          "full_name": "project.dataset.orders",
          "columns": [{"name": "id", "type": {"typeKind": "TYPE_INT64"}}],
      }
    return None  # not found


channel = grpc.insecure_channel("127.0.0.1:50051")
stub = local_service_pb2_grpc.GoogleSqlLocalServiceStub(channel)
request = local_service_pb2.AnalyzeRequest(sql_statement="SELECT id FROM orders")
response = client_catalog.analyze_with_client_catalog(
    stub, request, Catalog(), timeout=30
)

A lookup may return None for a missing object or raise client_catalog.CatalogLookupError(message, status_code) to report a typed failure. Analysis failures raise client_catalog.ClientCatalogAnalyzeError with the gRPC status code and message. Pass timeout so a stalled server cannot block the caller indefinitely; it bounds the gRPC call but does not interrupt a lookup that is still running, so a catalog backed by a remote service should enforce its own timeouts.

Regenerating bindings

From the repository root, update the copied proto closure and generated files with:

uv run --project py/googlesql python tools/update_python_client.py

To verify that committed files are up to date without changing the worktree:

uv run --project py/googlesql python tools/update_python_client.py --check

The updater uses the repository's Python template generators and Buf. Bazel is not required for Python client generation.