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
/handoff <goal> - Start a fresh thread with context from current conversation

> /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. You can configure different thinking levels to balance cost vs quality.

Thinking Levels:

Level	Use Case	Description
`off`	Disable	No extended thinking
`minimal`	Quick responses	Minimal reasoning overhead
`low`	Light reasoning	Faster, cheaper
`medium`	Balanced (default)	Good balance of cost and quality
`high`	Deep reasoning	More thorough analysis
`maximum`	Complex problems	Highest reasoning depth, highest cost

In interactive mode:

> /thinking
Thinking: disabled

> /thinking medium
✓ Thinking: enabled (medium)

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

> /thinking high
✓ Thinking: enabled (high)

> /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?"

Configuring thinking level:

Use saber models set to configure thinking level after selecting a model:

saber models set
# After selecting model, you'll be prompted:
# ? Configure thinking mode? [Y/n]: y
# ? Select thinking level: medium (Recommended)

Check current settings with:

saber models current
# Current model: anthropic:claude-sonnet-4-5-20250929
# Thinking: enabled (medium)

Provider-specific mapping:

Each thinking level maps to provider-specific configurations:

Anthropic: budget_tokens (1,024 → 100,000)
OpenAI: reasoning_effort (minimal → xhigh)
Google: thinking_level (MINIMAL → HIGH)
Groq: Binary (any non-off level enables reasoning)

Handoff

When your conversation gets long or you want to start fresh while preserving context, use the /handoff command:

> /handoff optimize the monthly revenue query for better performance

The handoff:

Summarizes your conversation (tables discovered, SQL queries run, key findings)
Presents an editable draft prompt
Ends the current thread and starts fresh with your edited prompt

Dangerous Mode

By default, SQLsaber only allows read-only SELECT queries. To enable write operations, use the --allow-dangerous flag:

# Single query with write access
saber --allow-dangerous "Insert a new user with email test@example.com"

# Interactive mode with write access
saber --allow-dangerous

What’s allowed in dangerous mode:

DML: INSERT, UPDATE, DELETE (UPDATE/DELETE require WHERE)
Restricted DDL:
- CREATE TABLE
- CREATE VIEW
- CREATE INDEX
- ALTER TABLE

What’s always blocked (even in dangerous mode):

DROP, TRUNCATE (destructive operations)
Transaction control (BEGIN, COMMIT, ROLLBACK)
Security operations (GRANT, REVOKE)
Database operations (ATTACH, DETACH)
Admin/executable schema objects (e.g., CREATE FUNCTION/PROCEDURE/TRIGGER, CREATE USER/ROLE/DATABASE)

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: