# rudbman user guide
rudbman is a database workbench: one window, a tab for each open connection,
a schema explorer beside it, and a work area of SQL editors, table data,
structure editors, diagrams and query builders. It talks to any database that
has a JDBC driver, through a Java runtime it starts inside itself. This guide
covers everything the application does. The [README](../README.md) is the
short version.

## Contents
- [Getting started](#getting-started)
- [Connections](#connections)
- [Tabs, panes and workspaces](#tabs-panes-and-workspaces)
- [The explorer](#the-explorer)
- [Queries](#queries)
- [Table data](#table-data)
- [Table structure](#table-structure)
- [ERD diagrams](#erd-diagrams)
- [The query builder](#the-query-builder)
- [Extracting a script](#extracting-a-script)
- [Backing up a schema](#backing-up-a-schema)
- [Transferring rows](#transferring-rows)
- [Settings](#settings)
- [Updating](#updating)
- [Keyboard shortcuts](#keyboard-shortcuts)
- [Where rudbman keeps things](#where-rudbman-keeps-things)
- [Troubleshooting](#troubleshooting)
Throughout this guide, read Cmd for Ctrl on macOS unless
a line says otherwise. The commands that live in the ☰ menu on Linux and
Windows are in the menu bar on macOS.
## Getting started
### Installing
Download the build for your platform from the
[Releases](https://github.com/xcomart/rudbman/releases) page, or install it
with `winget install Xcomart.Rudbman` on Windows or
`brew install --cask xcomart/tap/rudbman` on an Apple Silicon Mac. Every
download carries its own Java runtime, so no JDK has to be installed. The
[README](../README.md#installing) walks through each platform: the winget
package, the Windows installer and portable zip, the Homebrew cask, the macOS
Gatekeeper and local-network steps, and the Linux `install.sh`.
rudbman ships no JDBC drivers. The first time you connect to a product, the
connection dialog offers to download its driver from Maven Central, or you can
point it at a JAR you already have — see [Drivers](#drivers).
### How rudbman reaches a database
rudbman is written in Rust, and JDBC drivers are Java. The two meet inside the
one process: rudbman starts a Java runtime the first time something needs it
(the first connection or the first look inside a driver JAR) and keeps it until
it quits. Each connection loads its driver in a class loader of its own, so two
versions of the same driver can be open at once. Rows come back in compact
binary batches rather than one object at a time, and the result grids fetch
them as you scroll.
```mermaid
flowchart LR
subgraph process["rudbman process"]
ui["Window
explorer, editors, grids"]
jvm["Embedded Java runtime
and the bridge JAR"]
drv["JDBC driver
in a class loader of its own"]
ui -- "JNI" --> jvm --> drv
end
drv -- "direct" --> db1[("Database")]
drv -. "127.0.0.1:free port" .-> tunnel["SSH tunnel
through a bastion"] -.-> db2[("Database
behind the bastion")]
```
When a connection goes through an [SSH tunnel](#ssh-tunnel), rudbman opens the
tunnel first, binds a free port on `127.0.0.1`, and hands the driver a URL that
points there.
### The window
| Part | Where | What it holds |
| --- | --- | --- |
| **Tab strip** | Along the top | The ☰ menu button, one tab per open connection, **▾** (all connections), **+** (manage connections) and, when rudbman draws its own title bar, the window buttons. |
| **Explorer** | Down the left | The schema tree of the connection whose tab is in front, with a filter over it. Ctrl+B shows or hides it; drag its edge to resize it. |
| **Work area** | The rest | One or more panes, each with its own strip of tabs: query tabs, table details, table data, structure editors, ERDs and query builders. Switching the connection tab switches the whole work area with it. |
| **Status bar** | Along the bottom | The product and version, the connection state, an *uncommitted transaction* cell while one is open, and the row count and time of the last statement. |
F6 and Shift+F6 move the keyboard between the
explorer, the editor and the results.
### The welcome screen
With no connection open, the work area is the welcome screen: the name, a
**Manage connections…** button, and — once something has been saved — the
**Saved connections**, grouped under their folders.

- **Click a saved connection to connect at once.** The only exception is a
profile that does not remember its password: the connection dialog opens
over it and asks for one.
- **Right-click a row** (or Shift+F10 on a focused row)
for **Connect**, **Edit…**, **Duplicate…** and **Delete…**. The last three
open the connection dialog: on the profile, with a copy made and selected,
or with the delete question already up.
- A colored stripe in front of a row is the profile's **Tag**.
## Connections
### The connection dialog
**Manage connections…** (Ctrl+N, the **+** at the end of
the tab strip, or the welcome screen's button) opens the dialog on the first
saved profile, or on a new one when nothing is saved yet.

The list on the left groups the profiles by **Folder**. Click a folder heading
(or focus it with Tab and press Space or
Enter) to fold it; a folded folder stays folded the next time the
dialog opens during the same run of the application. Picking another profile
keeps what you typed into this one, and **Save** writes every profile you
edited.
The form, from the top:
| Field | Notes |
| --- | --- |
| **Name** | Required. A new profile starts as "New connection". |
| **Folder** | Optional. Profiles with the same folder are listed together here and on the welcome screen. |
| **Tag** | None, or one of six colors. It marks the profile on the welcome screen, its root in the explorer and the dot on its work tabs. |
| **Driver** | Starts empty on a new profile. **Drivers…** beside it opens the [driver manager](#drivers) on the driver the form names. |
| **Host**, **Port**, **Database** | One field for each hole in the driver's URL template. **Database** stands for whatever the template calls it: a database, an Oracle service, a SID or an SQLite file. **Port** starts at the driver's default port. |
| **URL** | Assembled from the fields above as you type. Edit it directly and it keeps what you type — "Typed by hand; the fields above no longer change it." — until you press **Rebuild**. |
| **User**, **Password** | The password is masked, and read from the system keychain when a saved profile is shown. |
| **Remember password in the system keychain** | On by default. Off, rudbman keeps neither the password nor the tunnel's secret anywhere — and deletes what it had kept — and asks for them on every connect. |
| **Driver properties** | Key/value rows passed to the driver, with **Add a property**. A row with no key is dropped. |
| **Behavior** | See [below](#behavior). |
| **SSH tunnel** | Folded unless it is on. See [SSH tunnel](#ssh-tunnel). |
| **Hide in the explorer** | Folded unless it holds something. See [Hide in the explorer](#hide-in-the-explorer). |
A driver that has no JAR yet says so under the picker. When the driver has a
Maven coordinate, **Download** sits right there, with progress and **Cancel**,
so a first connection to a new product needs no trip to the driver manager.
#### Behavior
| Switch | Default | What it does |
| --- | --- | --- |
| **Open the connection read-only** | off | Opens the session read-only and refuses every write — see [Guarded connections](#guarded-connections). |
| **Commit each statement as it runs** | on | Auto-commit. Off, the statements you run join a transaction you end with **Commit** or **Rollback** — see [Transactions](#transactions). |
| **Ask before running a write statement** | on | Asks before a query tab sends a statement that changes data. A new profile takes its starting value from Settings. |
| **Keep the connection alive with a periodic query** | off | On, two fields appear: the interval in seconds (300) and the query (`select 1`). |
#### SSH tunnel
Tick **Connect through an SSH bastion** to reach a database that only a
bastion host can see.
| Field | Notes |
| --- | --- |
| **Bastion** | The SSH host and its port (22). |
| **Bastion user** | The SSH login. |
| **Authentication** | **SSH agent** (the default; nothing is stored), **Private key**, or **Password**. |
| **Key file** | For **Private key**: an OpenSSH or PKCS#8 PEM key. A leading `~` is the home directory of whoever runs rudbman. |
| **Key passphrase** / **Bastion password** | Masked, and kept in the keychain like the database password. |
| **Database** | The database's host and port *as the bastion sees them*, for example `db.internal` and `5432`. |
rudbman binds a free port on `127.0.0.1` — never on every interface — and
points the driver there, so the database host and port in the URL are replaced
with the tunnel's. A URL with no host and port to replace, such as an SQLite
file, cannot go through a tunnel. The bastion is asked for no terminal, so a
jump host whose login shell is `nologin` works. A single bastion is supported;
chains of jump hosts are not.
Host keys are trusted on first use and kept in rudbman's own `known_hosts`
file, not in `~/.ssh/known_hosts`. An unknown key is refused with its full
fingerprint shown, and **Trust this key** (after **Test**) or **Trust the key
and reconnect** (on a failed tab) adds it. A key that *changed* is refused with
no button to accept it: if the change is expected, remove the old line from
`known_hosts` by hand.
A tunnel that breaks is never repaired behind your back: the connection tab
says the tunnel closed and offers **Reconnect**.
#### Hide in the explorer
Some databases carry schemas or objects you never want to scroll past —
temporary schemas, recycle-bin tables, system catalogs. This section hides them
from the explorer for this profile, for good.
- **Catalogs**, **Schemas** and **Objects** each take one regular expression a
line, matched against the **whole** name, case ignored: `pg_temp_.*`,
`BIN\$.*`, `template[01]`.
- **Show only what the list matches** turns a list around, as SQL
Workbench/J's inclusion filters do.
- **Applies to** picks the folders the object list acts on (all six by
default).
- A catalog or schema level left with one member is skipped, as if the others
were never there. A level whose members are all hidden is left empty rather
than skipped.
- A line that is not a valid regular expression is named under its field, and
**Save** is refused until it is fixed.
Saving the profile while it is connected reloads its tree with the new lists,
keeping what was expanded. To narrow the tree for the moment rather than for
good, use the explorer's own [filter](#filtering-the-tree).
#### Testing, saving and connecting
| Button | What it does |
| --- | --- |
| **New** | A new, empty profile. Ctrl+N inside the dialog does the same. |
| **Duplicate** | A copy named "… (copy)". The password is not copied. |
| **Delete** | Asks first, then removes the profile and its saved secrets. |
| **Test** | Connects with what is on the form — without saving it — and says "Connected to *product*." or why it could not, with a hint. |
| **Cancel** | Closes the dialog. |
| **Save** | Saves every profile edited. Ctrl+S does the same. |
| **Connect** | Saves, closes the dialog and opens the connection. Enter in a field does the same. |
Closing the dialog with unsaved edits — Esc, **Cancel** or a click
beside it — asks **Keep editing**, **Discard** or **Save**.
### Drivers
**Drivers…** turns the connection dialog into the driver manager. A driver
definition is a name, the driver class, a URL template, a default port, a SQL
dialect, a Maven coordinate and the JAR files.
Eight products are defined out of the box, each with the dialect rudbman uses
for its highlighting, quoting, paging and DDL:
| Driver | Maven coordinate | URL template | Port |
| --- | --- | --- | --- |
| H2 | `com.h2database:h2:2.3.232` | `jdbc:h2:tcp://{host}:{port}/{database}` | 9092 |
| PostgreSQL | `org.postgresql:postgresql:42.7.4` | `jdbc:postgresql://{host}:{port}/{database}` | 5432 |
| MySQL | `com.mysql:mysql-connector-j:9.1.0` | `jdbc:mysql://{host}:{port}/{database}` | 3306 |
| MariaDB | `org.mariadb.jdbc:mariadb-java-client:3.5.1` | `jdbc:mariadb://{host}:{port}/{database}` | 3306 |
| SQLite | `org.xerial:sqlite-jdbc:3.47.1.0` | `jdbc:sqlite:{file}` | — |
| Oracle Thin | `com.oracle.database.jdbc:ojdbc11:23.6.0.24.10` | `jdbc:oracle:thin:@//{host}:{port}/{service}` | 1521 |
| Microsoft SQL Server | `com.microsoft.sqlserver:mssql-jdbc:12.8.1.jre11` | `jdbc:sqlserver://{host}:{port};databaseName={database}` | 1433 |
| IBM Db2 | `com.ibm.db2:jcc:12.1.5.0` | `jdbc:db2://{host}:{port}/{database}` | 50000 |
None of them comes with its JAR. To give a driver one:
- **Download** fetches the coordinate's JAR from Maven Central, checks it
against the SHA-1 Central publishes, and stores it in the `drivers` folder of
the configuration directory. Only that one artifact is fetched, not its
dependencies, which is all the drivers above need.
- **Add a JAR…** picks one or more files from disk, left where they are. A JAR
that has since gone missing is marked *missing*; **Remove** takes one off.
**Detect** looks inside the JARs for the driver class. The first look starts
the Java runtime, which can take a few seconds. When a JAR holds several
drivers, the one its vendor declares is listed first and marked
*recommended*; a JAR that holds none — a sources or javadoc JAR picked by
mistake — is said to hold none.
**Table comments** and **Column comments** are for products whose driver
reports no comments through JDBC. Tick **Read table comments with a query** and
give a query that returns the table name and the comment, in that order;
`${catalog}` and `${schema}` are filled in. The column query returns the table
name, the column name and the comment.
**New** adds a driver of your own — any JDBC driver works, with the generic
dialect if none fits — and **Delete** removes a definition after asking.
Profiles that used it are left alone. Adding or removing a JAR and finishing a
download are saved at once; other edits are saved with **Save**, and **Close**
leaves without saving them.
> **H2 embedded.** The H2 template reaches an H2 server. For a database file,
> edit the profile's **URL** to `jdbc:h2:file:/path/to/db`.
### Connecting, and when it fails
**Connect** opens a tab at once, in front, and its work area says
"Connecting to “*name*”…" with **Cancel**. The attempt gives up after the
**Connection timeout** in [Settings](#database) — 30 seconds unless changed.
Once connected, the explorer opens onto the database and schema the session
landed in, and the profile's saved [workspace](#what-is-kept-between-sessions)
comes back.
```mermaid
stateDiagram-v2
[*] --> Connecting: Connect
Connecting --> Connected: session opened
Connecting --> Failed: error, timeout or Cancel
Connected --> Ended: session or SSH tunnel lost
Failed --> Connecting: Reconnect
Ended --> Connecting: Reconnect
Connected --> [*]: Close connection
```
A tab that could not connect, or whose session ended, keeps its place and
says why in its work area: the whole message, a one-line hint, and
- **Reconnect** — tries again in the same tab, re-reading the profile, so a
fix made with **Edit connection…** is picked up;
- **Edit connection…** — opens the connection dialog on the profile;
- **Copy message** — puts the error on the clipboard;
- **Trust the key and reconnect** — only when the bastion's host key is not
trusted yet.
When the tab still has work tabs open, the same message is a band above them,
so nothing you had open is closed. The dot in front of the tab's name is green
while connected and red when it failed or ended.
### Passwords and the keychain
Passwords and the tunnel's password or key passphrase are kept in the
operating system's keychain — Windows Credential Manager, the macOS Keychain,
or the Secret Service (GNOME Keyring, KWallet) on Linux — under the service
name `rudbman`. They are never written to disk by rudbman. If no keychain is
available, a notice says so at start-up: saved passwords cannot be read, and
connecting sends an empty password unless you type one.
A profile with **Remember password in the system keychain** off asks for the
password on every connect, in the connection dialog, with the keyboard in the
**Password** field: type it and press **Connect**.
## Tabs, panes and workspaces
### Connection tabs
Each open connection is a tab in the strip along the top. Drag a tab to
reorder it; **▾** lists them all. Right-click a connection tab for:
- **New query** and **New query builder** (while connected);
- **Query history…**;
- **Reconnect** (when the tab failed or ended) and **Edit connection…**;
- **Close connection**.
Ctrl+Alt+PgDn / PgUp moves to the
next or previous connection tab (Linux and Windows).
### Work tabs and panes
Everything you open on a connection is a tab in a pane of its work area: query
tabs (**Query 1**, **Query 2**, …), table details and data (named after the
table), structure editors, ERDs and query builders (**Builder 1**, …).
- **Split** a pane with **Split right** (Alt+Shift+D)
or **Split below** (Alt+Shift+S); the new
pane starts with a copy of the selected tab. On macOS the pane chords use
Cmd instead of Alt.
- **Drag** a tab to reorder it, or onto another pane to move it there. A pane
disappears when its last tab closes; the last pane always stays.
- **Rename** a tab from its right-click menu (**Rename tab…**); leave the name
blank to go back to the default.
- **Reopen closed tab** (Ctrl+Shift+T) brings
back the query or builder tabs closed last, up to ten.
- **Middle-click** a tab to close it.
A pane tab's right-click menu has **Rename tab…**, **Close tab**, **Close
other tabs**, **Close tabs to the right**, **Reopen closed tab**, **Split
right**, **Split below** and **Close pane**.
| Keys | Does |
| --- | --- |
| Ctrl+PgDn / PgUp, Ctrl+Tab / Ctrl+Shift+Tab | Next / previous tab of the pane (macOS: Cmd+Alt+→ / ←) |
| Ctrl+1–8, Ctrl+9 | Tab *n* of the pane, the last tab |
| Alt+] / [ | Next / previous pane, keyboard included |
| Alt+W | Close the pane |
| Ctrl+W | Close the tab on top (Linux and Windows; Cmd+W closes the pane on macOS) |
### What is kept between sessions
Each profile has a workspace that is saved as you work and when you close:
its panes and splits, its tabs and their names, the SQL in every query tab,
the files they are bound to, query builders, data-tab filters and the
explorer's filter. Connecting the profile again brings it all back.
What is *not* kept: result rows, staged edits, open transactions and the
session itself. SQL comes back without being run. A draft over 4 MiB is not
kept either — the tab says so, and saving it to a file is the way to keep it.
### Closing and quitting
Nothing is lost without a question:
- A tab with **staged row or structure changes** refuses to close — and so do
the pane and the connection tab holding it — until the changes are applied
or discarded.
- A query tab bound to a `.sql` file with **unsaved changes** asks **Save**,
**Don't save** or **Cancel**. A tab bound to no file is a draft, kept with
the workspace, and closes without asking.
- Closing a connection with an **uncommitted transaction** (it will be rolled
back) or a **running statement** (it will be stopped) asks first.
- **Quit** (Ctrl+Q), closing the window, and the restart
after an update list everything they would lose — unapplied changes, unsaved
files, running statements, open transactions, running extractions, transfers
and backups — and offer **Save all** for the files.
## The explorer
### The tree
The explorer shows the connection whose tab is in front:
- the **connection**, with its tag-colored dot;
- its **catalogs** and **schemas** — a level with a single member is skipped,
so a database with one schema shows its folders straight away;
- six folders under each schema: **Tables**, **Views** (materialized views
too), **Procedures**, **Functions**, **Sequences** and **Triggers**, each
with the number of objects once it has been read;
- the **objects**, each followed by its comment, when it has one.
On connect the tree opens onto the database and schema the session landed in.
Folders are read when first opened; **Refresh** in the header (or on a node's
menu) reads them again, keeping what was expanded.
- **Double-click** an object — or select it and press Enter — to
open its [detail panel](#the-detail-panel), or bring it to the front if it
is open already. Double-click a folder to open or close it.
- → / ← expand and collapse; ↑ /
↓, Home and End move.
- **Drag** a table or view onto a [query builder](#the-query-builder).
### Filtering the tree
The box over the tree narrows what it shows, without asking the database
again: Ctrl+F puts the keyboard in it.
| Typed | Matches |
| --- | --- |
| `cust` | Names containing `cust`, case ignored |
| `*_seq` | Names that are *wholly* matched: a term with `*` or `?` is a wildcard over the whole name |
| `orders, items` | Either term — a comma means "or" |
| `!tmp*` | Leaves the names that match out |
- **`.*`** (or Alt+R) reads the box as one regular
expression, matched anywhere in the name, case ignored. One that does not
compile is marked and filters nothing.
- Enter opens the folders that may hold matches and hands the
keyboard to the tree; Esc clears the box, and pressed again goes
back to the tree.
- The **folders button** (it reads **All** at first) picks which of the six
folders the filter narrows, and whether it narrows only the database the
connection landed in (**Connected database only**, the default) or **All
databases**.
- **Conditions** opens a panel of conditions on the **Name**, the **Comment**
or the **Schema** (the database on MySQL and MariaDB): *contains*, *does not
contain*, *starts with*, *ends with*, *is*, *wildcard*, *regex*, *is empty*,
*is not empty*. They are taken all together (**Match all**) or any one of
them (**Match any**), and always together with the box.
- **History** lists the filters used on this profile, newest first, up to 20:
pick one to put it back whole. Remove one with its **×** or
Delete, or all with **Clear this connection's history**.
- **Reset** puts the box, the folders and the conditions back as they started.
The history keeps the filter you reset, so it is one pick away.
While a filter is on, a line under the tree says how many of the objects read
so far match — a folder nobody has opened has not been filtered. Each
connection tab keeps its own filter, and it comes back when the profile
connects again.
### Selecting and copying
Ctrl-click toggles a row, and Shift-click or
Shift+↑ / ↓ selects a run. Then:
- **Copy names** (Ctrl+C) copies the names of the
selected catalogs, schemas and objects, one per line;
- **Copy SELECT statement** copies a laid-out `SELECT` of every column of each
selected table and view;
- **Copy INSERT statement** copies an `INSERT` with a `:column` placeholder for
each value, for each selected table.
Right-clicking inside the selection keeps it; right-clicking elsewhere acts on
the row under the pointer. **Drop** and **Truncate** act on the selection the
same way; every other command acts on one object.
### The explorer's menu
Right-click a node, or press Shift+F10 (or the Menu key)
with the tree focused. A row an object has no use for is left out.
| Node | Menu |
| --- | --- |
| Table | **View data**, **Edit structure**, **Query the selected object** (Ctrl+Enter), **Add to query builder**, **Extract script…**, **Transfer rows…** · **Copy names**, **Copy SELECT statement**, **Copy INSERT statement** · **ERD diagram** (Ctrl+E), **Back up schema…**, **Restore from script…** · **Truncate table…**, **Drop table…** · **Refresh** |
| View | The same, without **Copy INSERT statement** and **Truncate table…**, and with **Drop view…** |
| Sequence | **Copy names** · **ERD diagram**, **Back up schema…**, **Restore from script…** · **Drop sequence…** · **Refresh** |
| Procedure, function, trigger | **Copy names** · **ERD diagram**, **Back up schema…**, **Restore from script…** · **Refresh** |
| Schema or catalog | **Copy names** · **New table**, **ERD diagram**, **Back up schema…**, **Restore from script…** · **Drop schema…** or **Drop database…** · **Refresh** |
| Tables folder | **New table**, **ERD diagram**, **Back up schema…**, **Restore from script…** · **Refresh** |
| Other folders | **ERD diagram**, **Back up schema…**, **Restore from script…** · **Refresh** |
**Query the selected object** opens a query tab with `SELECT * FROM` the
object in it. **ERD diagram**, **Back up schema…** and **Restore from
script…** act on the schema (or catalog) the selection sits in.
### Dropping and truncating
**Drop…** removes a table, view, sequence, schema or database; **Truncate
table…** deletes every row of a table and keeps the table. Neither runs from
the menu: a question shows every statement it will send, and its button stays
disabled until you type the object's name (or `DROP` / `TRUNCATE` when several
objects are selected) into the field below them. `Esc`, **Cancel** or a click
outside sends nothing.
- The statements are the plain ones — no `CASCADE`, no `IF EXISTS` — so the
database refuses a schema that is not empty or a table another table's key
still points at, and its reason is shown.
- Over a selection, views are dropped before tables and sequences last; the
first failure stops the rest, and what ran before it stays done.
- Each product's own spelling is used: Oracle drops a schema with
`DROP USER`, Db2 with `DROP SCHEMA … RESTRICT`, MySQL and MariaDB with
`DROP DATABASE`; SQLite empties a table with `DELETE FROM`. **Drop
database…** is offered on PostgreSQL, MySQL, MariaDB and SQL Server only.
- Both rows are grayed on a read-only connection, and refused while a query
tab on the same connection has uncommitted changes.
- Procedures, functions and triggers are not offered: their drop needs a
signature or a parent table the tree does not hold.
### The detail panel
A table or view opens a panel of four tabs, read once and switched between for
free. **View data** and **Edit structure** in its header open the
[data](#table-data) and the [structure](#table-structure) of the same table;
**Refresh** reads it again.

| Tab | Shows |
| --- | --- |
| **Columns** | Column, type, `NULL` / `NOT NULL`, default, `PK`, comment |
| **Keys** | The **Primary key** and the **Indexes**, with uniqueness and order |
| **References** | **Foreign keys of this object** and **Foreign keys pointing at this object**, with their `ON UPDATE` / `ON DELETE` rules |
| **DDL** | The object's `CREATE`, in a read-only, highlighted editor, with **Copy** |
The DDL is the server's own text wherever the product can give it back, and
otherwise rebuilt from the catalog — in which case a line above it says what
the rebuilt text leaves out (check constraints, triggers, partitioning,
collations). Either way it is laid out for reading: one column to a line, a
view's query as Format SQL writes it, a routine's or a trigger's body indented
by block.
Procedures, functions, sequences and triggers get a **Properties** tab — a
routine's parameters and return type, a sequence's start, increment, bounds
and current value, a trigger's table, timing, events and status — and a
**DDL** tab.
In the **Columns** tab, pick rows as in the tree and right-click for **Copy
names** (one per line), **Copy names, comma-separated**, **Copy rows** (the
whole rows as tab-separated text) and **Select all**.
## Queries
### Opening a query tab
- **New query** (Ctrl+T) opens an empty query tab on the
connection in front.
- **Query the selected object** (Ctrl+Enter in the
explorer) opens one with a `SELECT` of the selected object.
- **Open SQL file…** (Ctrl+O) reads a `.sql` file into a
new query tab.
- **Query history…** opens a past statement in a new tab.
### Running statements
| Keys | Runs |
| --- | --- |
| Ctrl+Enter | The statement under the caret |
| Ctrl+Alt+Enter | The selection |
| Ctrl+Shift+Enter | Everything in the editor |
| Esc | Stops the running statement (in the editor or the results) |
**How statements are told apart.** Statements end at a `;`, read the way the
connection's dialect reads them: a `;` inside a string, a comment or a
PostgreSQL `$$` body does not end one. Blank lines do not separate statements,
a last statement needs no `;`, and comments above a statement belong to it.
The statement under the caret is drawn with a band behind it; with the caret
between two statements, the one before it is the one that runs. The `;` itself
is not sent.
- **Run all** reads the editor the way the product's own command-line client
reads a script, and gives each result set its own tab: MySQL's and
MariaDB's `DELIMITER`, SQL Server's `GO` (a batch holding a routine or a
`DECLARE` is sent whole, as `sqlcmd` sends it), Oracle's `/` after a
PL/SQL unit (a `CREATE PROCEDURE`, a `BEGIN … END` block, a package runs to
its `/`, or to the end of the editor), Db2's `--#SET TERMINATOR` and
SQLite's `CREATE TRIGGER … END;`. Commands that only change what the client
prints — SQL\*Plus's `SET DEFINE OFF`, `PROMPT`, `REM`, psql's `\echo` — are
skipped, `EXEC` runs as a block, and `EXIT`, `QUIT` or `\q` end the run
there. A command that cannot be carried out here (`\connect`, `SOURCE`,
`@file`, `:setvar`, `DEFINE x = …`, `COPY … FROM stdin`) stops the run before
anything is sent, with its line selected.
- **Run selection** splits the selection on `;` — except that a selection
holding a procedural block (`DECLARE`, `BEGIN … END`, `CREATE PROCEDURE`
and the like) is sent whole, so select a routine's whole definition to
create it, no `DELIMITER` needed. A selection with one of those client lines
in it (`DELIMITER`, `GO`, `/`, …) is read the way **Run all** reads the
editor.
- There is no prompt for bind parameters: `?`, `:name` and the like are sent
as typed.
The toolbar over the editor has, in order: **Run statement**, **Run
selection**, **Run all**, **Explain plan**, **Cancel** · **Commit**,
**Rollback** · **Undo**, **Redo** · **Cut**, **Copy**, **Paste**, **Select
all** · **Toggle comment**, **Format SQL** · **Find…**, **Replace…**. Hover a
button for its shortcut. The editor's right-click menu has the same commands
and **SQL completion**.
A tab runs one thing at a time: a second run while the first is going is
refused rather than queued.
### Results and the result log
Each result set opens a **Result *n*** tab under the editor. **Result log**,
the first tab, records every statement that ran — its SQL, how long it took,
and "Statement executed.", the rows it affected, or the error it stopped at —
and the total time of the run. Right-click a log row for **Copy message** and
**Copy SQL**.
When a single statement fails, the result area shows the driver's message,
its SQLSTATE, and a hint chosen by the kind of error (a syntax or permission
problem, a broken constraint, a lost connection), with **Copy message**.
The status bar counts the rows read across the result tabs — or the rows
affected, when nothing was read — and the time the whole run took.
- The grid fetches rows as you scroll, **Rows per batch** at a time (500
unless changed in Settings). The status bar reads "500+ rows" while more
remain, and a grid stops at 200,000 rows with a note that the result has
more.
- Click a column heading to sort: ascending, descending, then unsorted. A sort
runs the statement again with `ORDER BY`, since the grid holds only the
first rows of the answer.
- A statement that changes rows reports how many.
- **A script that fails part way** stops there. The log names which statement
of how many failed, with its SQL and the error, the results of the
statements before it stay, and the failed statement is selected in the
editor.
A result that comes from one table with its whole primary key among the
columns can be edited in place — see [Editing a query result](#editing-a-query-result).
### Transactions
On a profile with **Commit each statement as it runs** on (the default), every
statement commits as it runs, there is nothing to end, and **Commit** and
**Rollback** are grayed out.
With it off, the statements a query tab runs join one open transaction:
- the status bar shows **uncommitted transaction** — its tooltip names the
query tab the writes came from — and the connection tab wears a dot;
- the editor's **Commit** and **Rollback** buttons are lit:
F11 commits and F12 rolls back (on macOS
Ctrl+Cmd+C / R, since
F11 is Show Desktop there). A `COMMIT` or `ROLLBACK` run from the
editor ends the transaction just the same;
- applying edits in a grid, changing a table's structure and transfers on that
connection are refused, naming the query tab to commit or roll back from,
rather than committing or discarding your transaction for you;
- closing the connection asks first, because the transaction would be rolled
back.
### Guarded connections
Two profile switches stand between a statement and a database you would rather
not change by accident.
- **Open the connection read-only** opens the session read-only and refuses a
write from a query tab without sending it: "This connection is read-only; the
statement was not sent." Grids and the structure editor show the rows and
the shape but offer no editing.
- **Ask before running a write statement** puts up **Run this statement?**,
with the number of statements that change data and the first of them, and
**Cancel** focused. **Run it** sends them.
A *write* is anything starting with `INSERT`, `UPDATE`, `DELETE`, `MERGE`,
`CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `CALL`, `EXEC`, `GRANT`, `REVOKE`,
`REPLACE`, `UPSERT` or `COPY`, a `SELECT … INTO`, and a `WITH` that writes. A
statement rudbman cannot classify — `BEGIN`, `SET`, a vendor-specific command
— counts as a write too, so a guarded connection errs on the side of asking.
### Explain plan
**Explain plan** (Ctrl+Shift+E, the toolbar,
the editor's right-click menu or the ☰ menu) shows the plan of the selection,
or of the statement under the caret, in a read-only **Plan *n*** tab of up to
10,000 rows. The statement itself is **not run**, and the log says so. A
selection of several statements is refused: select one.
| Product | How the plan is asked for |
| --- | --- |
| PostgreSQL, MySQL, MariaDB, H2 | `EXPLAIN` |
| SQLite | `EXPLAIN QUERY PLAN` |
| Oracle | `EXPLAIN PLAN FOR`, then `DBMS_XPLAN.DISPLAY()` |
| SQL Server | `SET SHOWPLAN_TEXT ON`, the statement, `SET SHOWPLAN_TEXT OFF` |
| Db2 | Not supported: it needs explain tables of its own |
| Any other driver | `EXPLAIN`, and the database's own answer |
A plan is not a write, so a read-only profile and **Ask before running a write
statement** let it through. Two cautions:
- Oracle's `EXPLAIN PLAN` writes into the session's `PLAN_TABLE`, which on a
manual-commit connection joins the open transaction, and which a read-only
connection may refuse.
- While SQL Server's option is on, anything else sent on the same connection
in that moment — another tab's statement, the explorer — is planned rather
than run. `SHOWPLAN_TEXT OFF` is sent even when the plan fails, and if it
cannot be sent, rudbman says so in red: reconnect before running anything
else.
### Completion
Completion opens as you type a word or after a dot, or with
Ctrl+Space — Ctrl on macOS too:
↑ / ↓ choose, Enter or Tab
inserts, Esc dismisses. It offers keywords, the dialect's common
functions (`COUNT`, `SUM`, `AVG`, `MIN`, `MAX` and the usual scalar ones), and
the connection's schemas, tables and columns — columns read on demand, and
found through table aliases. Completing a function replaces its name and keeps
the arguments already written. Nothing is offered inside comments and string
literals.
### Format SQL, find and replace, comments
- **Format SQL** (Ctrl+Shift+F) lays out the
selection, or the whole editor, in the [sqlstyle.guide](https://www.sqlstyle.guide/)
"river" layout: keywords right-aligned on a river, one column to a line.
- **Find…** (Ctrl+F) and **Replace…**
(Ctrl+H) open the find bar over the editor, filled with
the selection when it is on one line. It searches for plain text as you
type, counts the matches, and has **Aa** for a case-sensitive search.
F3 / Shift+F3 go to the next and previous
match (also Cmd+G / Cmd+Shift+G
on macOS), Ctrl+Alt+Enter in the bar
replaces them all, and Esc closes it.
- **Toggle comment** (Ctrl+/) comments or uncomments the
selected lines with `--`.
The editor highlights SQL as the connection's dialect writes it, handles input
methods for Korean, Japanese and Chinese, keeps a new line's indentation,
indents and outdents with Tab / Shift+Tab, and
wraps long lines when **Wrap long lines in the editor** is on in Settings. Its
text size is **Editor size** in Settings.
### SQL files
- **Save SQL file** (Ctrl+S) writes the tab to the file
it was opened from or last saved to. The first time, it asks where,
suggesting the tab's name with today's date after it — or before it, or
left out, as **SQL file name date** in Settings says. A name typed without
an extension is saved as `.sql`.
- **Save SQL file as…** (Ctrl+Shift+S on Linux
and Windows) always asks.
- The tab takes the file's name, and a dot after it marks changes not yet
saved.
- A file changed on disk since the tab read or saved it — by another program,
or by another tab — is never overwritten in place: the save asks where
instead.
### Query history
Every statement a query tab runs because you asked it to is recorded for the
connection's profile: when it ran, how long it took, and the rows it returned,
the rows it changed, or the error it stopped at. Sort re-runs, grid applies,
plans and writes that were refused or declined are not recorded.
**Query history…** (Ctrl+Shift+H, the ☰ menu
or a connection tab's menu) lists them newest first, with the whole statement
under the list:
- type to search; ↑ / ↓ move;
- Enter or a double-click opens the statement in a **new query
tab**, without running it;
- **Copy SQL**, **Delete** and **Clear history…** are beside it and on a row's
right-click menu.
Each profile keeps up to 1,000 statements and 4 MiB of SQL, oldest dropped
first; a statement over 256 KiB is not recorded. The history is plain JSON in
the configuration directory, and statements can carry secrets: **Keep a
history of the statements query tabs run** in [Settings](#database) turns
recording off (what was recorded stays until it is deleted).
## Table data
### The data tab
**View data** — from the explorer's menu or the detail panel — opens a table's
rows in a data tab, one per table. It reads them as you scroll, like a query
result, and stops at 200,000 rows. **Refresh** (F5) reads them
again; **Cancel** stops a load or a sort that takes too long.

Click a column heading to sort by it: the rows are read again in that order,
with the primary key as a tie-breaker. The header's right-click menu also has
**Fit to contents**, **Hide this column**, **Show all columns** and **Copy
column name**.
### Filtering rows
The **WHERE** strip under the toolbar reads the rows again under a condition:
1. Type a condition such as `status = 'PENDING'` (Ctrl+F
puts the keyboard there).
2. Press Enter or **Filter**. **Filtered** beside the row count
says the rows are not all of them.
3. Esc or **Clear** brings every row back.
A leading `WHERE` and a trailing `;` are taken off, and a second statement
after the condition is refused. A condition the database rejects is reported
like any failed load and stays in the field to be corrected. The filter is kept
with the workspace and copied by a split.
### Editing rows
A table can be edited when it has a primary key and the profile is not
read-only; otherwise a line above the grid says why its rows can be read but
not changed. Views usually report no primary key, so their rows are read-only.
Columns the driver reports as read-only or auto-incremented cannot be edited.
| To | Do |
| --- | --- |
| Edit a cell | Double-click it, press F2 or Enter, or start typing. Enter keeps the value, Esc cancels, Tab moves on. |
| Set a cell to `NULL` | **Set to NULL**, Ctrl+0 or Shift+Delete. Emptying a field stores an empty string, not `NULL`. |
| Add a row | **Insert row** or Alt+Insert. Cells you leave alone read *DEFAULT* and are left out of the `INSERT`, so the server fills them. |
| Delete rows | Delete (and Backspace on macOS) marks the selected rows; pressed again, it unmarks them. |
| Paste | Ctrl+V pastes tab-separated cells from the cursor on, or one value into every selected cell. |
| Undo a row | **Discard this row's changes**, or **Restore row** on a deleted one. |
| Undo everything | **Discard**, which asks first. |
Nothing reaches the database until you apply. The toolbar counts what is
staged — "2 changed · 1 inserted · 1 deleted" — and while anything is, a sort,
a refresh or a new filter waits for it to be applied or discarded.
### Applying changes
**Apply** (Ctrl+S) always shows the statements first,
each with the values it binds. **Apply** there runs them:
```mermaid
flowchart TD
edit["Edit cells, insert rows,
mark rows deleted"] --> staged["Staged in the grid"]
staged -- "Discard" --> gone["Thrown away"]
staged -- "Apply" --> preview["Preview of every statement
and the values it binds"]
preview -- "Cancel" --> staged
preview -- "Apply" --> tx["One transaction:
deletes, then updates, then inserts"]
tx -- "all succeed" --> done["Commit and read the rows again"]
tx -- "any fails, or a row changed underneath" --> back["Roll back, and keep the edits staged"]
```
- Every `UPDATE` and `DELETE` finds its row by the primary key alone, and must
touch exactly one row. If one touches none or several — somebody else
changed or deleted the row — the whole batch is rolled back and nothing is
applied.
- A value that cannot be written to its column (`abc` into an integer) is
refused before anything is sent.
- On a product without transactions the preview says so in red, because a
failure part way cannot be undone.
- Apply is refused while a query tab on the connection holds an uncommitted
transaction.
### Editing a query result
A query result can be edited like a data tab when its rows come from **one
table** and **every column of its primary key** is among the selected columns.
The rows appear at once; the grid becomes editable a moment later, once the key
has been looked up. Otherwise a line above the grid says the rows can be read
but not changed.
A query result takes **updates and deletes**, never inserts: a row typed into
`SELECT id, name` would miss every column not selected, and need not satisfy
the query's own `WHERE`. Inserting is what the table's data tab is for. Apply
and Discard sit on the result tab strip, Apply uses the same preview and
transaction, and the statement runs again afterwards.
### LOB and multiline values
Double-click a BLOB or CLOB cell (including a `NULL` one), or choose **Open
LOB…** from its menu. A text cell that holds line breaks shows its first line
with visible `\n` separators, and opens the same viewer with **Open text
editor…**.
- A CLOB or text value is edited as text, and files are read and written as
UTF-8. A BLOB is edited as hexadecimal byte pairs, 16 to a line.
- **Save to file…** writes the complete value. **Replace from file…** takes
a replacement without changing the database yet. **Empty value** and **Set
to NULL** are kept apart, because the database tells them apart.
- **Add to changes** (Ctrl+Enter) stages the value; the
grid's **Apply** writes it, with the same preview and transaction.
- Only the first 1 MiB of a larger value is shown, read-only; it can still be
saved whole, and replaced from a file without being loaded into the editor.
- A read-only result can still be viewed and saved.
Copying and writing keep the real line breaks of a multiline value.
### Copying from the grid
Select cells with the mouse or the keyboard (Ctrl+A
selects all) and right-click:
| Row | Copies |
| --- | --- |
| **Copy as TSV** (Ctrl+C) | Tab-separated values, no header, `NULL` as an empty field |
| **Copy as CSV** | Comma-separated values, quoted where needed |
| **Copy as JSON** | An array of objects keyed by column name, `NULL` as `null` |
| **Copy as INSERT** | One `INSERT` per row, into the table the rows come from |
## Table structure
### Editing a table's structure
**Edit structure** — from the explorer's menu or the detail panel — opens a
table's columns and constraints in a pane that writes `ALTER TABLE` for you.
- **Columns** lists every column with its type, nullability, default and
state. Pick one and change it in the **Selected column** form under the
list: **Name**, **Type**, **Default** with **Has a default**, and **NOT
NULL**. A type or a default is your own SQL, passed through as typed.
- **Add column** adds one; **Drop** marks an existing one to be dropped
(**Keep** takes the mark off), and **Remove** takes back an added one.
- **Constraints** lists the primary key, unique constraints and foreign keys,
each of which can be dropped.
- **Rename table** gives the table a new name in the same schema.
- **Statements** shows the batch your changes would send, recomputed as you
type, or — in red — why a change cannot be written for this product.
**Apply** shows the statements and runs them. Unlike a data edit, a structure
change cannot be rolled back: several products commit at every DDL statement
whatever the client asks, so rudbman runs the batch with auto-commit on, stops
at the first statement that fails, and says how many before it were committed.
Either way, the pane then reads the table again.
### Creating a table
**New table** — on a schema, a catalog or a Tables folder — opens the same pane
in create mode, titled "New table in *schema*":
1. Give the **Table name**.
2. **Add column** for each column, filling in the form.
3. Under **Add a constraint**, pick **PRIMARY KEY**, **UNIQUE** or **FOREIGN
KEY**, tick the columns in the order you want them, optionally name it,
and for a foreign key give the **Referenced table** (and its columns, or
leave them empty for its primary key). **Add constraint** stages it.
4. **Create table**.
Creating a table is the one place a constraint is born: once the table exists,
the pane can drop constraints but not add them. A create that fails keeps what
you typed. One that succeeds turns the pane into the structure editor of the
new table and refreshes the schema in the explorer.
### What each database cannot do
What a product cannot express is refused by name before anything is sent,
rather than sent and rejected:
- **SQLite** can add, drop and rename columns and rename the table — nothing
else. A changed type, nullability or default would need the table rebuilt,
and constraints cannot be dropped.
- **SQL Server** keeps a default as a separately named constraint the catalog
does not report, so an existing column's default cannot be changed here.
- **MySQL and MariaDB** need a new foreign key's referenced columns spelled
out.
- **Db2** puts a table into *reorg pending* after a changed type or
nullability or a dropped column; rudbman ends such a batch with
`CALL SYSPROC.ADMIN_CMD('REORG TABLE …')` so the table takes writes again.
Not supported anywhere: adding a constraint or an index to an existing table,
dropping a table, reordering columns, and check constraints.
## ERD diagrams
**ERD diagram** (Ctrl+E in the explorer, or the menus)
draws every table of the schema or catalog the selection sits in, joined by
their foreign keys, in a tab named "ERD — *schema*". Asked for again, the open
diagram comes to the front.

- Each box lists the table's columns with their types; primary-key columns
and foreign-key columns are drawn in colors of their own. Views are not
drawn, and a foreign key to a table outside the schema has no line.
- A large schema says how many tables' keys have been read, with **Cancel**;
**Refresh** starts it again.
- Tables are placed by a hierarchical layout and joined by routed,
right-angled lines. Drag a table to move it: the position is saved for the
profile and the schema, and comes back next time. **Arrange**
(Ctrl+Shift+A) lays everything out again.
- **Physical** / **Logical** switches the boxes between the names and the
comments the catalog carries (Ctrl+Shift+L).
The choice is kept for the next diagram.
- Drag the background to pan; the wheel scrolls, Shift+wheel
scrolls sideways and Ctrl+wheel zooms.
Ctrl+= / - / 0 zoom in, out and
back to actual size.
- **Export SVG…** writes the diagram to a file.
- Right-click a table for **Open details**, which opens its detail panel; the
canvas's menu also has **Arrange**, **Logical names**, the zoom commands,
**Export SVG…** and **Refresh**.
## The query builder
**New query builder** (the ☰ menu or a connection tab's menu) opens an empty
canvas, **Builder *n***. **Add to query builder** on a table or view puts it
on the builder in front, or the first one open, opening one if there is none.
You can also drag tables and views from the explorer onto the canvas.

- **Drag a table by its title** to move it. A table added twice gets an alias
(`ORDERS_2`), which is how a self-join is built.
- **Click a column** on the canvas to add it to the select list, or click it
again to take it out. With nothing picked, the statement is `SELECT *`.
- **Drag a column onto a column of another table** to join them, or pick the
two columns in the **Joins** form, which appears once two tables are on the
canvas, and press **Add join**. A join starts as **INNER JOIN** and can be
changed to **LEFT JOIN**, **RIGHT JOIN** or **FULL JOIN**. Tables with no
join between them are listed with a comma.
- **Conditions** takes `WHERE` conditions as text (`id > 1000`), combined with
`AND`.
- Under **Selected columns**, each column can be grouped (**Group**) and
sorted (**Unsorted**, **Ascending**, **Descending**).
- **Statement** previews the `SELECT` as you go, with identifiers quoted as
the dialect wants them. **Open in editor** sends it to a new query tab,
without running it.
- Right-click a table for **Remove table**, which takes its joins and picked
columns with it, and a column for **Add to the select list** / **Remove from
the select list**.
The builder writes plain selects: aggregates, `DISTINCT`, row limits and
column aliases are added in the editor afterwards. The canvas and the form say
which gesture to use until each has been used. Builders — tables, positions,
joins, columns and conditions — are kept with the workspace.
## Extracting a script
**Extract script…** on a table or view (the explorer's menu or the ☰ menu)
writes it out to a file. The form starts from its defaults each time.
| Option | Default | Notes |
| --- | --- | --- |
| **Output file** | — | **Browse…** picks it, suggesting `