Multiple databases

Connect one SQLsaber session to more than one database. The agent picks a database for each step, runs those queries separately, and combines the answers.

Note

SQLsaber does not run cross-database JOINs. It queries each database on its own and combines the results in the reply.

Start a multi-database session

Repeat -d or --database. Each value can be a saved connection name, a connection string, or a file path. Mix those forms.

# Two saved connections
saber -d sales -d analytics "Compare last month's revenue to web sessions"

# Mix a saved name with a connection string
saber -d sales -d "postgresql://user:pass@host:5432/events" "..."

# Interactive mode across several databases
saber -d sales -d analytics -d inventory

Single-query mode and interactive mode both work. In interactive mode the footer lists every connected database:

DBs: sales, analytics, inventory | Model: ... | ...

Caution

Each connected database must resolve to a unique name. Connecting two databases that share a name raises an error. The name is the saved connection name, or a name derived from the database or file for ad-hoc strings and paths.

CSV and Parquet files are different

Passing several CSV or Parquet files does not create a multi-database session. SQLsaber loads every file into one in-memory DuckDB database, with one table per file, so you can join across them:

saber -d users.csv -d orders.csv "Join users and orders"
saber -d users.csv -d orders.parquet "Revenue by user"
saber -d users.parquet -d orders.parquet "Join users and orders"

If the repeated targets include another database type or a saved connection, each target resolves on its own into a multi-database session.

Describe connections

When several databases are connected, the agent has to choose which one holds the data. Attach a short description to each connection. Descriptions are shown to the agent, and by the list_dbs tool. They are otherwise optional.

saber db add sales \
  --description "Production Postgres: orders, customers, revenue"

saber db add analytics \
  --description "ClickHouse warehouse: web sessions, events, funnels"

Add a description to any connection. See Database setup for saber db add.

Tip

Distinct descriptions help the agent route a question. Name the kind of data each connection holds: tables, domains, or environments.

How the agent routes queries

When more than one database is connected:

• SQL and knowledge tools require a db_name argument. The agent must choose a connected database for each list_tables, introspect_schema, execute_sql, and knowledge-base call.
• A list_dbs tool lists every connected database with its name, dialect, and description.
• Knowledge entries stay scoped per database. Each connection contributes its own context.

In a single-database session none of this is visible. Tool schemas have no db_name argument, and there is no list_dbs tool.

Resume a multi-database thread

Conversation threads created in a multi-database session record every connected database. When you resume that thread, SQLsaber reconnects to the same set:

saber threads resume a1b2c3d4

Note

Automatic resume works only when every database on the thread is a saved connection (added with saber db add). If a thread used a connection string or file path, resume it with explicit -d flags:

saber threads resume a1b2c3d4 -d sales -d "postgresql://user:pass@host:5432/events"

Use the Python SDK

Pass a list of targets in SQLSaberOptions. Read names from saber.info.database_names when you need metadata only:

import asyncio

from sqlsaber import SQLSaber, SQLSaberOptions


async def main() -> None:
    options = SQLSaberOptions(
        database=["sales", "postgresql://user:pass@host:5432/events"],
    )

    async with SQLSaber(options=options) as saber:
        print(saber.info.database_names)  # ("sales", "events")
        print(saber.db_names)             # compatibility property
        print(saber.connections)          # compatibility property


asyncio.run(main())

See Configuration for the full options list.

Next steps

• Database setup to register and describe connections
• Knowledge base to give each database extra context
• Conversation threads to resume a multi-database session