sqlitexplorer 1.0.0__py3-none-any.whl

sqlitexplorer/core.py

@@ -0,0 +1,700 @@
+"""SQLite access layer of sqlitexplorer.
+
+The CLI never touches :mod:`sqlite3` directly: it opens a database with
+:func:`open_database` and talks to the resulting :class:`Explorer`. Anything
+that should reach the user as a plain message is raised as
+:class:`ExplorerError`. Nothing in this module prints.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from itertools import islice
+from pathlib import Path
+from typing import NamedTuple
+
+__all__ = [
+    "Explorer",
+    "ExplorerError",
+    "Page",
+    "ReadOnlyError",
+    "ResultSet",
+    "RowStream",
+    "StatsReport",
+    "open_database",
+    "plan_tree",
+    "quote_identifier",
+    "split_statements",
+    "translate_error",
+]
+
+Parameters = Sequence[object] | Mapping[str, object]
+
+
+class ExplorerError(Exception):
+    """An error that should be shown to the user as a plain message."""
+
+
+class ReadOnlyError(ExplorerError):
+    """A write was attempted on a database that was opened read-only."""
+
+
+class Page(NamedTuple):
+    """A window of rows: 1-based page ``number`` of ``size`` rows each."""
+
+    number: int
+    size: int
+
+    @property
+    def start(self) -> int:
+        return (self.number - 1) * self.size
+
+
+@dataclass(frozen=True, slots=True)
+class ResultSet:
+    """Outcome of one SQL statement.
+
+    ``columns`` is empty for statements that do not return rows (DDL, DML).
+    ``rowcount`` is the number of rows changed by DML, or -1 when it does not
+    apply. When the rows are only one :class:`Page` of the result, ``total``
+    tells how many rows the statement produced in all.
+    """
+
+    columns: tuple[str, ...] = ()
+    rows: list[tuple] = field(default_factory=list)
+    rowcount: int = -1
+    total: int | None = None
+
+    @property
+    def returns_rows(self) -> bool:
+        """Whether the statement produced a result set, even an empty one."""
+        return bool(self.columns)
+
+
+@dataclass(slots=True)
+class RowStream:
+    """Rows of a statement as they come out of the cursor, without loading them all."""
+
+    columns: tuple[str, ...] = ()
+    rows: Iterator[tuple] = field(default_factory=lambda: iter(()))
+    rowcount: int = -1
+
+    @property
+    def returns_rows(self) -> bool:
+        return bool(self.columns)
+
+    def collect(self) -> ResultSet:
+        """Load every remaining row into a :class:`ResultSet`."""
+        return ResultSet(columns=self.columns, rows=list(self.rows), rowcount=self.rowcount)
+
+
+class StatsReport(NamedTuple):
+    """Per-column statistics, plus how many rows they were computed on."""
+
+    result: ResultSet
+    rows: int
+    sampled: bool
+
+
+def _rows_of(cursor: sqlite3.Cursor) -> Iterator[tuple]:
+    try:
+        yield from cursor
+    finally:
+        cursor.close()
+
+
+def _window(stream: RowStream, page: Page) -> ResultSet:
+    """Keep only *page* of *stream*, counting the rest without retaining it."""
+    skipped = sum(1 for _ in islice(stream.rows, page.start))
+    rows = list(islice(stream.rows, page.size))
+    rest = sum(1 for _ in stream.rows)
+    return ResultSet(
+        columns=stream.columns,
+        rows=rows,
+        rowcount=stream.rowcount,
+        total=skipped + len(rows) + rest,
+    )
+
+
+def quote_identifier(name: str) -> str:
+    """Quote *name* so it can be embedded in SQL as an identifier."""
+    return '"' + name.replace('"', '""') + '"'
+
+
+def split_statements(sql: str) -> list[str]:
+    """Split *sql* into complete statements.
+
+    Uses :func:`sqlite3.complete_statement`, so semicolons inside strings,
+    comments and ``CREATE TRIGGER ... END`` blocks do not split. Trailing text
+    without a semicolon is returned as a final statement.
+    """
+    statements: list[str] = []
+    buffer = ""
+    *parts, remainder = sql.split(";")
+    for part in parts:
+        buffer += part + ";"
+        if sqlite3.complete_statement(buffer):
+            if _has_content(buffer):
+                statements.append(buffer.strip())
+            buffer = ""
+    leftover = buffer + remainder
+    if _has_content(leftover):
+        statements.append(leftover.strip())
+    return statements
+
+
+def _has_content(text: str) -> bool:
+    return bool(text.strip().rstrip(";").strip())
+
+
+def plan_tree(result: ResultSet) -> ResultSet:
+    """Indent the ``detail`` column of an ``EXPLAIN QUERY PLAN`` result by depth."""
+    parents = {row[0]: row[1] for row in result.rows}
+
+    def depth(node: object) -> int:
+        level, seen = 0, set()
+        while node in parents and node not in seen and parents[node]:
+            seen.add(node)
+            node = parents[node]
+            level += 1
+        return level
+
+    rows = [(row[0], row[1], "  " * depth(row[0]) + str(row[3])) for row in result.rows]
+    return ResultSet(columns=("id", "parent", "detail"), rows=rows)
+
+
+def _database_uri(path: Path, *, write: bool) -> str:
+    # ``as_uri`` percent-encodes the characters that are special in URIs.
+    mode = "rw" if write else "ro"
+    return f"{path.resolve().as_uri()}?mode={mode}"
+
+
+def translate_error(error: sqlite3.Error, *, write: bool) -> ExplorerError:
+    """Turn a raw sqlite3 error into the ExplorerError shown to the user."""
+    message = str(error)
+    if not write and "readonly database" in message:
+        return ReadOnlyError(message)
+    return ExplorerError(message)
+
+
+@contextmanager
+def open_database(path: Path, *, write: bool = False) -> Iterator[Explorer]:
+    """Open the database at *path* and yield an :class:`Explorer` bound to it.
+
+    The file is opened read-only unless *write* is true, and it is never
+    created. In write mode the transaction is committed when the ``with``
+    block finishes normally and rolled back if it raises.
+    """
+    try:
+        connection = sqlite3.connect(_database_uri(path, write=write), uri=True)
+    except sqlite3.Error as error:
+        raise ExplorerError(f"cannot open {path}: {error}") from error
+    try:
+        yield Explorer(connection, write=write)
+        if write:
+            connection.commit()
+    except sqlite3.Error as error:
+        connection.rollback()
+        raise translate_error(error, write=write) from error
+    finally:
+        connection.close()
+
+
+class Explorer:
+    """Explorer-oriented queries on top of an open :class:`sqlite3.Connection`."""
+
+    def __init__(self, connection: sqlite3.Connection, *, write: bool = False) -> None:
+        self._connection = connection
+        self._write = write
+
+    # --- Statements -------------------------------------------------------
+
+    def execute(
+        self, sql: str, parameters: Parameters = (), *, page: Page | None = None
+    ) -> ResultSet:
+        """Run a single SQL statement and collect its outcome.
+
+        With *page*, only that window of rows is kept in memory; the rest of
+        the result is counted as it streams by and reported as ``total``.
+        """
+        stream = self.stream(sql, parameters)
+        if page is None or not stream.returns_rows:
+            return stream.collect()
+        return _window(stream, page)
+
+    def stream(self, sql: str, parameters: Parameters = ()) -> RowStream:
+        """Run a single SQL statement and return its rows lazily."""
+        cursor = self._connection.execute(sql, parameters)
+        if cursor.description is None:
+            rowcount = cursor.rowcount
+            cursor.close()
+            return RowStream(rowcount=rowcount)
+        columns = tuple(name for name, *_ in cursor.description)
+        return RowStream(columns=columns, rows=_rows_of(cursor), rowcount=cursor.rowcount)
+
+    def explain(self, sql: str, parameters: Parameters = ()) -> ResultSet:
+        """Return the query plan of *sql* as an indented tree."""
+        return plan_tree(self.execute(f"EXPLAIN QUERY PLAN {sql}", parameters))
+
+    def commit(self) -> None:
+        self._connection.commit()
+
+    def rollback(self) -> None:
+        self._connection.rollback()
+
+    def attach(self, alias: str, path: Path, *, write: bool | None = None) -> None:
+        """Attach the database at *path* under *alias*, read-only unless *write*."""
+        if write is None:
+            write = self._write
+        try:
+            self._connection.execute(
+                f"ATTACH DATABASE ? AS {quote_identifier(alias)}",
+                (_database_uri(path, write=write),),
+            )
+        except sqlite3.Error as error:
+            raise ExplorerError(f"cannot attach {path}: {error}") from error
+
+    # --- Catalogue --------------------------------------------------------
+
+    def names(
+        self, *, kinds: Sequence[str] = ("table", "view"), include_internal: bool = False
+    ) -> list[str]:
+        """Names of the schema objects of the given *kinds*, sorted."""
+        placeholders = ", ".join("?" for _ in kinds)
+        sql = f"SELECT name FROM sqlite_master WHERE type IN ({placeholders})"
+        if not include_internal:
+            sql += " AND name NOT LIKE 'sqlite_%'"
+        sql += " ORDER BY name"
+        return [row[0] for row in self.execute(sql, tuple(kinds)).rows]
+
+    def objects(self, *, include_internal: bool = False) -> list[tuple[str, str, str]]:
+        """``(type, name, sql)`` of every object with a CREATE statement, in creation order."""
+        sql = "SELECT type, name, sql FROM sqlite_master WHERE sql IS NOT NULL"
+        if not include_internal:
+            sql += " AND name NOT LIKE 'sqlite_%'"
+        # Creation order, like the sqlite3 shell: every object comes after
+        # the ones it depends on, so the output can be replayed as a script.
+        sql += " ORDER BY rowid"
+        return [(kind, name, statement) for kind, name, statement in self.execute(sql).rows]
+
+    def tables(self, *, include_internal: bool = False, count: bool = True) -> ResultSet:
+        """List tables and views, with their row counts unless *count* is false."""
+        sql = "SELECT type, name FROM sqlite_master WHERE type IN ('table', 'view')"
+        if not include_internal:
+            sql += " AND name NOT LIKE 'sqlite_%'"
+        sql += " ORDER BY type, name"
+        objects = self.execute(sql).rows
+        if not count:
+            return ResultSet(columns=("type", "name"), rows=[tuple(row) for row in objects])
+        rows = [(kind, name, self._count_rows(name)) for kind, name in objects]
+        return ResultSet(columns=("type", "name", "rows"), rows=rows)
+
+    def _count_rows(self, name: str) -> int | str:
+        try:
+            return self.execute(f"SELECT COUNT(*) FROM {quote_identifier(name)}").rows[0][0]
+        except sqlite3.Error:
+            # Typically a view whose underlying table no longer exists.
+            return "?"
+
+    def schema(self, name: str | None = None, *, include_internal: bool = False) -> list[str]:
+        """Return the CREATE statements of the database.
+
+        When *name* is given, only the table or view itself plus its indexes
+        and triggers are returned. Otherwise SQLite's internal objects
+        (``sqlite_*``) are skipped unless *include_internal* is true.
+        """
+        if name is None:
+            return [
+                statement for _, _, statement in self.objects(include_internal=include_internal)
+            ]
+        result = self.execute(
+            "SELECT sql FROM sqlite_master WHERE sql IS NOT NULL"
+            " AND (name = ? OR tbl_name = ?) ORDER BY rowid",
+            (name, name),
+        )
+        statements = [row[0] for row in result.rows]
+        if not statements:
+            raise ExplorerError(f"no such table or view: {name}")
+        return statements
+
+    def columns(self, table: str) -> ResultSet:
+        """Describe the columns of *table* as reported by ``PRAGMA table_info``."""
+        result = self.execute(f"PRAGMA table_info({quote_identifier(table)})")
+        if not result.rows:
+            raise ExplorerError(f"no such table or view: {table}")
+        return result
+
+    def column_names(self, table: str) -> list[str]:
+        return [row[1] for row in self.columns(table).rows]
+
+    def _resolve_column(self, table: str, name: str, known: Sequence[str]) -> str:
+        for column in known:
+            if column.casefold() == name.casefold():
+                return column
+        raise ExplorerError(f"no such column in {table}: {name}")
+
+    def indexes(self, table: str | None = None) -> ResultSet:
+        """Indexes of *table*, or of every table, with the columns they cover."""
+        tables = self._tables_or_one(table)
+        rows = []
+        for name in tables:
+            index_list = self.execute(f"PRAGMA index_list({quote_identifier(name)})").rows
+            for _seq, index, unique, origin, partial in index_list:
+                info = self.execute(f"PRAGMA index_info({quote_identifier(index)})").rows
+                covered = ", ".join("<expr>" if column is None else column for _, _, column in info)
+                rows.append((name, index, unique, origin, partial, covered))
+        return ResultSet(
+            columns=("table", "name", "unique", "origin", "partial", "columns"), rows=rows
+        )
+
+    def foreign_keys(self, table: str | None = None) -> ResultSet:
+        """Foreign keys declared by *table*, or by every table."""
+        tables = self._tables_or_one(table)
+        rows = []
+        for name in tables:
+            fks = self.execute(f"PRAGMA foreign_key_list({quote_identifier(name)})").rows
+            for fk_id, seq, referenced, source, target, on_update, on_delete, match in fks:
+                rows.append(
+                    (name, fk_id, seq, source, referenced, target, on_update, on_delete, match)
+                )
+        return ResultSet(
+            columns=(
+                "table",
+                "id",
+                "seq",
+                "from",
+                "references",
+                "to",
+                "on_update",
+                "on_delete",
+                "match",
+            ),
+            rows=rows,
+        )
+
+    def _tables_or_one(self, table: str | None) -> list[str]:
+        if table is None:
+            return self.names(kinds=("table",))
+        self.columns(table)  # fail early with a clear message
+        return [table]
+
+    def info(self, *, check: bool = False) -> ResultSet:
+        """Facts about the database file: size, pragmas and object counts."""
+        databases = self.execute("PRAGMA database_list").rows
+        path = next((file for _, name, file in databases if name == "main"), "")
+        try:
+            size: int | None = Path(path).stat().st_size if path else None
+        except OSError:
+            size = None
+        entries: list[tuple[str, object]] = [
+            ("path", path),
+            ("size", size),
+            ("sqlite_version", sqlite3.sqlite_version),
+        ]
+        pragmas = (
+            "page_size",
+            "page_count",
+            "freelist_count",
+            "journal_mode",
+            "encoding",
+            "user_version",
+            "application_id",
+        )
+        for pragma in pragmas:
+            entries.append((pragma, self.execute(f"PRAGMA {pragma}").rows[0][0]))
+        counts = dict(
+            self.execute(
+                "SELECT type, COUNT(*) FROM sqlite_master"
+                " WHERE name NOT LIKE 'sqlite_%' GROUP BY type"
+            ).rows
+        )
+        plurals = {"table": "tables", "view": "views", "index": "indexes", "trigger": "triggers"}
+        for kind, plural in plurals.items():
+            entries.append((plural, counts.get(kind, 0)))
+        if check:
+            problems = self.execute("PRAGMA integrity_check").rows
+            entries.append(("integrity_check", "; ".join(str(row[0]) for row in problems)))
+        return ResultSet(columns=("key", "value"), rows=entries)
+
+    # --- Data -------------------------------------------------------------
+
+    def _rows_sql(
+        self,
+        table: str,
+        *,
+        columns: Sequence[str] | None,
+        where: str | None,
+        order_by: str | None,
+        descending: bool,
+    ) -> tuple[str, str, str]:
+        """``(selection, source, order)`` pieces of a SELECT over *table*."""
+        selection = "*"
+        order_clause = ""
+        if columns or order_by:
+            known = self.column_names(table)
+            if columns:
+                selection = ", ".join(
+                    quote_identifier(self._resolve_column(table, name, known)) for name in columns
+                )
+            if order_by:
+                column = quote_identifier(self._resolve_column(table, order_by, known))
+                order_clause = f" ORDER BY {column}{' DESC' if descending else ''}"
+        source = f"FROM {quote_identifier(table)}"
+        if where:
+            source += f" WHERE ({where})"
+        return selection, source, order_clause
+
+    def rows(
+        self,
+        table: str,
+        *,
+        columns: Sequence[str] | None = None,
+        where: str | None = None,
+        order_by: str | None = None,
+        descending: bool = False,
+        limit: int | None = None,
+        offset: int = 0,
+        page: Page | None = None,
+    ) -> ResultSet:
+        """Return the rows of *table*, optionally filtered, ordered and windowed.
+
+        *where* is a raw SQL fragment; *columns* and *order_by* are validated
+        against the table's columns (case-insensitively). *limit* and *offset*
+        select the rows; *page* then picks one page of them in SQL, so only
+        that page is ever loaded, and ``total`` reports how many there were.
+        """
+        selection, source, order = self._rows_sql(
+            table, columns=columns, where=where, order_by=order_by, descending=descending
+        )
+        query = f"SELECT {selection} {source}{order} LIMIT ? OFFSET ?"
+        if page is None:
+            return self.execute(query, (-1 if limit is None else limit, offset))
+        matching = self.execute(f"SELECT COUNT(*) {source}").rows[0][0]
+        total = max(0, matching - offset)
+        if limit is not None:
+            total = min(total, limit)
+        size = max(0, min(page.size, total - page.start))
+        window = self.execute(query, (size, offset + page.start))
+        return ResultSet(
+            columns=window.columns, rows=window.rows, rowcount=window.rowcount, total=total
+        )
+
+    def stream_rows(
+        self,
+        table: str,
+        *,
+        columns: Sequence[str] | None = None,
+        where: str | None = None,
+        order_by: str | None = None,
+        descending: bool = False,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> RowStream:
+        """Like :meth:`rows`, but the rows come lazily from the cursor."""
+        selection, source, order = self._rows_sql(
+            table, columns=columns, where=where, order_by=order_by, descending=descending
+        )
+        query = f"SELECT {selection} {source}{order} LIMIT ? OFFSET ?"
+        return self.stream(query, (-1 if limit is None else limit, offset))
+
+    def stats(
+        self,
+        table: str,
+        *,
+        top: int = 3,
+        columns: Sequence[str] | None = None,
+        sample: int | None = None,
+    ) -> StatsReport:
+        """Per-column summary of *table*: nulls, distinct values, min, max, top values.
+
+        Nulls, distinct values, minimum and maximum of every column come from a
+        single pass over the table; the *top* most frequent values need one
+        ``GROUP BY`` per column, so ``top=0`` is much cheaper on big tables.
+        With *sample*, everything is computed on a random sample of that many
+        rows copied to a temporary table.
+        """
+        info = self.columns(table).rows
+        known = [row[1] for row in info]
+        declared = {row[1]: row[2] for row in info}
+        if columns is None:
+            selected = known
+        else:
+            selected = [self._resolve_column(table, name, known) for name in columns]
+        if sample is None:
+            return self._collect_stats(quote_identifier(table), selected, declared, top, False)
+        source = self._sample(table, selected, sample)
+        try:
+            return self._collect_stats(source, selected, declared, top, True)
+        finally:
+            self._connection.execute(f"DROP TABLE IF EXISTS {source}")
+
+    def _sample(self, table: str, columns: Sequence[str], size: int) -> str:
+        """Copy a random sample of *table* into a temporary table; return its name."""
+        selection = ", ".join(quote_identifier(name) for name in columns)
+        self._connection.execute(f"DROP TABLE IF EXISTS {_SAMPLE_TABLE}")
+        self._connection.execute(
+            f"CREATE TEMP TABLE {_SAMPLE_NAME} AS SELECT {selection}"
+            f" FROM {quote_identifier(table)} ORDER BY random() LIMIT ?",
+            (size,),
+        )
+        return _SAMPLE_TABLE
+
+    def _collect_stats(
+        self,
+        source: str,
+        columns: Sequence[str],
+        declared: Mapping[str, str],
+        top: int,
+        sampled: bool,
+    ) -> StatsReport:
+        rows = []
+        examined = 0
+        for start in range(0, len(columns), _STATS_CHUNK):
+            chunk = columns[start : start + _STATS_CHUNK]
+            expressions = ["COUNT(*)"]
+            for name in chunk:
+                q_col = quote_identifier(name)
+                expressions += [
+                    f"COUNT({q_col})",
+                    f"COUNT(DISTINCT {q_col})",
+                    f"MIN({q_col})",
+                    f"MAX({q_col})",
+                    f"typeof(MIN({q_col}))",
+                ]
+            values = self.execute(f"SELECT {', '.join(expressions)} FROM {source}").rows[0]
+            examined = values[0]
+            for index, name in enumerate(chunk):
+                filled, distinct, minimum, maximum, min_type = values[1 + index * 5 : 6 + index * 5]
+                rows.append(
+                    (
+                        name,
+                        declared.get(name) or min_type,
+                        examined - filled,
+                        distinct,
+                        minimum,
+                        maximum,
+                        self._top_values(source, name, top),
+                    )
+                )
+        if not columns:
+            examined = self.execute(f"SELECT COUNT(*) FROM {source}").rows[0][0]
+        return StatsReport(ResultSet(columns=_STATS_COLUMNS, rows=rows), examined, sampled)
+
+    def _top_values(self, source: str, column: str, top: int) -> str:
+        if top <= 0:
+            return ""
+        q_col = quote_identifier(column)
+        frequent = self.execute(
+            f"SELECT quote({q_col}), COUNT(*) AS n FROM {source}"
+            f" WHERE {q_col} IS NOT NULL GROUP BY {q_col} ORDER BY n DESC, 1 LIMIT ?",
+            (top,),
+        ).rows
+        return ", ".join(f"{value} ({count})" for value, count in frequent)
+
+    def search(
+        self, text: str, *, tables: Sequence[str] | None = None, limit: int | None = None
+    ) -> ResultSet:
+        """Find *text* (case-insensitive substring) in every non-BLOB column.
+
+        Each table is scanned once, whatever its number of columns; one row is
+        reported per matching column.
+        """
+        if not text:
+            raise ExplorerError("nothing to search for")
+        escaped = text.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        pattern = f"%{escaped}%"
+        if tables is None:
+            tables = self.names(kinds=("table",))
+        remaining = limit
+        rows = []
+        for table in tables:
+            if remaining is not None and remaining <= 0:
+                break
+            columns = self.column_names(table)
+            for record in self._scan_table(table, columns, pattern, remaining):
+                rowid, values, matched = (
+                    record[0],
+                    record[1:][: len(columns)],
+                    record[1 + len(columns) :],
+                )
+                for column, value, hit in zip(columns, values, matched, strict=True):
+                    if not hit:
+                        continue
+                    rows.append((table, column, rowid, value))
+                    if remaining is not None:
+                        remaining -= 1
+                        if remaining <= 0:
+                            break
+                if remaining is not None and remaining <= 0:
+                    break
+        return ResultSet(columns=_SEARCH_COLUMNS, rows=rows)
+
+    def _scan_table(
+        self, table: str, columns: Sequence[str], pattern: str, limit: int | None
+    ) -> list[tuple]:
+        """One pass over *table* returning ``rowid, values..., matched flags...`` per hit row."""
+        quoted = [quote_identifier(column) for column in columns]
+        flags = [f'"__match_{index}"' for index in range(len(columns))]
+        tests = ", ".join(
+            f"(typeof({column}) <> 'blob' AND CAST({column} AS TEXT) LIKE ? ESCAPE '\\') AS {flag}"
+            for column, flag in zip(quoted, flags, strict=True)
+        )
+        selection = ", ".join(quoted)
+        parameters = (*[pattern] * len(columns), -1 if limit is None else limit)
+
+        def sql(rowid: str) -> str:
+            return (
+                f'SELECT * FROM (SELECT {rowid} AS "__rowid", {selection}, {tests}'
+                f" FROM {quote_identifier(table)}) WHERE {' OR '.join(flags)} LIMIT ?"
+            )
+
+        try:
+            return self.execute(sql("rowid"), parameters).rows
+        except sqlite3.OperationalError as error:
+            if "no such column: rowid" not in str(error):
+                raise
+            # WITHOUT ROWID tables and views have no rowid to report.
+            return self.execute(sql("NULL"), parameters).rows
+
+    def dump(self) -> Iterator[str]:
+        """The database as replayable SQL, one statement per item."""
+        return self._connection.iterdump()
+
+    def import_rows(
+        self,
+        table: str,
+        columns: Sequence[tuple[str, str]],
+        rows: Iterable[Sequence[object]],
+        *,
+        create: bool = True,
+    ) -> int:
+        """Insert *rows* into *table*, creating it from *columns* (``(name, type)``) if needed."""
+        q_table = quote_identifier(table)
+        exists = self.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (table,)
+        ).rows
+        if not exists:
+            if not create:
+                raise ExplorerError(f"no such table: {table}")
+            definition = ", ".join(f"{quote_identifier(name)} {kind}" for name, kind in columns)
+            self._connection.execute(f"CREATE TABLE {q_table} ({definition})")
+        names = ", ".join(quote_identifier(name) for name, _ in columns)
+        placeholders = ", ".join("?" for _ in columns)
+        cursor = self._connection.executemany(
+            f"INSERT INTO {q_table} ({names}) VALUES ({placeholders})", rows
+        )
+        try:
+            return cursor.rowcount
+        finally:
+            cursor.close()
+
+
+_SEARCH_COLUMNS = ("table", "column", "rowid", "value")
+_STATS_COLUMNS = ("column", "type", "nulls", "distinct", "min", "max", "top")
+# Columns per aggregate query: five expressions each, well below SQLITE_MAX_COLUMN.
+_STATS_CHUNK = 100
+_SAMPLE_NAME = '"sqlitexplorer_sample"'
+_SAMPLE_TABLE = f"temp.{_SAMPLE_NAME}"