SQLBook User Guide

🔌

Database Connections

SQLBook connects directly from your machine to your database — nothing goes through any server. Open the Connections panel using the plug icon in the top navigation bar.

Important: Connections do not reconnect automatically when you start SQLBook. Each time you open the app, go to the Connections panel and click Reconnect on the connection you want to use before running any queries. This is by design — it keeps things fast and avoids unwanted background connections.

Connection Indicators on Cells

Every query cell shows a connection selector. The state of each connection is shown as a circle icon:

Filled / bold circle — connected and ready to use
Empty / hollow circle — not connected, click Reconnect first

If no connections appear at all, go to the Connections panel and add one first.

Adding a Connection — Step by Step

Click the plug icon (Connections) in the top bar.
Click + New Connection.
Select your Database Type from the dropdown.
Choose a Connection Mode — either Add Specific Details (fill individual fields) or Full Connection String (paste one URL).
Fill in the fields for your database type (see below), then click Test Connection to verify.
Click Save. Your credentials are encrypted and stored only on your machine.

🐬 MySQL

Field	Description	Default
Host	Database server hostname or IP address	localhost
Port	MySQL port	3306
Username	MySQL user account	root
Password	User password — stored encrypted	—
Database	Name of the database to connect to	—
Additional Parameters	Extra URL query params e.g. `ssl=true&charset=utf8mb4`	—

Full connection string format: mysql://user:password@host:3306/database

🐘 PostgreSQL

Field	Description	Default
Host	Database server hostname or IP address	localhost
Port	PostgreSQL port	5432
Username	PostgreSQL user account	postgres
Password	User password — stored encrypted	—
Database	Name of the database	postgres
Schema	Optional schema name	public
Additional Parameters	e.g. `sslmode=require&connect_timeout=10`	—

Full connection string format: postgresql://user:password@host:5432/database

🗄 SQL Server (MSSQL)

Field	Description	Default
Authentication Type	SQL Server Auth (username + password) or Windows Auth (uses your Windows login)	SQL Server Auth
Username / Password	Only shown when using SQL Server Auth	sa / —
Server	Server address. Accepts: `localhost`, `localhost,1433`	localhost
Database	Name of the database	master
Trust Server Certificate	Enable for local/dev installs. Disable only if you have a valid SSL certificate.	Yes (local/dev)

Fresh SQL Server Express install? TCP/IP is disabled by default. Open SQL Server Configuration Manager → SQL Server Network Configuration → Protocols for SQLEXPRESS, enable TCP/IP, set a static port of 1433 under IP Addresses → IPAll, then restart the SQL Server service. Then connect using localhost with Windows Auth and Trust Server Certificate enabled.

Full connection string format: Server=localhost,1433;Database=master;User Id=sa;Password=yourpassword;TrustServerCertificate=true

🔶 OracleDB

Field	Description	Default
Host	Oracle server hostname or IP	localhost
Port	Oracle listener port	1521
Username	Oracle user account	system
Password	User password — stored encrypted	—
Service Name / SID	Oracle service name or SID e.g. `ORCL` or `XE`	ORCL

OracleDB requires Transaction Mode to always be enabled on cells connected to Oracle. Oracle is transaction-driven by default — see the Transaction Mode section below.

📝

Working with Cells

SQLBook is organised as a notebook — a sequence of cells you work through from top to bottom. Each cell is independent but shares the same connection pool.

Cell Types

Every cell has a type selector. Click the type label on the cell to change it:

Query — Write and execute SQL. This is the default type. A query cell shows a code editor, connection selector, run button, and results area.
Note — A plain text area for writing notes, documentation, or context about the surrounding queries. Does not execute anything.
Heading — A large text heading to organise and label sections of your notebook, making long notebooks easier to navigate.

Moving Cells

The cell index number is displayed on the far left of every cell (e.g. Cell 1, Cell 2…). You can change a cell's position by:

Click on the cell index number to make it editable.
Type the position number you want the cell to move to.
Press Enter — the cell will jump to that position immediately.

Tip: Hover over the cell index box to see the tooltip reminder: "Cell Index — change the index and press Enter to move to new position."

Running Cells

Click the ▶ Run button on a query cell, or press Shift + Enter inside the editor.
If the cell is the last cell in the notebook, pressing Shift+Enter will run it and automatically create a new empty cell below.
If the cell is in the middle of the notebook, pressing Shift+Enter will run it and keep focus on the current cell — it will not jump to the next one.

Selecting a Connection

Each query cell has a connection dropdown. Select the connection you want this cell to use. A new cell automatically inherits the connection of the last executed cell so you don't have to re-select it every time.

Remember: connections show a filled circle when connected and a hollow circle when disconnected. If a connection shows hollow, go to the Connections panel and click Reconnect before running.

⚡

Multiple Queries in One Cell

You don't have to limit yourself to one query per cell. SQLBook automatically splits multiple statements separated by semicolons and executes them one by one, giving each its own result and status message.

-- All three run in sequence in one cell
CREATE TABLE orders (id INT, amount DECIMAL(10,2));
INSERT INTO orders VALUES (1, 99.99), (2, 149.50), (3, 49.00);
SELECT *, amount * 1.1 AS with_tax FROM orders;

Running the cell above produces three separate results:

✅ Table created successfully
✅ 3 rows inserted
📋 A result table with the SELECT output

More examples of what you can mix in one cell:

-- Drop + recreate + seed — all in one go DROP TABLE IF EXISTS products;
CREATE TABLE products (id INT, name VARCHAR(100), price FLOAT);
INSERT INTO products VALUES (1, 'Widget A', 29.99);
INSERT INTO products VALUES (2, 'Widget B', 49.99);
SELECT * FROM products ORDER BY price;

Each query gets its own feedback. If one statement errors, SQLBook still executes and shows results for all the other statements, so you know exactly which one failed.

💡

Smart Autocomplete Suggestions

SQLBook provides context-aware autocomplete as you type inside any query cell. Suggestions appear automatically and cover:

SQL keywords — SELECT, FROM, WHERE, JOIN, GROUP BY, HAVING, ORDER BY, etc.
Table names — inferred from the SQL you've already written in other cells of the notebook.
Column names — detected from your existing queries and schema references.
Dialect-aware keywords — suggestions adapt based on the database type selected on the cell (MySQL-specific, PostgreSQL-specific, etc.).

Press Tab to accept a suggestion or Escape to dismiss the popup. Suggestions update as you type more characters.

Tip: The more queries you write in your notebook, the better the suggestions get — SQLBook learns table and column names from all the cells in your current notebook.

🔒

Transaction Mode

By default, SQLBook splits the SQL in a cell into individual batches and executes each one on its own database connection. This is fast and reliable for most queries — but it breaks when you need multiple statements to share a single connection, which is required for:

Explicit transactions with BEGIN / COMMIT / ROLLBACK
Temporary tables (CREATE TEMP TABLE) used across multiple statements in the same cell
Session-level variables and settings
Any OracleDB work (Oracle is transaction-driven by default)

How to Enable Transaction Mode

Click the settings/gear icon next to the AI button on the top right of any query cell. Toggle Transaction Mode on. The cell will now run all its statements on a single dedicated connection in sequence.

OracleDB users: Always keep Transaction Mode enabled on cells connected to OracleDB. Oracle requires it for all operations to work correctly.

Transaction Mode Inheritance

When you add a new cell, it automatically inherits the transaction mode of the last cell you ran. So if you're working in a transaction-heavy notebook, you only need to enable it once and new cells will follow suit. The same applies when you open a saved .sqlb file — new cells will match the transaction mode of the last cell in the file.

Example — Using Transactions

-- Enable Transaction Mode on this cell, then run:
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;

📊

Query Results & Export

When a SELECT query returns results, SQLBook renders them as a table directly below the cell. Each result set gets its own table if you ran multiple statements.

Result Table Actions

Copy Table — Copies the entire result as tab-separated values. Paste directly into Excel or Google Sheets.
Export CSV — Downloads the result as a .csv file.
Visualize — Opens the chart builder for this result. See the Visualization section below.

Non-SELECT Feedback

For INSERT, UPDATE, DELETE, CREATE, DROP, and other non-query statements, SQLBook shows a descriptive status message rather than a table — for example: "3 rows inserted", "Table created successfully", or "2 rows affected".

🎨

Data Visualization

Any SELECT result can be turned into a chart with one click — and the chart saves inside the same .sqlb file as the query that produced it. When you reopen the file, the chart is exactly as you left it.

Opening the Chart Builder

Run a SELECT query to get a result table.
Click the Visualize button that appears at the top right of the result.
The chart panel opens directly below the table — the chart renders immediately using your query data.

Chart Types Available

SQLBook auto-detects the best chart type for your data, but you can switch to any of the following:

📊 Bar Chart — compare values across categories
📈 Line Chart — trends over time or sequences
🥧 Pie / Donut Chart — proportions of a whole
⚡ Scatter Plot — correlation between two numeric columns
🔲 Heatmap — intensity of values across two dimensions
🕷 Radar / Spider Chart — comparing multiple metrics
🔽 Funnel Chart — conversion / drop-off stages
🌳 Treemap — hierarchical proportions
And more…

Customising Your Chart

Change X Axis and Y Axis fields by selecting from your column names.
Add a Series / Group By column for multi-series charts.
Adjust colors, labels, legend position, and axis formatting.
Give your chart a custom name / title.
Click Save as PNG to download a high-resolution image of your chart.

Everything saves automatically. Your chart configuration — type, axis selections, colors, name — is all saved inside the .sqlb file alongside your query. When you reopen the file, the chart is exactly as you left it. Share the file with a colleague and they get the query and chart together.

🤖

AI Assistant

SQLBook has a built-in AI chat assistant that knows the content of your current cell and can maintain conversation history across the whole notebook session. You bring your own API key — nothing is proxied through SQLBook's servers.

Setting Up an AI Model

Click the Settings (gear) icon in the top bar to open Settings.
Scroll down to the AI Models section.
Click + Add AI Model.
Select your Provider. Supported providers:

Provider	API Key Starts With	Notes
OpenAI	`sk-...`	GPT-4o, GPT-4 Turbo, GPT-3.5 etc.
Anthropic (Claude)	`sk-ant-...`	Claude 3.5 Sonnet, Claude 3 Opus etc.
Google (Gemini)	`AIza...`	Gemini 1.5 Pro, Gemini Flash etc.
Groq	`gsk_...`	Fast inference — Llama 3, Mixtral etc.
Ollama (Local)	No key needed	Run models locally on your machine
OpenAI-Compatible	Depends on provider	Any API following the OpenAI spec

Give the model a Display Name (e.g. "My GPT-4o").
Select or type a Model ID.
Enter your API Key — it is encrypted and stored only on your machine. It never leaves your device.
Optionally tick Set as default model.
Click Add Model.

Using the AI Chat on a Cell

Every query cell has an AI chat button in its top-right corner. Click it to open a chat panel for that cell. The AI automatically knows the current cell's SQL content and can see the notebook's conversation history, so it understands context from your previous questions.

Use it to:

Ask "explain this query"
Ask "how do I optimize this?"
Ask "write a query to find the top 5 customers by revenue"
Debug errors — paste the error message and ask what's wrong

API keys are yours. SQLBook never sends your API key to any SQLBook server. Requests go directly from your machine to the AI provider's API endpoint.

🔍

Find & Navigate

Open the Find & Navigate panel with Ctrl + F (or Cmd + F on Mac). It gives you two ways to move around your notebook quickly.

Method 1 — Go to Cell by Number

The # Go to Cell tab lets you jump directly to any cell by its index number.

Open the Find panel.
Make sure the # Go to Cell tab is selected.
Type the cell number you want to jump to (e.g. 12).
Press Enter or click Go — the notebook scrolls directly to that cell and focuses it.

Method 2 — Search by Cell Type

The By Type tab lets you filter and jump to cells by their type — Query, Note, or Heading.

Switch to the By Type tab in the Find panel.
Select the cell type you are looking for.
Use the arrow buttons to cycle through all cells matching that type.

Quick tip: You can also directly edit the cell index number on any cell — click the number on the left side of the cell, type a new position, and press Enter to move it there instantly.

⚙️

Settings

Open Settings from the gear icon in the top bar. Settings are split into sections:

Appearance

Theme — Switch between Light ☀️ and Dark 🌙 mode. The change is instant.

Editor

Font Family — Choose the editor font. Available options: Outfit (default), Nunito, Cascadia Code, JetBrains Mono, Malgun Gothic.
Font Size — Drag the slider between 15px and 20px to adjust the editor text size.
Tab Size — Set the number of spaces used when you press Tab inside the editor. Options: 2 or 4 spaces.

Keyboard Shortcuts Reference

The settings panel also shows a full list of editor keyboard shortcuts — useful to check while you're getting familiar with SQLBook.

AI Models

Add, manage, and set default AI models. See the AI Assistant section above for full setup instructions.

Help & Feedback

Found a bug or have a suggestion? The Help tab in the About panel (click the About option in the header menu) has a direct email link to the developer.

💾

The .sqlb File

Everything in your notebook — every cell, query, note, heading, result table, chart configuration, and visualization — is saved in a single .sqlb file. It is a JSON file with a .sqlb extension.

What Is Saved in the .sqlb File

✅ All cells and their content (SQL, notes, headings)
✅ Cell types and positions
✅ Query results (the last output of each cell)
✅ Chart configurations — type, axes, colors, name
✅ Transaction mode setting per cell
✅ Notebook metadata (name, last modified date)

What Is NOT Saved in the .sqlb File

🔒 Database connection details and passwords — stored separately, encrypted, on your machine only
🔒 AI model API keys — stored separately, encrypted, on your machine only

Transfer anywhere. You can copy a .sqlb file to another computer, a USB drive, or a shared folder and open it in SQLBook on any machine. The queries, notes, and charts will all be intact. The recipient will need to set up their own connections and AI keys on their machine.

File Operations

New — Creates a blank notebook (Ctrl+N)
Open — Opens an existing .sqlb file (Ctrl+O)
Save — Saves to the current file (Ctrl+S)
Save As — Save to a new location or name
Rename — Click the filename in the top bar to edit it inline. Press Enter or click away — the file is renamed on disk automatically.

How to use SQLBook