# 4. Writing SQL

*Tabellum for desktop, chapter 4. On the web: https://tabellum.dudko.dev/manual/desktop/writing-sql*

## 4.1 The query tab

**New query tab** (the **+** above the tabs, or the palette) opens an editor on the connection chosen at its top. Type SQL and press `Cmd+Enter` or click **Run** (1): Tabellum runs the selection if there is one, otherwise the statement under the caret.

![A saved query and its rows](https://tabellum.dudko.dev/manual/desktop/img/query.jpg)

*A saved query and its rows*

Marked on the screenshot: (1) Run the statement at the caret, or the selection; (2) Format the SQL; (3) Save as a query file; (4) The query plan; (5) Table, JSON or chart.

- (2) formats the SQL: keywords upper-cased, one clause per line.
- (3) saves the tab as a file in `queries/` (`Cmd+S`).
- (4) shows the query plan (see below).
- (5) switches the result between a table, JSON and a chart.

While a query runs, **Run** becomes a red **Stop** button that counts the seconds; `Cmd+.` or `Esc` stops it too.

## 4.2 Completion

The editor completes as you type, and it knows both the database’s dialect and your schema: tables, columns of the tables the statement names (with their aliases), functions with their arguments, and whole join conditions along foreign keys.

![After ON, the joins the foreign keys allow come first](https://tabellum.dudko.dev/manual/desktop/img/complete.jpg)

*After `ON`, the joins the foreign keys allow come first*

Press `Tab` or `Enter` to accept, the arrow keys to move, `Esc` to close.

## 4.3 Parameters

A query can have named parameters — `:since`, `$1` or `@name`, as the database writes them. Before it runs, Tabellum asks for their values and passes them to the database separately, so they are never pasted into the SQL.

![Values for a querys parameters](https://tabellum.dudko.dev/manual/desktop/img/params.jpg)

*Values for a query’s parameters*

## 4.4 The query plan

**Plan** (`Cmd+Shift+E`) asks the database how it would run the statement and shows the answer as a tree. Each step has a bar for its share of the cost, the costliest steps are highlighted, and the database’s own output is a click away. Press it again to go back to the rows without running anything.

![A plan: each step with its rows and share of the time](https://tabellum.dudko.dev/manual/desktop/img/plan.jpg)

*A plan: each step with its rows and share of the time*

## 4.5 The command palette

`Cmd+P` opens the palette: type a few letters of a connection, table, saved query or command and press `Enter`.

![The command palette](https://tabellum.dudko.dev/manual/desktop/img/palette.jpg)

*The command palette*

## 4.6 The approval dialog

Tabellum reads every statement before it runs. Anything it cannot prove to be a read — `UPDATE`, `DELETE`, `INSERT`, `CREATE`, `ALTER`, `DROP` — stops at an approval dialog that shows the statements, their kind (1) and, where the database can tell, how many rows they would change.

![A write waits for your click](https://tabellum.dudko.dev/manual/desktop/img/gate.jpg)

*A write waits for your click*

Marked on the screenshot: (1) What kind of statement it is; (2) Run it, all or nothing.

**Run in transaction** (2) runs them all or none. Before a statement that changes the schema, the dialog offers to back up first. This dialog is the same whether you typed the SQL, edited cells, applied a design or the AI agent proposed it.