Metadata-Version: 2.4
Name: googlesql
Version: 0.2.0
Summary: GoogleSQL protobuf schemas and generated local-service clients
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: protobuf>=5.29.6
Requires-Dist: grpcio>=1.71.0 ; extra == "grpc"
Provides-Extra: grpc

# googlesql

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

Install the protobuf-only package with:

```bash
uv add googlesql
```

Install the generated gRPC client bindings with:

```bash
uv add 'googlesql[grpc]'
```

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

```python
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.

```python
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:

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

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

```bash
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.

