Overview

package wittgenstein_sql_runner

wittgenstein-sql-runner — SQL execution against PostgreSQL, returning structured result envelopes.

Classes

• ExecutionResult — Result envelope returned by SQLRunner.execute().

• SQLRunner — Executes SQL queries against a PostgreSQL database.

Functions

• discover_db_tables — Return the set of base table names in the given schema.

wittgenstein_sql_runner.ExecutionResult

mkapi_definition_mkapi class ExecutionResult()

Result envelope returned by SQLRunner.execute().

dataframe contains the full result; data is a preview of the first 10 rows as a list of dicts (for serialization-friendly consumption by agents).

Methods

• success

• empty

• failure

wittgenstein_sql_runner.ExecutionResult.success

mkapi_definition_mkapi classmethod ExecutionResult.success(df: pd.DataFrame) → ExecutionResult

wittgenstein_sql_runner.ExecutionResult.empty

mkapi_definition_mkapi classmethod ExecutionResult.empty() → ExecutionResult

wittgenstein_sql_runner.ExecutionResult.failure

mkapi_definition_mkapi classmethod ExecutionResult.failure(error: str) → ExecutionResult

wittgenstein_sql_runner.SQLRunner

mkapi_definition_mkapi class SQLRunner(pg_dsn: str, statement_timeout_ms: int | None = None, max_rows: int | None = None, read_only: bool = False)

Executes SQL queries against a PostgreSQL database.

Returns an ExecutionResult with the full DataFrame, a row preview, and a status string — suitable for direct consumption by agent tools.

One instance per target database is typical. Thread-safe (each call opens and closes its own connection).

Three opt-in guardrails are available, all OFF by default so existing callers see no behavior change: statement_timeout_ms, max_rows, and read_only. See __init__ for details.

Parameters

• pg_dsn : str — psycopg2-compatible DSN, e.g. 'postgresql://user:pass@host:port/dbname'

• statement_timeout_ms : int | None — opt-in. If set, aborts any query on this connection that runs longer than this many milliseconds (via SET statement_timeout) instead of hanging forever. None (default) leaves PostgreSQL's own timeout in effect.

• max_rows : int | None — opt-in. If set, fetches at most this many rows from the database via cursor.fetchmany() instead of pulling the full result set into memory. None (default) preserves the previous behavior of fetching everything.

• read_only : bool — opt-in. If True, puts the connection into a read-only transaction (conn.set_session(readonly=True)) before running the query, so PostgreSQL itself rejects write statements regardless of the SQL text. False (default) preserves the previous read-write behavior.

Methods

• execute — Run sql and return the result wrapped in an ExecutionResult.

wittgenstein_sql_runner.SQLRunner.execute

mkapi_definition_mkapi method SQLRunner.execute(sql: str) → ExecutionResult

Run sql and return the result wrapped in an ExecutionResult.

Parameters

• sql : str — Any read SQL statement (SELECT / WITH / …). Write statements are not prevented here unless read_only=True was passed to this runner — callers are otherwise responsible for access control.

Returns

• ExecutionResult — ExecutionResult with status='success' and the DataFrame, or status='error' with the exception message. Guardrail failures (a fired statement_timeout_ms, a read_only violation) are captured here too — never raised to the caller.

wittgenstein_sql_runner.discover_db_tables

mkapi_definition_mkapi discover_db_tables(pg_dsn: str, schema: str = 'public') → set[str]

Return the set of base table names in the given schema.

Queries information_schema.tables with table_type='BASE TABLE' to exclude views and materialized views.

Parameters

• pg_dsn : str — psycopg2-compatible DSN, e.g. 'postgresql://user:pass@host:port/dbname'

• schema : str — PostgreSQL schema to inspect (default 'public').

Returns

• set[str] — Set of table name strings.