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).
`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).

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 db_names and connections for the connected databases:

saber = SQLSaber(options)
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.