Running Queries

SQLsaber offers multiple ways to query your database using natural language. This guide covers all the different query modes and their use cases.

Interactive Mode

Ideal for back and forth conversations about your data.

saber

Single Query Mode

Run a one-off query without entering interactive mode:

saber "How many orders were placed last week?"

Useful for:

Shell scripting
Quick checks
Automated reporting

Stdin Mode

Pipe queries from other commands or files:

# From echo
echo "Count all active customers from last week" | saber

# From file
cat query.txt | saber

# From other commands
curl -s https://api.example.com/query | saber

Useful for:

Shell scripting
Batch processing
Integration with other tools
Automation

Features

Slash Commands

Special commands in interactive mode:

/clear - Clear conversation history
/exit or /quit - Exit SQLsaber
/thinking on - Enable extended thinking mode
/thinking off - Disable extended thinking mode

> /clear
Conversation history cleared.

> /thinking on
✓ Thinking enabled

> /exit
Goodbye!

Table Autocomplete

Type @ followed by a table name to get autocomplete suggestions:

> Show me all records from @cus[TAB]
> Show me all records from @customers

Supports schema-aware completions:

> @pub[TAB] → @public.customers

Extended Thinking Mode

For complex queries requiring deeper reasoning, enable thinking mode to see step-by-step problem solving process.

In interactive mode:

> /thinking on
✓ Thinking enabled

> Analyze sales trends and forecast next quarter
💭 Thinking...
[dim reasoning process appears here]
[followed by final answer]

> /thinking off
✓ Thinking disabled

For single queries:

# Enable thinking for complex analysis
saber --thinking "Compare performance across regions with seasonal adjustments"

# Disable for simple queries
saber --no-thinking "How many users do we have?"

Default configuration:

Thinking is disabled by default. To change this, edit ~/.config/sqlsaber/model_config.json:

{
  "model": "anthropic:claude-sonnet-4-20250514",
  "thinking_enabled": true
}

Database Selection

Using Default

If you have a default database configured:

saber "Show me sales data"

Specifying Database by Name

Use a configured database connection:

saber -d prod-db "What's our revenue this month?"

Using Files Directly

Work with SQLite, DuckDB, or CSV files directly:

# SQLite file
saber -d "./data/sales.db" "Top selling products"

# DuckDB file
saber -d "./data/warehouse.duckdb" "Latest partitions"

# CSV file
saber -d "./customers.csv" "How many customers per state?"

Connection Strings

Use connection strings for temporary connections:

saber -d "postgresql://user:pass@host:5432/db" "Count all users"

Connection Issues

# Test the connection
saber db test my-database

# Check database list
saber db list

What’s Next?

Now that you know how to query effectively: