vgi-python 0.8.0__py3-none-any.whl

vgi/client/cli_catalog.py

@@ -0,0 +1,182 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Catalog CLI commands for VGI.
+
+This module provides CLI commands for catalog operations, organized hierarchically:
+
+catalog
+├── list                    # List available catalogs
+├── attach <name>           # Attach to a catalog
+├── detach <attach_opaque_data>      # Detach from a catalog
+├── create <name>           # Create a new catalog
+├── drop <name>             # Drop a catalog
+├── version                 # Get catalog version (--attach-opaque-data or --catalog)
+├── schema                  # Schema operations
+│   ├── list/get/create/drop/contents
+├── table                   # Table operations
+│   ├── get/create/drop/rename/...
+├── view                    # View operations
+│   ├── get/create/drop/rename/...
+└── transaction             # Transaction operations
+    ├── begin/commit/rollback
+
+"""
+
+from __future__ import annotations
+
+import click
+
+from vgi.catalog import OnConflict
+from vgi.client.cli_schema import schema
+from vgi.client.cli_table import table
+from vgi.client.cli_transaction import transaction
+from vgi.client.cli_utils import (
+    bytes_to_hex,
+    catalog_attach_result_to_dict,
+    get_attach_opaque_data_from_options,
+    hex_to_attach_opaque_data,
+    hex_to_transaction_opaque_data,
+    output_json,
+    parse_json_option,
+)
+from vgi.client.cli_view import view
+from vgi.client.client import Client
+
+
+@click.group()
+def catalog() -> None:
+    """Manage catalogs, schemas, tables, views, and transactions."""
+
+
+@catalog.command("list")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+def catalog_list(worker: str) -> None:
+    """List available catalogs."""
+    client = Client(worker)
+    catalogs = client.catalogs()
+    output_json(
+        [
+            {
+                "name": c.name,
+                "implementation_version": c.implementation_version,
+                "data_version_spec": c.data_version_spec,
+            }
+            for c in catalogs
+        ]
+    )
+
+
+@catalog.command("attach")
+@click.argument("name")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--options", default="{}", help="Catalog options as JSON object")
+def catalog_attach(name: str, worker: str, options: str) -> None:
+    """Attach to a catalog and return attach_opaque_data.
+
+    NAME is the catalog name to attach to.
+
+    """
+    opts = parse_json_option(options, "--options")
+    client = Client(worker)
+    result = client.catalog_attach(
+        name=name,
+        options=opts,
+        data_version_spec=None,
+        implementation_version=None,
+    )
+    output_json(catalog_attach_result_to_dict(result))
+
+
+@catalog.command("detach")
+@click.argument("attach_opaque_data")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+def catalog_detach(attach_opaque_data: str, worker: str) -> None:
+    """Detach from a catalog.
+
+    ATTACH_ID is the hex-encoded attach ID from catalog attach.
+
+    """
+    client = Client(worker)
+    client.catalog_detach(attach_opaque_data=hex_to_attach_opaque_data(attach_opaque_data))
+    output_json({"status": "detached"})
+
+
+@catalog.command("create")
+@click.argument("name")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option(
+    "--on-conflict",
+    type=click.Choice(["error", "ignore", "replace"]),
+    default="error",
+    help="Behavior if catalog already exists",
+)
+@click.option("--options", default="{}", help="Catalog options as JSON object")
+def catalog_create(name: str, worker: str, on_conflict: str, options: str) -> None:
+    """Create a new catalog.
+
+    NAME is the name for the new catalog.
+
+    """
+    opts = parse_json_option(options, "--options")
+    client = Client(worker)
+    client.catalog_create(
+        name=name,
+        on_conflict=OnConflict(on_conflict),
+        options=opts,
+    )
+    output_json({"status": "created", "name": name})
+
+
+@catalog.command("drop")
+@click.argument("name")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+def catalog_drop(name: str, worker: str) -> None:
+    """Drop a catalog.
+
+    NAME is the name of the catalog to drop.
+
+    """
+    client = Client(worker)
+    client.catalog_drop(name=name)
+    output_json({"status": "dropped", "name": name})
+
+
+@catalog.command("version")
+@click.option("--attach-opaque-data", help="Hex-encoded attach ID")
+@click.option("--catalog", "catalog_name", help="Catalog name for auto-attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--transaction-opaque-data", help="Transaction ID (hex) for transactional read")
+def catalog_version(
+    attach_opaque_data: str | None,
+    catalog_name: str | None,
+    attach_options: str,
+    worker: str,
+    transaction_opaque_data: str | None,
+) -> None:
+    """Get the current catalog version."""
+    client = Client(worker)
+    opts = parse_json_option(attach_options, "--attach-options")
+    resolved_attach_opaque_data, is_stateful = get_attach_opaque_data_from_options(
+        client, attach_opaque_data, catalog_name, opts
+    )
+    if is_stateful and catalog_name:
+        click.echo(
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
+            err=True,
+        )
+    version = client.catalog_version(
+        attach_opaque_data=resolved_attach_opaque_data,
+        transaction_opaque_data=(
+            hex_to_transaction_opaque_data(transaction_opaque_data) if transaction_opaque_data else None
+        ),
+    )
+    output_json({"version": version, "attach_opaque_data": bytes_to_hex(resolved_attach_opaque_data)})
+
+
+# Add nested subcommand groups
+catalog.add_command(schema)
+catalog.add_command(table)
+catalog.add_command(view)
+catalog.add_command(transaction)

vgi/client/cli_schema.py

@@ -0,0 +1,270 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Schema CLI commands for VGI.
+
+This module provides CLI commands for schema operations:
+- list: List schemas in a catalog
+- get: Get schema info
+- create: Create a new schema
+- drop: Drop a schema
+- contents: List contents of a schema (tables, views, functions)
+
+"""
+
+from __future__ import annotations
+
+import click
+
+from vgi.catalog import FunctionInfo, SchemaObjectType, TableInfo, ViewInfo
+from vgi.client.cli_utils import (
+    function_info_to_dict,
+    get_attach_opaque_data_from_options,
+    hex_to_transaction_opaque_data,
+    output_json,
+    parse_json_option,
+    schema_info_to_dict,
+    table_info_to_dict,
+    view_info_to_dict,
+)
+from vgi.client.client import Client
+
+
+@click.group()
+def schema() -> None:
+    """Manage schemas in a catalog."""
+
+
+@schema.command("list")
+@click.option("--attach-opaque-data", help="Hex-encoded attach ID")
+@click.option("--catalog", "catalog_name", help="Catalog name for auto-attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--transaction-opaque-data", help="Transaction ID (hex) for transactional read")
+def schema_list(
+    attach_opaque_data: str | None,
+    catalog_name: str | None,
+    attach_options: str,
+    worker: str,
+    transaction_opaque_data: str | None,
+) -> None:
+    """List schemas in a catalog."""
+    client = Client(worker)
+    opts = parse_json_option(attach_options, "--attach-options")
+    resolved_attach_opaque_data, is_stateful = get_attach_opaque_data_from_options(
+        client, attach_opaque_data, catalog_name, opts
+    )
+    if is_stateful and catalog_name:
+        click.echo(
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
+            err=True,
+        )
+    for schema_info in client.schemas(
+        attach_opaque_data=resolved_attach_opaque_data,
+        transaction_opaque_data=(
+            hex_to_transaction_opaque_data(transaction_opaque_data) if transaction_opaque_data else None
+        ),
+    ):
+        output_json(schema_info_to_dict(schema_info))
+
+
+@schema.command("get")
+@click.argument("name")
+@click.option("--attach-opaque-data", help="Hex-encoded attach ID")
+@click.option("--catalog", "catalog_name", help="Catalog name for auto-attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--transaction-opaque-data", help="Transaction ID (hex) for transactional read")
+def schema_get(
+    name: str,
+    attach_opaque_data: str | None,
+    catalog_name: str | None,
+    attach_options: str,
+    worker: str,
+    transaction_opaque_data: str | None,
+) -> None:
+    """Get information about a schema.
+
+    NAME is the schema name.
+
+    """
+    client = Client(worker)
+    opts = parse_json_option(attach_options, "--attach-options")
+    resolved_attach_opaque_data, is_stateful = get_attach_opaque_data_from_options(
+        client, attach_opaque_data, catalog_name, opts
+    )
+    if is_stateful and catalog_name:
+        click.echo(
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
+            err=True,
+        )
+    schema_info = client.schema_get(
+        attach_opaque_data=resolved_attach_opaque_data,
+        transaction_opaque_data=(
+            hex_to_transaction_opaque_data(transaction_opaque_data) if transaction_opaque_data else None
+        ),
+        name=name,
+    )
+    if schema_info:
+        output_json(schema_info_to_dict(schema_info))
+    else:
+        output_json({"error": "not_found", "name": name})
+
+
+@schema.command("create")
+@click.argument("name")
+@click.option("--attach-opaque-data", help="Hex-encoded attach ID")
+@click.option("--catalog", "catalog_name", help="Catalog name for auto-attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--transaction-opaque-data", help="Transaction ID (hex)")
+@click.option("--comment", help="Description of the schema")
+@click.option("--tags", default="{}", help="Metadata tags as JSON object")
+def schema_create(
+    name: str,
+    attach_opaque_data: str | None,
+    catalog_name: str | None,
+    attach_options: str,
+    worker: str,
+    transaction_opaque_data: str | None,
+    comment: str | None,
+    tags: str,
+) -> None:
+    """Create a new schema.
+
+    NAME is the name for the new schema.
+
+    """
+    client = Client(worker)
+    opts = parse_json_option(attach_options, "--attach-options")
+    resolved_attach_opaque_data, is_stateful = get_attach_opaque_data_from_options(
+        client, attach_opaque_data, catalog_name, opts
+    )
+    if is_stateful and catalog_name:
+        click.echo(
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
+            err=True,
+        )
+    tags_dict = parse_json_option(tags, "--tags")
+    client.schema_create(
+        attach_opaque_data=resolved_attach_opaque_data,
+        transaction_opaque_data=(
+            hex_to_transaction_opaque_data(transaction_opaque_data) if transaction_opaque_data else None
+        ),
+        name=name,
+        comment=comment,
+        tags=tags_dict,
+    )
+    output_json({"status": "created", "name": name})
+
+
+@schema.command("drop")
+@click.argument("name")
+@click.option("--attach-opaque-data", help="Hex-encoded attach ID")
+@click.option("--catalog", "catalog_name", help="Catalog name for auto-attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--transaction-opaque-data", help="Transaction ID (hex)")
+@click.option("--ignore-not-found", is_flag=True, help="Don't error if not found")
+@click.option("--cascade", is_flag=True, help="Drop contained tables and views")
+def schema_drop(
+    name: str,
+    attach_opaque_data: str | None,
+    catalog_name: str | None,
+    attach_options: str,
+    worker: str,
+    transaction_opaque_data: str | None,
+    ignore_not_found: bool,
+    cascade: bool,
+) -> None:
+    """Drop a schema.
+
+    NAME is the name of the schema to drop.
+
+    """
+    client = Client(worker)
+    opts = parse_json_option(attach_options, "--attach-options")
+    resolved_attach_opaque_data, is_stateful = get_attach_opaque_data_from_options(
+        client, attach_opaque_data, catalog_name, opts
+    )
+    if is_stateful and catalog_name:
+        click.echo(
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
+            err=True,
+        )
+    client.schema_drop(
+        attach_opaque_data=resolved_attach_opaque_data,
+        transaction_opaque_data=(
+            hex_to_transaction_opaque_data(transaction_opaque_data) if transaction_opaque_data else None
+        ),
+        name=name,
+        ignore_not_found=ignore_not_found,
+        cascade=cascade,
+    )
+    output_json({"status": "dropped", "name": name})
+
+
+@schema.command("contents")
+@click.argument("name")
+@click.option("--attach-opaque-data", help="Hex-encoded attach ID")
+@click.option("--catalog", "catalog_name", help="Catalog name for auto-attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+@click.option("--transaction-opaque-data", help="Transaction ID (hex) for transactional read")
+@click.option(
+    "--type",
+    "object_type",
+    type=click.Choice(["table", "view", "scalar_function", "table_function", "aggregate_function"]),
+    required=True,
+    help="Object type to list (required)",
+)
+def schema_contents(
+    name: str,
+    attach_opaque_data: str | None,
+    catalog_name: str | None,
+    attach_options: str,
+    worker: str,
+    transaction_opaque_data: str | None,
+    object_type: str,
+) -> None:
+    """List contents of a schema by object type.
+
+    NAME is the schema name.
+
+    Requires --type to specify which object type to list.
+
+    """
+    client = Client(worker)
+    opts = parse_json_option(attach_options, "--attach-options")
+    resolved_attach_opaque_data, is_stateful = get_attach_opaque_data_from_options(
+        client, attach_opaque_data, catalog_name, opts
+    )
+    if is_stateful and catalog_name:
+        click.echo(
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
+            err=True,
+        )
+
+    # Convert string type to SchemaObjectType enum
+    type_filter = SchemaObjectType(object_type)
+
+    for item in client.schema_contents(
+        attach_opaque_data=resolved_attach_opaque_data,
+        transaction_opaque_data=(
+            hex_to_transaction_opaque_data(transaction_opaque_data) if transaction_opaque_data else None
+        ),
+        name=name,
+        type=type_filter,
+    ):
+        if isinstance(item, TableInfo):
+            output_json({"type": "table", **table_info_to_dict(item)})
+        elif isinstance(item, ViewInfo):
+            output_json({"type": "view", **view_info_to_dict(item)})
+        elif isinstance(item, FunctionInfo):
+            output_json({"type": "function", **function_info_to_dict(item)})
+        else:
+            output_json({"type": "unknown", "name": getattr(item, "name", "unknown")})