Database setup

Connect SQLsaber to a database or a local file, then test the connection.

SQLsaber works with PostgreSQL, MySQL, SQLite, DuckDB, CSV, and Parquet. PostgreSQL and MySQL support SSL. DuckDB can open a file or run in memory. SQLsaber queries Parquet through DuckDB.

Add a saved connection

saber db add my-database

SQLsaber prompts for the connection details.

For scripts and coding agents, pass every required value and disable prompts:

# Local database
saber db add local --type sqlite --database ./local.db --no-interactive

# Server database. Keep the password out of argv and shell history.
printf '%s' "$DB_PASSWORD" | saber db add analytics --no-interactive \
  --host db.example.com --database analytics --username agent --password-stdin

If you will connect several databases in one session, add a short description so the agent can tell them apart:

saber db add my-database --description "Production Postgres: orders and revenue"

See Multiple databases for that session type.

Connect with a string

Pass a PostgreSQL or MySQL URL, or a SQLite or DuckDB file URI:

saber -d "postgresql://user:password@localhost:5432/database"

saber -d "mysql://user:password@localhost:3306/database"

saber -d "duckdb:///path/to/data.duckdb"

Query a local file

SQLite

saber -d "./data/sales.db" "Show me total sales by month"

saber -d "~/Documents/mydata.db" "Count all records"

DuckDB

saber -d "./warehouse/data.duckdb" "Show the latest partition"

saber -d "duckdb:///Users/me/analytics.duckdb" "Describe orders"

CSV

saber -d "./customers.csv" "How many customers are from each state?"

Parquet

Query a local .parquet file, or use a parquet:/// URL:

saber -d "./orders.parquet" "What is total revenue?"
saber -d "parquet:///orders.parquet" "Describe the columns"
saber -d "./customers.csv" -d "./orders.parquet" "Revenue by customer"

DuckDB reads column names and types from the Parquet schema. Each file becomes a table named after its filename without the extension. For example, orders.parquet is the table orders. Repeated CSV and Parquet inputs share one database, so SQL joins work across them.

SQLsaber loads each file into memory on every query, then disables further file access for read-only execution. That is not a lazy scan of a large Parquet file. Give the process enough memory for the loaded data. Use explicit local files. Remote URLs and partition-directory inputs are not supported.

Manage saved connections

List connections:

saber db list

If you have several connections, set one as the default:

saber db set-default my-database

Test a connection:

saber db test my-database

Remove a connection:

saber db remove my-database

# Non-interactive deletion
saber db remove my-database --yes

Connect several databases at once

Repeat -d to attach more than one database to a session. The agent queries each database separately and combines the answers:

saber -d sales -d analytics "Compare revenue to web sessions"

See Multiple databases.

Keep queries read-only

SQLsaber blocks INSERT, UPDATE, DELETE, and DDL by default. Only SELECT runs unless you pass --allow-dangerous.

Even with --allow-dangerous, SQLsaber still blocks destructive statements such as DROP and TRUNCATE, and admin statements such as GRANT, REVOKE, and CREATE FUNCTION, CREATE USER, CREATE ROLE, or CREATE DATABASE.

If you connect a production database, create a read-only database role and use those credentials in SQLsaber.

SQLsaber uses AST validation through sqlglot before it runs a query. That catches writes in nested queries, CTEs, subqueries, and some dialect-specific functions. Validation can miss a case. A read-only role enforces the limit in the database.

SQLsaber stores database passwords in your operating system credentials store.

Store SSL certificates in a secure location. Use absolute paths when you configure a connection. SSL modes are listed in Commands.

Skip schemas during introspection

SQLsaber skips noisy system schemas for every supported database. Add more exclusions when you add a connection, or later with saber db exclude.

Default exclusions:

PostgreSQL: pg_catalog, information_schema, _timescaledb_internal, _timescaledb_cache, _timescaledb_config, _timescaledb_catalog
MySQL: information_schema, performance_schema, mysql, sys
DuckDB, CSV, and Parquet: information_schema, pg_catalog, duckdb_catalog

When you run saber db add, the interactive flow asks for extra schemas to ignore. In non-interactive mode, pass --exclude-schemas schema1,schema2. Change an existing connection at any time:

# Replace the exclusion list interactively
saber db exclude my-database

# Append specific schemas
saber db exclude my-database --add reporting_temp,rollups

For ad-hoc connections from URLs or file paths, extend the defaults with environment variables:

export SQLSABER_PG_EXCLUDE_SCHEMAS="schema1,schema2"
export SQLSABER_MYSQL_EXCLUDE_SCHEMAS="temp_db,staging"
export SQLSABER_DUCKDB_EXCLUDE_SCHEMAS="internal_schema"

Both list_tables and introspect_schema apply these filters.

Fix a failed connection

saber db test my-database

saber db list

saber db remove my-database
saber db add my-database

See saber db --help and saber db add --help, or Commands.