sqlnow-mcp 0.1.0__py3-none-any.whl

sqlnow_mcp/db.py

@@ -0,0 +1,827 @@
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from pathlib import Path
+from typing import Any, Literal
+
+import duckdb
+
+AttachMode = Literal["view", "load"]
+DbType = Literal["POSTGRES", "SQLITE", "MYSQL"]
+
+MAX_ROWS = 100_000
+BACKGROUND_CHUNK_ROWS = 2_000
+
+
+class DuckDBSessionError(Exception):
+    pass
+
+
+class DuckDBSession:
+    def __init__(
+        self,
+        data_dir: Path,
+        allow_paths: list[Path] | tuple[Path, ...] = (),
+        allow_external: bool = False,
+        *,
+        read_only: bool = False,
+        query_timeout_sec: float | None = None,
+    ) -> None:
+        self.data_dir = data_dir.resolve()
+        resolved_allow = tuple(p.resolve() for p in allow_paths)
+        for path in resolved_allow:
+            if path in {Path("/"), Path()}:
+                raise DuckDBSessionError(
+                    f"Unsafe allow_paths entry {path!s} (would allow any file on disk)"
+                )
+        self.allow_paths = resolved_allow
+        self.allow_external = allow_external
+        self.read_only = read_only
+        self.query_timeout_sec = query_timeout_sec
+        self.native_tables_only = False
+        self.conn: duckdb.DuckDBPyConnection | None = None
+        self.active_db: Path | None = None
+        self.attachments: list[dict[str, Any]] = []
+        self.failed_attachments: list[dict[str, Any]] = []
+        self._query_view_ids: list[str] = []
+        self._query_meta: dict[str, dict[str, Any]] = {}
+
+    def use_memory(self) -> None:
+        self._close_connection()
+        self.conn = duckdb.connect()
+        self._install_extensions(self.conn)
+        self.active_db = None
+        self.attachments = []
+        self.failed_attachments = []
+
+    def use_database(self, db_name: str) -> dict[str, Any]:
+        db_path = self._resolve_db_path(db_name)
+        if not db_path.exists():
+            raise DuckDBSessionError(f"Database not found: {db_name}")
+
+        self._close_connection()
+        self.conn = duckdb.connect(str(db_path))
+        self._install_extensions(self.conn)
+        self.active_db = db_path
+        self.attachments = []
+        self.failed_attachments = []
+
+        sidecar = self._load_sidecar(db_path)
+        for entry in sidecar.get("attachments", []):
+            try:
+                if not self._is_attached(entry["name"]):
+                    self._attach_from_sidecar(entry)
+                self.attachments.append(entry)
+            except Exception as exc:
+                failed = dict(entry)
+                failed["error"] = str(exc)
+                self.failed_attachments.append(failed)
+
+        return {
+            "name": db_path.stem,
+            "path": str(db_path),
+            "tables": self._list_table_names(),
+            "attachments": list(self.attachments),
+            "failed_attachments": list(self.failed_attachments),
+        }
+
+    def open_publish_database(
+        self,
+        db_path: Path,
+        *,
+        memory_limit: str,
+        threads: int,
+        max_temp_directory_size: str | None = None,
+    ) -> dict[str, Any]:
+        resolved = db_path.resolve()
+        if not resolved.exists():
+            raise DuckDBSessionError(f"Database not found: {resolved}")
+
+        self._close_connection()
+        self.conn = duckdb.connect(str(resolved), read_only=True)
+        self._install_extensions(self.conn)
+        self.active_db = resolved
+        self.attachments = []
+        self.failed_attachments = []
+        self.native_tables_only = True
+
+        self._reject_publish_attachments(resolved)
+
+        escaped_memory = self._escape_sql_string(memory_limit)
+        self._run_sql(f"SET memory_limit = '{escaped_memory}'")
+        self._run_sql(f"SET threads = {int(threads)}")
+        if max_temp_directory_size:
+            escaped_temp = self._escape_sql_string(max_temp_directory_size)
+            self._run_sql(f"SET max_temp_directory_size = '{escaped_temp}'")
+
+        return {
+            "name": resolved.stem,
+            "path": str(resolved),
+            "tables": self._list_table_names(native_only=True),
+            "read_only": True,
+        }
+
+    def create_database(self, db_name: str) -> dict[str, Any]:
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        db_path = self._resolve_db_path(db_name)
+        name = db_path.stem
+        if not name or name in {".", ".."}:
+            raise DuckDBSessionError(f"Invalid database name: {db_name}")
+        if not self._is_under_root(db_path, self.data_dir):
+            raise DuckDBSessionError(f"Invalid database name: {db_name}")
+        if db_path.exists():
+            raise DuckDBSessionError(f"Database already exists: {name}")
+
+        conn = duckdb.connect(str(db_path))
+        try:
+            self._install_extensions(conn)
+        finally:
+            conn.close()
+
+        return {"name": name, "path": str(db_path)}
+
+    def list_databases(self) -> list[dict[str, Any]]:
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        results: list[dict[str, Any]] = []
+        for db_path in sorted(self.data_dir.glob("*.db")):
+            stat = db_path.stat()
+            results.append(
+                {
+                    "name": db_path.stem,
+                    "path": str(db_path),
+                    "size_mb": round(stat.st_size / (1024 * 1024), 3),
+                    "last_modified": datetime.fromtimestamp(stat.st_mtime).isoformat(),
+                }
+            )
+        return results
+
+    def current_database(self) -> dict[str, Any]:
+        if self.conn is None:
+            return {
+                "name": None,
+                "path": None,
+                "in_memory": False,
+                "attachments": [],
+                "failed_attachments": [],
+            }
+        return {
+            "name": self.active_db.stem if self.active_db else None,
+            "path": str(self.active_db) if self.active_db else None,
+            "in_memory": self.active_db is None,
+            "attachments": list(self.attachments),
+            "failed_attachments": list(self.failed_attachments),
+        }
+
+    def attach_file(
+        self,
+        path: str,
+        name: str | None = None,
+        mode: AttachMode = "view",
+    ) -> dict[str, Any]:
+        conn = self._require_conn()
+        resolved = self._resolve_allowed_path(path)
+        if not resolved.exists():
+            raise DuckDBSessionError(f"File not found: {path}")
+
+        table_name = name or resolved.stem
+        sql = self._file_attach_sql(resolved, table_name, mode)
+        conn.execute(sql)
+        return {"name": table_name, "path": str(resolved), "mode": mode}
+
+    def attach_database(
+        self,
+        connection_string: str,
+        name: str,
+        tables: list[str] | None = None,
+    ) -> dict[str, Any]:
+        if not self.allow_external:
+            raise DuckDBSessionError("External database attachments are disabled")
+
+        conn = self._require_conn()
+        db_type, attach_str = self._parse_database_connection(connection_string)
+        sql = (
+            f"ATTACH '{self._escape_sql_string(attach_str)}' "
+            f"AS {self._quote_ident(name)} (TYPE {db_type})"
+        )
+        conn.execute(sql)
+
+        entry: dict[str, Any] = {
+            "name": name,
+            "type": db_type,
+            "connection_string": connection_string,
+        }
+        if tables:
+            entry["tables"] = tables
+
+        self.attachments.append(entry)
+        self._save_sidecar()
+        return entry
+
+    def detach_source(self, name: str) -> dict[str, Any]:
+        conn = self._require_conn()
+        attachment = next((a for a in self.attachments if a["name"] == name), None)
+        if attachment is not None:
+            conn.execute(f"DETACH {self._quote_ident(name)}")
+            self.attachments = [a for a in self.attachments if a["name"] != name]
+            self._save_sidecar()
+            return {"name": name, "detached": True, "type": "database"}
+
+        quoted = self._quote_ident(name)
+        conn.execute(f"DROP VIEW IF EXISTS {quoted}")
+        conn.execute(f"DROP TABLE IF EXISTS {quoted}")
+        return {"name": name, "detached": True, "type": "file"}
+
+    def run_mutating_query(self, sql: str) -> dict[str, Any]:
+        result = self._run_sql(sql.strip().rstrip(";"))
+        return self._format_execution_result(result)
+
+    def run_query(self, sql: str, limit: int = 500) -> dict[str, Any]:
+        if self._is_mutating_sql(sql):
+            return self.run_mutating_query(sql)
+
+        result = self._run_sql(sql)
+        if not result.description:
+            return {"headers": [], "rows": [], "types": []}
+        headers = [col[0] for col in result.description]
+        types = [str(col[1]) for col in result.description]
+        rows: list[list[str]] = []
+        for row in result.fetchmany(limit):
+            rows.append([self._stringify_value(v) for v in row])
+        return {"headers": headers, "rows": rows, "types": types}
+
+    def run_select_query(self, sql: str, limit: int = 500) -> dict[str, Any]:
+        """Create a TEMP VIEW for the SELECT and return the first page for the table UI."""
+        if self._is_mutating_sql(sql):
+            raise DuckDBSessionError(
+                "run_select_query requires a SELECT statement; use run_query for DDL/DML"
+            )
+
+        query_id = self._new_query_id()
+        view_name = self._query_view_name(query_id)
+        stripped = sql.strip().rstrip(";")
+        self._run_sql(f"CREATE OR REPLACE TEMP VIEW {view_name} AS ({stripped})")
+        self._query_view_ids.append(query_id)
+
+        total_rows = self._count_query_rows(query_id)
+        self._query_meta.setdefault(query_id, {})["total_rows"] = total_rows
+
+        page_limit = min(int(limit), MAX_ROWS)
+        page = self._fetch_query_page(query_id, offset=0, limit=page_limit)
+        has_more = page["has_more"]
+        return {
+            "query_id": query_id,
+            "sql": stripped,
+            "columns": page["columns"],
+            "types": page["types"],
+            "rows": page["rows"],
+            "offset": 0,
+            "total_rows": total_rows,
+            "row_cap": MAX_ROWS,
+            "has_more": has_more,
+            "loading": has_more,
+            "complete": not has_more,
+            "capped": False,
+        }
+
+    def fetch_table_page(
+        self, query_id: str, offset: int, limit: int = BACKGROUND_CHUNK_ROWS
+    ) -> dict[str, Any]:
+        if query_id not in self._query_view_ids:
+            raise DuckDBSessionError(f"Unknown query_id: {query_id}")
+
+        offset = int(offset)
+        if offset >= MAX_ROWS:
+            meta = self._query_meta[query_id]
+            return {
+                "query_id": query_id,
+                "columns": meta["columns"],
+                "types": meta["types"],
+                "rows": [],
+                "offset": offset,
+                "total_rows": meta.get("total_rows"),
+                "row_cap": MAX_ROWS,
+                "has_more": False,
+                "complete": True,
+                "capped": True,
+            }
+
+        page_limit = min(int(limit), MAX_ROWS - offset, BACKGROUND_CHUNK_ROWS)
+        page = self._fetch_query_page(query_id, offset=offset, limit=page_limit)
+        loaded = offset + len(page["rows"])
+        capped = loaded >= MAX_ROWS and page["has_more"]
+        if capped:
+            page["has_more"] = False
+        meta = self._query_meta.get(query_id, {})
+        return {
+            "query_id": query_id,
+            "columns": page["columns"],
+            "types": page["types"],
+            "rows": page["rows"],
+            "offset": offset,
+            "total_rows": meta.get("total_rows"),
+            "row_cap": MAX_ROWS,
+            "has_more": page["has_more"],
+            "complete": not page["has_more"],
+            "capped": capped,
+        }
+
+    def list_tables(self, *, native_only: bool | None = None) -> list[dict[str, Any]]:
+        if native_only is None:
+            native_only = self.native_tables_only
+        return self._list_tables(native_only=native_only)
+
+    def describe_table(
+        self, table_name: str, *, native_only: bool | None = None
+    ) -> dict[str, Any]:
+        if native_only is None:
+            native_only = self.native_tables_only
+        return self._describe_table(table_name, native_only=native_only)
+
+    def sample_table(self, table_name: str, n: int = 10) -> dict[str, Any]:
+        quoted = self._quote_table_ref(table_name)
+        sql = f"SELECT * FROM {quoted} LIMIT {int(n)}"
+        result = self.run_query(sql, limit=int(n))
+        return {
+            "table": table_name,
+            "sql": sql,
+            "rows": [dict(zip(result["headers"], row, strict=True)) for row in result["rows"]],
+        }
+
+    def profile_table(self, table_name: str, sample_threshold: int = 100_000) -> dict[str, Any]:
+        quoted = self._quote_table_ref(table_name)
+        count_row = self._run_sql(f"SELECT COUNT(*) FROM {quoted}").fetchone()
+        if count_row is None:
+            raise DuckDBSessionError(f"Could not count rows for table: {table_name}")
+        count = count_row[0]
+        if count <= sample_threshold:
+            sql = f"SUMMARIZE {quoted}"
+            sampled = False
+        else:
+            pct = min(100 * sample_threshold / count, 100)
+            sql = (
+                f"SUMMARIZE SELECT * FROM {quoted} "
+                f"USING SAMPLE {pct:.2f} PERCENT (bernoulli)"
+            )
+            sampled = True
+        result = self._run_sql(sql)
+        headers = [col[0] for col in result.description]
+        profile = [
+            dict(zip(headers, row, strict=True)) for row in result.fetchall()
+        ]
+        return {"sampled": sampled, "row_count": count, "profile": profile}
+
+    def value_counts(self, table_name: str, column_name: str, limit: int = 20) -> dict[str, Any]:
+        quoted_table = self._quote_table_ref(table_name)
+        quoted_col = self._quote_ident(column_name)
+        sql = (
+            f"SELECT {quoted_col} AS value, COUNT(*) AS count "
+            f"FROM {quoted_table} "
+            f"GROUP BY {quoted_col} "
+            f"ORDER BY count DESC "
+            f"LIMIT {int(limit)}"
+        )
+        result = self.run_query(sql, limit=limit)
+        rows = [dict(zip(result["headers"], row, strict=True)) for row in result["rows"]]
+        return {
+            "table": table_name,
+            "column": column_name,
+            "sql": sql,
+            "rows": rows,
+        }
+
+    def _format_execution_result(self, result: Any) -> dict[str, Any]:
+        if not result.description:
+            return {"ok": True, "message": "Statement executed successfully."}
+
+        headers = [col[0] for col in result.description]
+        record_rows = [
+            dict(
+                zip(
+                    headers,
+                    [self._stringify_value(v) for v in row],
+                    strict=True,
+                )
+            )
+            for row in result.fetchall()
+        ]
+
+        if not record_rows:
+            return {"ok": True, "message": "Statement executed successfully."}
+
+        if len(headers) == 1 and len(record_rows) == 1:
+            column = headers[0]
+            value = record_rows[0][column]
+            if column.lower() == "count" and value.isdigit():
+                count = int(value)
+                return {
+                    "ok": True,
+                    "message": f"{count:,} row(s) affected.",
+                    "rows_affected": count,
+                }
+            if column.lower() == "success":
+                return {
+                    "ok": True,
+                    "message": "Statement executed successfully.",
+                }
+
+        if len(record_rows) == 1 and len(headers) <= 8:
+            parts = [f"{column}: {record_rows[0][column]}" for column in headers]
+            return {
+                "ok": True,
+                "message": "; ".join(parts),
+                "columns": headers,
+                "rows": record_rows,
+            }
+
+        if len(headers) <= 12 and len(record_rows) <= 20:
+            lines = ["\t".join(headers)]
+            for row in record_rows:
+                lines.append("\t".join(row[column] for column in headers))
+            return {
+                "ok": True,
+                "message": "\n".join(lines),
+                "columns": headers,
+                "rows": record_rows,
+            }
+
+        return {
+            "ok": True,
+            "message": f"Statement returned {len(record_rows):,} row(s).",
+            "columns": headers,
+            "rows": record_rows,
+        }
+
+    @staticmethod
+    def _is_mutating_sql(sql: str) -> bool:
+        stripped = sql.strip().rstrip(";")
+        upper = stripped.upper()
+        mutating_prefixes = (
+            "CREATE",
+            "DROP",
+            "ALTER",
+            "INSERT",
+            "UPDATE",
+            "DELETE",
+            "COPY",
+            "ATTACH",
+            "DETACH",
+            "INSTALL",
+            "LOAD",
+            "SET",
+            "PRAGMA",
+        )
+        return any(upper.startswith(prefix) for prefix in mutating_prefixes)
+
+    def _require_conn(self) -> duckdb.DuckDBPyConnection:
+        if self.conn is None:
+            raise DuckDBSessionError("No active database connection")
+        return self.conn
+
+    def _run_sql(self, sql: str, parameters: list[Any] | None = None) -> Any:
+        conn = self._require_conn()
+        if self.query_timeout_sec is None:
+            if parameters is None:
+                return conn.execute(sql)
+            return conn.execute(sql, parameters)
+
+        timer: threading.Timer | None = None
+        try:
+            timer = threading.Timer(self.query_timeout_sec, conn.interrupt)
+            timer.start()
+            if parameters is None:
+                return conn.execute(sql)
+            return conn.execute(sql, parameters)
+        except duckdb.InterruptException as exc:
+            raise DuckDBSessionError(
+                f"Query timed out after {self.query_timeout_sec:g}s"
+            ) from exc
+        finally:
+            if timer is not None:
+                timer.cancel()
+
+    def _close_connection(self) -> None:
+        if self.conn is not None:
+            self.conn.close()
+            self.conn = None
+        self._query_view_ids = []
+        self._query_meta = {}
+
+    @staticmethod
+    def _new_query_id() -> str:
+        return secrets.token_hex(6)
+
+    def _query_view_name(self, query_id: str) -> str:
+        return f"__sqlnow_q_{query_id}"
+
+    def _count_query_rows(self, query_id: str) -> int:
+        quoted = self._quote_ident(self._query_view_name(query_id))
+        row = self._run_sql(f"SELECT COUNT(*) FROM {quoted}").fetchone()
+        if row is None:
+            raise DuckDBSessionError(f"Could not count rows for query: {query_id}")
+        return int(row[0])
+
+    def _fetch_query_page(
+        self, query_id: str, offset: int, limit: int
+    ) -> dict[str, Any]:
+        view_name = self._query_view_name(query_id)
+        quoted = self._quote_ident(view_name)
+        result = self._run_sql(
+            f"SELECT * FROM {quoted} LIMIT {int(limit)} OFFSET {int(offset)}"
+        )
+        if not result.description:
+            meta = self._query_meta.get(query_id, {})
+            return {
+                "columns": meta.get("columns", []),
+                "types": meta.get("types", []),
+                "rows": [],
+                "has_more": False,
+            }
+
+        columns = [col[0] for col in result.description]
+        types = [str(col[1]) for col in result.description]
+        meta = self._query_meta.setdefault(query_id, {})
+        meta["columns"] = columns
+        meta["types"] = types
+
+        record_rows: list[dict[str, str]] = []
+        for row in result.fetchall():
+            record_rows.append(
+                dict(
+                    zip(
+                        columns,
+                        [self._stringify_value(v) for v in row],
+                        strict=True,
+                    )
+                )
+            )
+
+        next_offset = offset + len(record_rows)
+        if len(record_rows) < limit or next_offset >= MAX_ROWS:
+            has_more = False
+        else:
+            peek = self._run_sql(
+                f"SELECT 1 FROM {quoted} LIMIT 1 OFFSET {next_offset}"
+            ).fetchone()
+            has_more = peek is not None
+        return {
+            "columns": columns,
+            "types": types,
+            "rows": record_rows,
+            "has_more": has_more,
+        }
+
+    def _resolve_db_path(self, db_name: str) -> Path:
+        name = db_name.removesuffix(".db")
+        return (self.data_dir / f"{name}.db").resolve()
+
+    def _sidecar_path(self, db_path: Path | None = None) -> Path | None:
+        path = db_path or self.active_db
+        if path is None:
+            return None
+        return path.with_suffix(".db.json")
+
+    def _load_sidecar(self, db_path: Path) -> dict[str, Any]:
+        sidecar = self._sidecar_path(db_path)
+        if sidecar is None or not sidecar.exists():
+            return {"attachments": []}
+        return json.loads(sidecar.read_text(encoding="utf-8"))
+
+    def _save_sidecar(self) -> None:
+        sidecar = self._sidecar_path()
+        if sidecar is None:
+            return
+        payload = {"attachments": self.attachments}
+        sidecar.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+    def _is_attached(self, name: str) -> bool:
+        conn = self._require_conn()
+        rows = conn.execute(
+            "SELECT 1 FROM duckdb_databases() WHERE database_name = ?",
+            [name],
+        ).fetchall()
+        return bool(rows)
+
+    def _attach_from_sidecar(self, entry: dict[str, Any]) -> None:
+        conn = self._require_conn()
+        db_type = entry["type"]
+        name = entry["name"]
+        connection_string = entry["connection_string"]
+        _, attach_str = self._parse_database_connection(connection_string)
+        sql = (
+            f"ATTACH '{self._escape_sql_string(attach_str)}' "
+            f"AS {self._quote_ident(name)} (TYPE {db_type})"
+        )
+        conn.execute(sql)
+
+    @staticmethod
+    def _install_extensions(conn: duckdb.DuckDBPyConnection) -> None:
+        conn.execute(
+            """
+            INSTALL parquet; LOAD parquet;
+            INSTALL httpfs; LOAD httpfs;
+            INSTALL aws; LOAD aws;
+            INSTALL postgres; LOAD postgres;
+            INSTALL sqlite; LOAD sqlite;
+            INSTALL mysql; LOAD mysql;
+            INSTALL json; LOAD json;
+            INSTALL excel; LOAD excel;
+            SET GLOBAL sqlite_all_varchar = true;
+            """
+        )
+
+    def _resolve_allowed_path(self, path: str) -> Path:
+        candidate = Path(path).expanduser()
+        if not candidate.is_absolute():
+            candidate = (self.data_dir / candidate).resolve()
+        else:
+            candidate = candidate.resolve()
+
+        allowed_roots = (self.data_dir, *self.allow_paths)
+        if not any(self._is_under_root(candidate, root) for root in allowed_roots):
+            raise DuckDBSessionError(f"Path not allowed: {path}")
+        return candidate
+
+    @staticmethod
+    def _is_under_root(path: Path, root: Path) -> bool:
+        try:
+            path.relative_to(root.resolve() if hasattr(root, 'resolve') else root)
+            return True
+        except ValueError:
+            return False
+
+    @staticmethod
+    def _escape_sql_string(value: str) -> str:
+        return value.replace("'", "''")
+
+    @staticmethod
+    def _quote_ident(name: str) -> str:
+        escaped = name.replace('"', '""')
+        return f'"{escaped}"'
+
+    def _quote_table_ref(self, table_name: str) -> str:
+        if "." in table_name:
+            parts = table_name.split(".")
+            return ".".join(self._quote_ident(part) for part in parts)
+        return self._quote_ident(table_name)
+
+    @staticmethod
+    def _parse_database_connection(connection_string: str) -> tuple[DbType, str]:
+        if connection_string.startswith(("postgresql://", "postgres://")):
+            return "POSTGRES", connection_string
+        if connection_string.startswith("mysql://"):
+            return "MYSQL", connection_string
+        if connection_string.startswith("sqlite://"):
+            return "SQLITE", connection_string.replace("sqlite://", "", 1)
+        if connection_string.endswith((".db", ".sqlite")):
+            return "SQLITE", connection_string
+        raise DuckDBSessionError(f"Unsupported database connection string: {connection_string}")
+
+    def _file_reader_sql(self, path: Path) -> str:
+        """Build a DuckDB table function for a supported file type."""
+        # Future: tiered JSON attach — try read_json/read_ndjson first (here); on failure
+        # or attach_file(flatten=True), use the Python `flatterer` package (same approach
+        # as querier/libsqlnow json.rs) to flatten nested JSON into multiple CSV tables
+        # and COPY into DuckDB. That gives IATI-style multi-table loads; not needed for
+        # flat JSON arrays.
+        path_sql = self._escape_sql_string(str(path))
+        suffix = path.suffix.lower()
+        if suffix == ".csv":
+            return f"read_csv('{path_sql}', header = true)"
+        if suffix == ".parquet":
+            return f"read_parquet('{path_sql}')"
+        if suffix == ".json":
+            return f"read_json('{path_sql}')"
+        if suffix == ".jsonl":
+            return f"read_ndjson('{path_sql}')"
+        if suffix == ".xlsx":
+            return f"read_xlsx('{path_sql}', header = true)"
+        raise DuckDBSessionError(f"Unsupported file type: {suffix}")
+
+    def _file_attach_sql(self, path: Path, name: str, mode: AttachMode) -> str:
+        reader = self._file_reader_sql(path)
+        quoted = self._quote_ident(name)
+        object_type = "VIEW" if mode == "view" else "TABLE"
+        return f"CREATE OR REPLACE {object_type} {quoted} AS SELECT * FROM {reader}"
+
+    def _list_table_names(self, *, native_only: bool = False) -> list[str]:
+        return [t["name"] for t in self._list_tables(native_only=native_only)]
+
+    def _list_tables(self, *, native_only: bool = False) -> list[dict[str, Any]]:
+        conn = self._require_conn()
+        main_catalog = self.active_db.stem if self.active_db else None
+        tables_sql = """
+            SELECT table_catalog, table_schema, table_name
+            FROM information_schema.tables
+            WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
+            ORDER BY table_catalog, table_schema, table_name
+        """
+        columns_sql = """
+            SELECT table_catalog, table_schema, table_name, column_name, data_type
+            FROM information_schema.columns
+            WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
+            ORDER BY table_catalog, table_schema, table_name, column_name
+        """
+        table_rows = conn.execute(tables_sql).fetchall()
+        column_rows = conn.execute(columns_sql).fetchall()
+
+        columns_by_table: dict[tuple[str, str, str], list[dict[str, str]]] = {}
+        for catalog, schema, table, column_name, data_type in column_rows:
+            key = (catalog, schema, table)
+            columns_by_table.setdefault(key, []).append(
+                {"name": column_name, "type": data_type}
+            )
+
+        results: list[dict[str, Any]] = []
+        for catalog, schema, table in table_rows:
+            if native_only and main_catalog and catalog != main_catalog:
+                continue
+            if not self._table_visible(catalog, schema, table):
+                continue
+            display_name = self._display_table_name(catalog, schema, table)
+            key = (catalog, schema, table)
+            columns = columns_by_table.get(key, [])
+            if not columns:
+                continue
+            results.append({"name": display_name, "columns": columns})
+        return results
+
+    def _describe_table(self, table_name: str, *, native_only: bool = False) -> dict[str, Any]:
+        tables = self._list_tables(native_only=native_only)
+        match = next((t for t in tables if t["name"] == table_name), None)
+        if match is None:
+            raise DuckDBSessionError(f"Table not found: {table_name}")
+        return match
+
+    def _reject_publish_attachments(self, db_path: Path) -> None:
+        sidecar = self._load_sidecar(db_path)
+        attachments = sidecar.get("attachments") or []
+        if attachments:
+            names = ", ".join(entry["name"] for entry in attachments)
+            sidecar_name = db_path.with_suffix(".db.json").name
+            raise DuckDBSessionError(
+                "Publish mode does not support attached databases; "
+                f"remove entries from {sidecar_name}: {names}"
+            )
+
+        main_catalog = db_path.stem
+        rows = self._run_sql(
+            """
+            SELECT database_name
+            FROM duckdb_databases()
+            WHERE database_name NOT IN ('system', 'temp', ?)
+            """,
+            [main_catalog],
+        ).fetchall()
+        if rows:
+            names = ", ".join(row[0] for row in rows)
+            raise DuckDBSessionError(
+                "Publish mode does not support attached databases; "
+                f"found attached catalog(s): {names}"
+            )
+
+    def _table_visible(self, catalog: str, schema: str, table: str) -> bool:
+        attachment = next((a for a in self.attachments if a["name"] == catalog), None)
+        if attachment is None:
+            return True
+        allowed = attachment.get("tables")
+        if not allowed:
+            return True
+        return table in allowed
+
+    def _display_table_name(self, catalog: str, schema: str, table: str) -> str:
+        attachment = next((a for a in self.attachments if a["name"] == catalog), None)
+        if attachment is None:
+            if schema == "main":
+                return table
+            return f"{schema}.{table}"
+
+        db_type = attachment["type"]
+        if db_type == "POSTGRES":
+            if schema == "public":
+                return f"{catalog}.{table}"
+            return f"{catalog}.{schema}.{table}"
+        if db_type == "SQLITE":
+            if schema == "main":
+                return f"{catalog}.{table}"
+            return f"{catalog}.{schema}.{table}"
+        return f"{catalog}.{table}"
+
+    @staticmethod
+    def _stringify_value(value: Any) -> str:
+        if value is None:
+            return ""
+        if isinstance(value, bool):
+            return str(value).lower()
+        if isinstance(value, (int, float, Decimal)):
+            return str(value)
+        if isinstance(value, (datetime, date, time, timedelta)):
+            return str(value)
+        if isinstance(value, bytes):
+            return value.decode("utf-8", errors="replace")
+        if isinstance(value, (list, dict, tuple)):
+            return str(value)
+        return str(value)