---
title: Database Setup
description: Configure database connections in SQLsaber
---

import { Aside } from "@astrojs/starlight/components";

SQLsaber supports PostgreSQL, MySQL, SQLite, DuckDB, and CSV data sources. This guide covers all the ways to configure database connections.

### Supported Database Types

- **PostgreSQL** - Full support with SSL
- **MySQL** - Full support with SSL
- **SQLite** - Local database files
- **DuckDB** - Local DuckDB files or in-memory analytics
- **CSV** - Local CSV files

### Adding Database

```bash
saber db add my-database
```

This will prompt you for all necessary connection details.

### Connection Strings

SQLsaber supports direct connection strings for PostgreSQL and MySQL, plus file URIs for SQLite and DuckDB.

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

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

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

### Files

#### SQLite

```bash
# Use SQLite file directly
saber -d "./data/sales.db" "Show me total sales by month"

# Relative paths work too
saber -d "~/Documents/mydata.db" "Count all records"
```

#### DuckDB

```bash
# Query a DuckDB file
saber -d "./warehouse/data.duckdb" "Show the latest partition"

# Use an absolute path
saber -d "duckdb:///Users/me/analytics.duckdb" "Describe orders"
```

#### CSV

SQLsaber can also analyze CSV files directly.

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

<Aside type="note">
  For CSV files, first row should contain column headers. SQLsaber will infer
  data types automatically.
</Aside>

### Managing Connections

#### List All Connections

```bash
saber db list
```

#### Set Default Database

If you have multiple databases, set one as default:

```bash
saber db set-default my-database
```

<Aside type="note">
  By default, SQLsaber will set the first added connection as default.
</Aside>

#### Test Connections

Verify that a database connection works:

```bash
saber db test my-database
```

#### Remove Connections

```bash
saber db remove my-database
```

### Security

#### Read-only by Default

SQLsaber blocks all write operations (INSERT, UPDATE, DELETE, DDL) by default. Only SELECT queries are allowed unless you explicitly enable dangerous mode with `--allow-dangerous`.

Even in dangerous mode, destructive operations like DROP, TRUNCATE, and GRANT/REVOKE are always blocked.

#### Read-only Database Role

> **If you are using SQLsaber with a production database, we recommend setting up a read-only role for your database and using those credentials to setup connection in SQLsaber.**

SQLsaber uses AST-based validation (via sqlglot) to analyze every query before execution. This catches write operations in nested queries, CTEs, subqueries, and dialect-specific dangerous functions. However, no validation is fool-proof.

**The most secure approach is to create a read-only database role and use those credentials with SQLsaber.** This provides database-level enforcement that cannot be bypassed regardless of what queries are generated.

<Aside type="note">
  For development setups, this isn't required but is a good practice if you wish
  to ensure with absolute certainty that no data modifying queries are ever
  executed.
</Aside>

#### Password Storage

SQLsaber stores database passwords securely using your operating system's credentials store.

#### SSL Certificates

Store SSL certificates in a secure location and use absolute paths when configuring connections.

### Schema Introspection Filters

SQLsaber skips noisy system schemas for every supported database when it introspects metadata, and you can layer on your own exclusions during setup or later via `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:** `information_schema`, `pg_catalog`, `duckdb_catalog`

When you run `saber db add`, the interactive flow prompts for extra schemas to ignore (or pass `--exclude-schemas schema1,schema2` in non-interactive mode). You can revisit an existing connection at any time:

```bash
# 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 created from raw URLs or file paths, use environment variables to extend the default filters:

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

Both the `list_tables` and `introspect_schema` tools respect these filters.

### Troubleshooting

Always test new connections after adding them.

```bash
# Test the connection
saber db test my-database

# If connection fails, check the details
saber db list

# Update connection if needed
saber db remove my-database
saber db add my-database  # Start over with correct details
```

### Getting Help

Use the help commands for more information:

```bash
saber db --help
saber db add --help
```

### What's Next?

After setting up your database connections:

1. [Configure authentication](/guides/authentication) for AI providers
2. [Start querying your data](/guides/getting-started)
3. [Set up memory](/guides/memory) for better context
4. [Manage conversation threads](/guides/threads)
