qod-cli 0.3.7__py3-none-any.whl

qod_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.7"

qod_cli/commands/_run.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from ..output import render
+from ..rest import ApiError, RestClient
+
+
+def call(
+    ctx: typer.Context,
+    method: str,
+    path: str,
+    params: dict | None = None,
+    body: Any | None = None,
+    text: bool = False,
+) -> Any:
+    try:
+        data = RestClient(ctx.obj.settings).request(method, path, params=params, body=body, text=text)
+    except ApiError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1)
+    render(data, ctx.obj.json_output)
+    return data
+
+
+def kv_pairs(values: list[str] | None) -> dict:
+    out: dict = {}
+    for item in values or []:
+        if "=" not in item:
+            raise typer.BadParameter(f"expected KEY=VALUE, got {item!r}")
+        key, _, value = item.partition("=")
+        out[key] = value
+    return out

qod_cli/commands/auth.py

@@ -0,0 +1,67 @@
+from urllib.parse import urlparse
+
+import typer
+
+from ..config import save_profile
+from ..output import render
+from ..rest import ApiError, RestClient
+from ._run import call
+
+app = typer.Typer(help="Authentication mode discovery.")
+
+
+@app.command()
+def mode(ctx: typer.Context):
+    """Show the auth mode (db or oidc) the manager expects."""
+    call(ctx, "GET", "/api/auth/mode")
+
+
+def login(
+    ctx: typer.Context,
+    url: str = typer.Option(None, "--url", help="Manager URL; defaults to the profile value."),
+    username: str = typer.Option("admin", "--username"),
+    tenant: str = typer.Option(None, "--tenant", help="Tenant for tenant-scoped admins."),
+):
+    """Mint a session, store it and the edge settings in the active profile."""
+    settings = ctx.obj.settings
+    manager_url = url or settings.manager_url
+    password = typer.prompt("Password", hide_input=True)
+    settings.manager_url = manager_url
+    client = RestClient(settings)
+    body = {"username": username, "password": password}
+    if tenant is not None:
+        body["tenant"] = tenant
+    try:
+        login_resp = client.request("POST", "/api/auth/login", body=body)
+        edge = client.request("GET", "/api/config/client")
+    except ApiError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1)
+    edge_host = edge.get("flightSqlHost", "")
+    if edge_host in ("", "0.0.0.0"):
+        edge_host = urlparse(manager_url).hostname or "localhost"
+    save_profile(
+        ctx.obj.profile,
+        {
+            "manager_url": manager_url,
+            "token": login_resp["token"],
+            "sql_user": username,
+            "edge_host": edge_host,
+            "edge_port": edge.get("flightSqlPort", 31338),
+            "edge_tls": edge.get("flightSqlTls", True),
+        },
+    )
+    render(
+        {"username": login_resp.get("username", username), "profile": ctx.obj.profile},
+        ctx.obj.json_output,
+    )
+
+
+def logout(ctx: typer.Context):
+    """Revoke the current session token."""
+    call(ctx, "POST", "/api/auth/logout")
+
+
+def whoami(ctx: typer.Context):
+    """Verify the current session."""
+    call(ctx, "GET", "/api/auth/whoami")

qod_cli/commands/catalog.py

@@ -0,0 +1,173 @@
+import typer
+
+from ._run import call
+
+app = typer.Typer(help="DuckLake catalog browsing, time travel, and recovery.")
+
+TENANT = typer.Argument(..., metavar="TENANT")
+DB = typer.Argument(..., metavar="DB")
+SCHEMA = typer.Argument(..., metavar="SCHEMA")
+TABLE = typer.Argument(..., metavar="TABLE")
+
+
+def _base(tenant: str, db: str) -> str:
+    return f"/api/catalog/tenant/{tenant}/database/{db}"
+
+
+def _at_most_one(**selectors) -> None:
+    given = [name for name, value in selectors.items() if value is not None]
+    if len(given) > 1:
+        raise typer.BadParameter(f"{' and '.join(given)} are mutually exclusive")
+
+
+@app.command()
+def schemas(ctx: typer.Context, tenant: str = TENANT, db: str = DB):
+    call(ctx, "GET", f"{_base(tenant, db)}/schemas")
+
+
+@app.command()
+def tables(ctx: typer.Context, tenant: str = TENANT, db: str = DB, schema: str = SCHEMA):
+    call(ctx, "GET", f"{_base(tenant, db)}/schemas/{schema}/tables")
+
+
+@app.command()
+def describe(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    schema: str = SCHEMA,
+    table: str = TABLE,
+    as_of: int = typer.Option(None, "--as-of", help="Snapshot id."),
+    as_of_tag: str = typer.Option(None, "--as-of-tag"),
+    as_of_ts: str = typer.Option(None, "--as-of-ts", help="ISO timestamp."),
+):
+    _at_most_one(as_of=as_of, as_of_tag=as_of_tag, as_of_ts=as_of_ts)
+    call(
+        ctx,
+        "GET",
+        f"{_base(tenant, db)}/schemas/{schema}/tables/{table}",
+        params={"asOf": as_of, "asOfTag": as_of_tag, "asOfTs": as_of_ts},
+    )
+
+
+@app.command()
+def snapshots(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    limit: int = typer.Option(None, "--limit"),
+    before: int = typer.Option(None, "--before", help="Keyset pagination: snapshot id."),
+    table: str = typer.Option(None, "--table", help="schema.table filter."),
+):
+    call(ctx, "GET", f"{_base(tenant, db)}/snapshots", params={"limit": limit, "before": before, "table": table})
+
+
+@app.command()
+def history(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    schema: str = SCHEMA,
+    table: str = TABLE,
+    limit: int = typer.Option(None, "--limit"),
+    before: int = typer.Option(None, "--before"),
+    from_: str = typer.Option(None, "--from"),
+    to: str = typer.Option(None, "--to"),
+    operation: str = typer.Option(None, "--operation"),
+    author: str = typer.Option(None, "--author"),
+):
+    call(
+        ctx,
+        "GET",
+        f"{_base(tenant, db)}/schemas/{schema}/tables/{table}/history",
+        params={"limit": limit, "before": before, "from": from_, "to": to, "operation": operation, "author": author},
+    )
+
+
+@app.command()
+def preview(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    schema: str = SCHEMA,
+    table: str = TABLE,
+    as_of: int = typer.Option(None, "--as-of"),
+    as_of_tag: str = typer.Option(None, "--as-of-tag"),
+    as_of_ts: str = typer.Option(None, "--as-of-ts"),
+    limit: int = typer.Option(None, "--limit"),
+):
+    _at_most_one(as_of=as_of, as_of_tag=as_of_tag, as_of_ts=as_of_ts)
+    call(
+        ctx,
+        "GET",
+        f"{_base(tenant, db)}/schemas/{schema}/tables/{table}/preview",
+        params={"asOf": as_of, "asOfTag": as_of_tag, "asOfTs": as_of_ts, "limit": limit},
+    )
+
+
+@app.command("data-diff")
+def data_diff(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    schema: str = SCHEMA,
+    table: str = TABLE,
+    from_: str = typer.Option(..., "--from", help="From snapshot selector."),
+    to: str = typer.Option(..., "--to", help="To snapshot selector."),
+    limit: int = typer.Option(None, "--limit"),
+    cursor: str = typer.Option(None, "--cursor"),
+    change_type: str = typer.Option(None, "--change-type"),
+):
+    call(
+        ctx,
+        "GET",
+        f"{_base(tenant, db)}/schemas/{schema}/tables/{table}/data-diff",
+        params={"from": from_, "to": to, "limit": limit, "cursor": cursor, "changeType": change_type},
+    )
+
+
+@app.command("schema-diff")
+def schema_diff(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    schema: str = SCHEMA,
+    table: str = TABLE,
+    from_: str = typer.Option(..., "--from"),
+    to: str = typer.Option(..., "--to"),
+):
+    call(
+        ctx,
+        "GET",
+        f"{_base(tenant, db)}/schemas/{schema}/tables/{table}/schema-diff",
+        params={"from": from_, "to": to},
+    )
+
+
+@app.command()
+def recoverable(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    limit: int = typer.Option(None, "--limit"),
+):
+    """Dropped tables still recoverable via undrop."""
+    call(ctx, "GET", f"{_base(tenant, db)}/recoverable", params={"limit": limit})
+
+
+@app.command()
+def undrop(
+    ctx: typer.Context,
+    tenant: str = typer.Option(..., "--tenant"),
+    db: str = typer.Option(..., "--db"),
+    schema: str = typer.Option(..., "--schema"),
+    table: str = typer.Option(..., "--table"),
+    as_name: str = typer.Option(None, "--as-name", help="Recover under a different name."),
+    from_snapshot: int = typer.Option(None, "--from-snapshot"),
+):
+    body: dict = {"tenant": tenant, "tenantDb": db, "schema": schema, "table": table}
+    if as_name is not None:
+        body["asName"] = as_name
+    if from_snapshot is not None:
+        body["fromSnapshot"] = from_snapshot
+    call(ctx, "POST", "/api/catalog/undrop", body=body)

qod_cli/commands/config_cmd.py

@@ -0,0 +1,17 @@
+import typer
+
+from ._run import call
+
+app = typer.Typer(help="Server-published configuration.")
+
+
+@app.command()
+def client(ctx: typer.Context):
+    """Edge host/port/TLS for client bootstrapping (open endpoint)."""
+    call(ctx, "GET", "/api/config/client")
+
+
+@app.command()
+def server(ctx: typer.Context):
+    """Effective manager configuration."""
+    call(ctx, "GET", "/api/config/server")

qod_cli/commands/database.py

@@ -0,0 +1,69 @@
+import typer
+
+from ._run import call, kv_pairs
+
+app = typer.Typer(help="Tenant databases (DuckLake catalogs).")
+
+
+@app.command("list")
+def list_(ctx: typer.Context, tenant: str = typer.Option(..., "--tenant")):
+    call(ctx, "GET", "/api/database/list", params={"tenant": tenant})
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    tenant: str = typer.Option(..., "--tenant"),
+    name: str = typer.Option(..., "--name", help="Suffix; server composes <tenant>_<name>."),
+    kind: str = typer.Option("ducklake", "--kind", help="ducklake|duckdb-file|memory"),
+    metastore: list[str] = typer.Option(None, "--metastore", help="KEY=VALUE, repeatable."),
+    data_path: str = typer.Option("", "--data-path"),
+    object_store: list[str] = typer.Option(None, "--object-store", help="KEY=VALUE, repeatable."),
+    default_database: str = typer.Option(None, "--default-database"),
+    default_schema: str = typer.Option(None, "--default-schema"),
+    init_sql: str = typer.Option("", "--init-sql"),
+):
+    body = {
+        "tenant": tenant,
+        "name": name,
+        "kind": kind,
+        "metastore": kv_pairs(metastore),
+        "dataPath": data_path,
+        "objectStore": kv_pairs(object_store),
+        "initSql": init_sql,
+    }
+    if default_database is not None:
+        body["defaultDatabase"] = default_database
+    if default_schema is not None:
+        body["defaultSchema"] = default_schema
+    call(ctx, "POST", "/api/database/create", body=body)
+
+
+@app.command()
+def update(
+    ctx: typer.Context,
+    tenant: str = typer.Option(..., "--tenant"),
+    name: str = typer.Option(..., "--name"),
+    metastore: list[str] = typer.Option(None, "--metastore", help="KEY=VALUE; omit = unchanged."),
+    object_store: list[str] = typer.Option(None, "--object-store"),
+    default_database: str = typer.Option(None, "--default-database"),
+    default_schema: str = typer.Option(None, "--default-schema"),
+    init_sql: str = typer.Option(None, "--init-sql"),
+):
+    body: dict = {"tenant": tenant, "name": name}
+    if metastore is not None:
+        body["metastore"] = kv_pairs(metastore)
+    if object_store is not None:
+        body["objectStore"] = kv_pairs(object_store)
+    if default_database is not None:
+        body["defaultDatabase"] = default_database
+    if default_schema is not None:
+        body["defaultSchema"] = default_schema
+    if init_sql is not None:
+        body["initSql"] = init_sql
+    call(ctx, "POST", "/api/database/update", body=body)
+
+
+@app.command()
+def delete(ctx: typer.Context, tenant: str = typer.Option(..., "--tenant"), name: str = typer.Option(..., "--name")):
+    call(ctx, "POST", "/api/database/delete", body={"tenant": tenant, "name": name})

qod_cli/commands/federation.py

@@ -0,0 +1,82 @@
+import typer
+
+from ._run import call
+
+app = typer.Typer(help="Federated sources per (tenant, tenant-db).")
+secret_app = typer.Typer(help="Secrets referenced by a federated source's setup SQL.")
+app.add_typer(secret_app, name="secret")
+
+TENANT = typer.Argument(..., metavar="TENANT")
+DB = typer.Argument(..., metavar="DB")
+ALIAS = typer.Argument(..., metavar="ALIAS")
+
+
+def _base(tenant: str, db: str) -> str:
+    return f"/api/tenants/{tenant}/tenant-dbs/{db}/federated-sources"
+
+
+@app.command("list")
+def list_(ctx: typer.Context, tenant: str = TENANT, db: str = DB):
+    call(ctx, "GET", _base(tenant, db))
+
+
+@app.command()
+def get(ctx: typer.Context, tenant: str = TENANT, db: str = DB, alias: str = ALIAS):
+    call(ctx, "GET", f"{_base(tenant, db)}/{alias}")
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    alias: str = typer.Option(..., "--alias"),
+    setup_sql: str = typer.Option(..., "--setup-sql"),
+    description: str = typer.Option(None, "--description"),
+    disabled: bool = typer.Option(False, "--disabled"),
+):
+    body: dict = {"alias": alias, "setupSql": setup_sql, "disabled": disabled}
+    if description is not None:
+        body["description"] = description
+    call(ctx, "POST", _base(tenant, db), body=body)
+
+
+@app.command()
+def delete(ctx: typer.Context, tenant: str = TENANT, db: str = DB, alias: str = ALIAS):
+    call(ctx, "DELETE", f"{_base(tenant, db)}/{alias}")
+
+
+@secret_app.command("list")
+def secret_list(ctx: typer.Context, tenant: str = TENANT, db: str = DB, alias: str = ALIAS):
+    call(ctx, "GET", f"{_base(tenant, db)}/{alias}/secrets")
+
+
+@secret_app.command("set")
+def secret_set(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    alias: str = ALIAS,
+    name: str = typer.Option(..., "--name"),
+    value: str = typer.Option(None, "--value", help="Inline value stored in Postgres."),
+    external_ref: str = typer.Option(None, "--external-ref", help="e.g. env:PGPASS."),
+):
+    if (value is None) == (external_ref is None):
+        raise typer.BadParameter("pass exactly one of --value / --external-ref")
+    body: dict = {"name": name}
+    if value is not None:
+        body["value"] = value
+    if external_ref is not None:
+        body["externalRef"] = external_ref
+    call(ctx, "PUT", f"{_base(tenant, db)}/{alias}/secrets", body=body)
+
+
+@secret_app.command("delete")
+def secret_delete(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    alias: str = ALIAS,
+    name: str = typer.Argument(..., metavar="NAME"),
+):
+    call(ctx, "DELETE", f"{_base(tenant, db)}/{alias}/secrets/{name}")

qod_cli/commands/group.py

@@ -0,0 +1,28 @@
+import typer
+
+from ._run import call
+
+app = typer.Typer(help="Groups.")
+
+
+@app.command("list")
+def list_(ctx: typer.Context, tenant: str = typer.Option(..., "--tenant")):
+    call(ctx, "GET", "/api/group/list", params={"tenant": tenant})
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    tenant: str = typer.Option(..., "--tenant"),
+    name: str = typer.Option(..., "--name"),
+    description: str = typer.Option(None, "--description"),
+):
+    body: dict = {"tenant": tenant, "name": name}
+    if description is not None:
+        body["description"] = description
+    call(ctx, "POST", "/api/group/create", body=body)
+
+
+@app.command()
+def delete(ctx: typer.Context, group_id: str = typer.Argument(..., metavar="ID")):
+    call(ctx, "POST", "/api/group/delete", body={"id": group_id})

qod_cli/commands/maintenance.py

@@ -0,0 +1,81 @@
+import typer
+
+from ._run import call
+
+app = typer.Typer(help="Managed maintenance policies and runs.")
+
+TENANT = typer.Option(..., "--tenant")
+DB = typer.Option(..., "--db")
+
+
+@app.command()
+def policy(ctx: typer.Context, tenant: str = TENANT, db: str = DB):
+    call(ctx, "GET", "/api/maintenance/policy", params={"tenant": tenant, "tenantDb": db})
+
+
+@app.command("policy-upsert")
+def policy_upsert(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    scope_kind: str = typer.Option(..., "--scope-kind", help="tenantdb|schema|table"),
+    scope_schema: str = typer.Option(None, "--scope-schema"),
+    scope_table: str = typer.Option(None, "--scope-table"),
+    enabled: bool = typer.Option(None, "--enabled/--disabled"),
+    retention_days: int = typer.Option(None, "--retention-days"),
+    compaction_enabled: bool = typer.Option(None, "--compaction-enabled/--compaction-disabled"),
+    target_file_size: str = typer.Option(None, "--target-file-size"),
+    small_file_min_count: int = typer.Option(None, "--small-file-min-count"),
+    rewrite_delete_threshold: float = typer.Option(None, "--rewrite-delete-threshold"),
+    cleanup_grace_days: int = typer.Option(None, "--cleanup-grace-days"),
+    orphan_min_age_days: int = typer.Option(None, "--orphan-min-age-days"),
+    cron: str = typer.Option(None, "--cron"),
+):
+    body: dict = {"tenant": tenant, "tenantDb": db, "scopeKind": scope_kind}
+    optional = {
+        "scopeSchema": scope_schema,
+        "scopeTable": scope_table,
+        "enabled": enabled,
+        "retentionDays": retention_days,
+        "compactionEnabled": compaction_enabled,
+        "targetFileSize": target_file_size,
+        "smallFileMinCount": small_file_min_count,
+        "rewriteDeleteThreshold": rewrite_delete_threshold,
+        "cleanupGraceDays": cleanup_grace_days,
+        "orphanMinAgeDays": orphan_min_age_days,
+        "cron": cron,
+    }
+    body.update({k: v for k, v in optional.items() if v is not None})
+    call(ctx, "POST", "/api/maintenance/policy/upsert", body=body)
+
+
+@app.command("policy-delete")
+def policy_delete(ctx: typer.Context, policy_id: str = typer.Argument(..., metavar="ID")):
+    call(ctx, "POST", "/api/maintenance/policy/delete", body={"id": policy_id})
+
+
+@app.command()
+def run(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    scope: str = typer.Option(None, "--scope"),
+    operations: str = typer.Option(None, "--operations", help="Comma-separated."),
+):
+    body: dict = {"tenant": tenant, "tenantDb": db}
+    if scope is not None:
+        body["scope"] = scope
+    if operations is not None:
+        body["operations"] = operations
+    call(ctx, "POST", "/api/maintenance/run", body=body)
+
+
+@app.command()
+def runs(
+    ctx: typer.Context,
+    tenant: str = TENANT,
+    db: str = DB,
+    limit: int = typer.Option(None, "--limit"),
+    before: int = typer.Option(None, "--before"),
+):
+    call(ctx, "GET", "/api/maintenance/runs", params={"tenant": tenant, "tenantDb": db, "limit": limit, "before": before})

qod_cli/commands/manifest.py

@@ -0,0 +1,34 @@
+import typer
+
+from ..rest import ApiError, RestClient
+from ._run import call
+
+app = typer.Typer(help="Topology manifest export/import (YAML).")
+
+
+@app.command()
+def export(
+    ctx: typer.Context,
+    out: str = typer.Option(None, "--out", help="File path; omit = stdout."),
+):
+    """Export the whole control-plane topology as YAML."""
+    try:
+        text = RestClient(ctx.obj.settings).request("GET", "/api/manifest/export", text=True)
+    except ApiError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1)
+    if out is None:
+        typer.echo(text, nl=False)
+    else:
+        with open(out, "w") as f:
+            f.write(text)
+        typer.echo(f"wrote {out}", err=True)
+
+
+@app.command("import")
+def import_(
+    ctx: typer.Context,
+    file: typer.FileText = typer.Argument(..., help="Manifest YAML file, or - for stdin."),
+):
+    """Import a topology manifest (YAML) into the control plane."""
+    call(ctx, "POST", "/api/manifest/import", body=file.read())

qod_cli/commands/membership.py

@@ -0,0 +1,50 @@
+import typer
+
+from ._run import call
+
+app = typer.Typer(help="RBAC membership edges.")
+user_role_app = typer.Typer(help="User to role memberships.")
+user_group_app = typer.Typer(help="User to group memberships.")
+group_role_app = typer.Typer(help="Group to role memberships.")
+app.add_typer(user_role_app, name="user-role")
+app.add_typer(user_group_app, name="user-group")
+app.add_typer(group_role_app, name="group-role")
+
+USER = typer.Option(..., "--user-id")
+ROLE = typer.Option(..., "--role-id")
+GROUP = typer.Option(..., "--group-id")
+
+
+@user_role_app.command()
+def add(ctx: typer.Context, user_id: str = USER, role_id: str = ROLE):
+    call(ctx, "POST", "/api/membership/user-role/add", body={"userId": user_id, "roleId": role_id})
+
+
+@user_role_app.command()
+def remove(ctx: typer.Context, user_id: str = USER, role_id: str = ROLE):
+    call(ctx, "POST", "/api/membership/user-role/remove", body={"userId": user_id, "roleId": role_id})
+
+
+@user_group_app.command("add")
+def ug_add(ctx: typer.Context, user_id: str = USER, group_id: str = GROUP):
+    call(ctx, "POST", "/api/membership/user-group/add", body={"userId": user_id, "groupId": group_id})
+
+
+@user_group_app.command("remove")
+def ug_remove(ctx: typer.Context, user_id: str = USER, group_id: str = GROUP):
+    call(ctx, "POST", "/api/membership/user-group/remove", body={"userId": user_id, "groupId": group_id})
+
+
+@group_role_app.command("add")
+def gr_add(ctx: typer.Context, group_id: str = GROUP, role_id: str = ROLE):
+    call(ctx, "POST", "/api/membership/group-role/add", body={"groupId": group_id, "roleId": role_id})
+
+
+@group_role_app.command("remove")
+def gr_remove(ctx: typer.Context, group_id: str = GROUP, role_id: str = ROLE):
+    call(ctx, "POST", "/api/membership/group-role/remove", body={"groupId": group_id, "roleId": role_id})
+
+
+@group_role_app.command("list")
+def gr_list(ctx: typer.Context, group_id: str = GROUP):
+    call(ctx, "GET", "/api/membership/group-role/list", params={"groupId": group_id})