Configuration

Every SQLSaber session is configured through a single SQLSaberOptions dataclass. Construct it with keyword arguments and pass it to SQLSaber(options=...).

from sqlsaber import SQLSaberOptions

options = SQLSaberOptions(
    database="postgresql://user:pass@localhost:5432/analytics",
    model_name="anthropic:claude-sonnet-4-5-20250929",
    thinking_level="medium",
)

Options reference

Field	Type	Default	Description
`database`	`str \| list[str] \| tuple[str, ...] \| None`	`None`	Connection string, file path, configured DB name, a list of CSV paths, or a list of targets for a multi-database session.
`model_name`	`str \| None`	`None`	Model in `"provider:model"` form. Falls back to your configured/default model.
`api_key`	`str \| None`	`None`	API key for the model’s provider. Usually unnecessary — see Credentials.
`thinking_enabled`	`bool \| None`	`None`	Toggle extended thinking on supported reasoning models.
`thinking_level`	`ThinkingLevel \| str \| None`	`None`	`"minimal" \| "low" \| "medium" \| "high" \| "maximum"`. Setting a level enables thinking.
`system_prompt`	`str \| Path \| None`	`None`	Custom system prompt text, or a path to a file containing it.
`settings`	`Config \| None`	`None`	Inject a `Config` (e.g. `Config.in_memory(...)`). Defaults to file-backed `Config.default()`.
`knowledge_manager`	`KnowledgeManager \| None`	`None`	Inject your own knowledge base (see Advanced).
`thread_manager`	`ThreadManager \| None`	`None`	Persist conversation history across runs (see Advanced).
`extra_capabilities`	`Sequence[AbstractCapability[Any]]`	`()`	Add pydantic-ai capabilities to the managed agent (see Capabilities).
`artifact_store`	`ArtifactStore \| None`	`None`	Application-owned publication and retrieval for artifacts such as analysis notebooks and plots.
`artifact_failure_mode`	`"required" \| "best_effort"`	`"required"`	Fail the tool or retain its answer when artifact publication fails.
`query_result_store`	`QueryResultStore \| None`	`None`	Store for complete SQL row results. Defaults to a session-owned in-memory store. Inject application storage for durable or tenant-scoped retrieval.
`workspace_input_resolver`	`WorkspaceInputResolver \| None`	`None`	Application-owned resolver for opaque, authorized inputs to the managed notebook analyst.
`tool_overrides`	`Mapping[str, ModelOverides] \| None`	`None`	Per-tool model/API-key overrides (see Advanced).
`allow_dangerous`	`bool`	`False`	Allow write operations and a restricted subset of DDL (see Advanced).

Artifact storage

Embedded SQLsaber does not persist artifacts unless artifact_store is injected. The injected store is application-owned and is never closed or garbage-collected by SQLsaber. The CLI explicitly uses FilesystemArtifactStore under its private user data directory.

Cloud stores should authorize get() from the current identity in ArtifactContext.metadata, keep objects private, and return ArtifactUnavailable for both missing and unauthorized IDs. Stable descriptor URIs are locators; SQLsaber retrieves bytes through the store rather than dereferencing those URIs.

Query result storage

Every successful row-returning query writes its complete canonical JSON payload to query_result_store. The model and message history receive only a stable 12 KiB projection. An injected store is application-owned and SQLsaber does not close it. The SDK default is in-memory; the CLI explicitly uses private filesystem storage. A storage failure makes that row-returning tool call fail rather than silently claiming complete data is available.

For web applications, implement QueryResultStore.put/get over a private database or object store. Authorize get from current identity in QueryResultContext.metadata; do not authorize solely from possession of a result ID, filename, or historical conversation metadata.

Managed notebook inputs

When sqlsaber-notebook is installed, workspace_input_resolver lets a host application make authorized files available to analyze_data without exposing filesystem paths, URLs, bucket names, object keys, or raw bytes to the main model. See Analyzing application-owned inputs for the resolver contract and trust boundary.

Without a resolver, SQLsaber preserves the original analyze_data(goal, files=None) schema: attachment_refs is not advertised to the model and SQL result selection is unchanged.

Choosing a database

The database option accepts the same targets as the CLI’s -d flag.

Connection strings

SQLSaberOptions(database="postgresql://user:pass@host:5432/db")
SQLSaberOptions(database="mysql://user:pass@host:3306/db")
SQLSaberOptions(database="sqlite:///path/to/local.db")
SQLSaberOptions(database="duckdb:///path/to/warehouse.duckdb")

File paths

Point directly at a SQLite, DuckDB, or CSV file:

SQLSaberOptions(database="./data/sales.db")
SQLSaberOptions(database="./customers.csv")

Multiple CSV files

Pass a list (or tuple) of CSV paths to query across them together. All CSVs are merged into a single in-memory database with one table per file:

SQLSaberOptions(database=["users.csv", "orders.csv"])

Multiple databases

Pass a list of non-CSV targets (configured names, connection strings, or file paths) to connect to several databases in one session. The agent queries each one separately and combines the results:

SQLSaberOptions(database=["sales", "postgresql://user:pass@host:5432/events"])

The resulting session exposes database metadata through saber.info:

from sqlsaber import SQLSaber

async with SQLSaber(options=options) as saber:
    saber.info.database_names  # ("sales", "events")

The compatibility properties saber.db_names and saber.connections remain available for callers that need the managed names or connection objects:

async with SQLSaber(options=options) as saber:
    saber.db_names     # ["sales", "events"]
    saber.connections  # {name: connection, ...}

A configured database

If you’ve already registered a connection with the CLI (saber db add), refer to it by name:

SQLSaberOptions(database="prod-db")

See the Database Setup guide for details on connection strings and registering databases.