Introduction

dbdesk is a desktop tool to browse and query databases. It connects to PostgreSQL and SQLite (more engines, such as MySQL, ClickHouse and Oracle, are planned), shows what is inside them as a tree, and gives you query consoles to write and run SQL, page through, sort and export the results, and edit rows.

The window has three areas, which you can drag around and resize:

• Explorer, a column down the left: your saved connections (“data sources”) and, under each, its databases, schemas, tables and so on.
• Consoles, the main area on the right: the Welcome tab and one tab per query console.
• Log console, under the consoles: what dbdesk is doing — connections opening and closing, queries running and how long they took, errors.

The thin bar at the very bottom shows whether dbdesk’s background engine is running and how many data sources the explorer is connected to.

This manual describes dbdesk as it is today. It is young software: things that are planned but not built yet are not described here, apart from a few warnings in Troubleshooting.

Install and first launch

Download dbdesk from the releases page: pick the file for your system from the latest release’s Assets. Until the first release is published, the page is empty; build from source instead (see the end of this page).

Windows builds are on the way: they’re built for every release but only offered once they’ve been tried on a real Windows machine.

macOS

1. Open the .dmg and drag dbdesk onto Applications.
2. Open dbdesk from Applications. These builds aren’t signed by Apple yet, so the first launch is blocked with “Apple could not verify dbdesk”.
3. Open System Settings › Privacy & Security, scroll down to the message about dbdesk, and click Open Anyway. macOS asks once more; confirm, and it opens normally from then on.

After each update, macOS asks again for access to each password dbdesk saved in the Keychain. Choose Always Allow. This happens because the app’s signature changes with every unsigned build; signed builds, planned for a later release, will remove both steps.

Linux

AppImage, on any distribution:

chmod +x dbdesk-*-x86_64.AppImage
./dbdesk-*-x86_64.AppImage

.deb, on Debian, Ubuntu and derivatives. This also adds dbdesk to the application menu:

sudo apt install ./dbdesk_*_amd64.deb

Saved passwords go to the Secret Service (GNOME Keyring, KWallet), which desktop environments already run. On a bare window manager without one, see Troubleshooting.

Check the download and the version

Each release has a SHA256SUMS file. In the folder with your download:

shasum -a 256 -c SHA256SUMS --ignore-missing

Help › About dbdesk shows the version and the commit it was built from, and Copy version copies them for a bug report. From a terminal, dbdesk --version prints the same.

Updates

When dbdesk starts, it asks GitHub whether a newer release is out. If one is, the status bar says so, for example dbdesk 0.2.0 is available; click it, then Open release page to download the new version and install it as above. Help › Check for updates… asks at any time.

dbdesk doesn’t update itself yet, and the check sends nothing about you or your data: it reads the public list of releases. To stop the check at start-up, untick Check for a new release when dbdesk starts in View → Settings….

Build from source

For contributors, or to run the latest unreleased code. You need:

• Rust 1.95 or newer, installed with rustup. Check with rustc --version.

• Git, to fetch the source.

• On Linux, the development headers for the windowing system. On Debian or Ubuntu:

  sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev
  

Then:

git clone https://github.com/navasvarela/dbdesk.git
cd dbdesk
cargo run --release -p dbdesk-app

To install the dbdesk command so you can start it from anywhere:

cargo install --path crates/dbdesk-app

First launch

On first launch the explorer is empty (“No data sources yet”) and the Welcome tab offers three things to do:

• New data source — add a connection to a database. See Data sources.
• New query console — open a console on a data source. It is greyed out until you have one.
• Open the manual — opens this manual in your browser.

The log console under the Welcome tab shows engine started, and the status bar reads Engine running · 0 connected. If it says the engine is stopped, see Troubleshooting.

Light and dark

dbdesk follows your system’s light or dark setting. To choose one yourself, open View → Theme and pick Match system, Light or Dark. The choice is remembered.

The layout

dbdesk opens maximized the first time; after that it remembers the window’s size and position.

Every panel is a tab you can drag: onto another panel’s tab bar to join it, or onto the edge of a panel to split it. Drag the gaps between panels to resize them. dbdesk remembers the layout and the window size when you quit. View → Reset layout puts everything back where it started.

Data sources

A data source is a saved connection: which database to connect to and how. dbdesk keeps the list in a file (see Where dbdesk keeps its files) and passwords in your system’s keychain, never in that file.

Adding one

Click + at the top of the explorer (or New data source on the Welcome tab) and choose PostgreSQL, SQLite or MySQL / MariaDB.

Every kind has:

• Name — how it appears in the explorer. Leave it empty and dbdesk names it for you: database@host for a server, the file name for SQLite.
• Colour — optional. The colour tints the data source’s row in the explorer, the tabs of its consoles and a band along the top of each console. Giving production a red and your local copy nothing makes it hard to run something in the wrong place.

PostgreSQL adds:

TLS

TLS encrypts the connection, which hosted databases usually require. The modes are the ones PostgreSQL’s own tools call sslmode, so a provider’s connection guide reads the same:

prefer and require keep anyone on the network from reading what you send, but not from pretending to be the server. Use verify-full for anything that matters.

With verify-full, a CA file row appears. Leave it empty for servers whose certificate is signed by a public authority (the same ones web browsers trust). For a private or self-signed certificate, give the authority’s certificate as a PEM file, typed or picked with Browse…: for example the bundle your cloud provider publishes for its managed databases. The Host must be a name (or IP address) the certificate lists.

dbdesk encrypts with rustls, so there is no OpenSSL to install. Client certificates aren’t supported yet.

MySQL / MariaDB has the same fields as PostgreSQL, with these defaults:

One data source type serves both: dbdesk tells MySQL and MariaDB apart once it connects, and Test connection says which it found (“Connected to MariaDB 11.4.4”).

SQLite adds:

• File — the full path to the database file. Type or paste it, or use the buttons under the field:

  • Browse… opens your system’s file dialog to pick an existing database. It shows every file, because SQLite databases end in .db, .sqlite, .sqlite3 or nothing at all.
  • New… opens your system’s Save dialog and creates an empty database file where you choose, then fills in the path and clears Read-only. The message under the form says whether it worked; click Save to keep the data source. dbdesk never overwrites an existing file, even if the Save dialog asked whether to replace it and you said yes: pick another name instead.

  Connecting never creates a file, so a typo in the path is an error rather than a new, empty database. New… is the only way dbdesk creates one.

• Read-only — opens the file read-only. Statements that would change it fail with SQLite’s error.

Testing the connection

Test connection connects with what is in the form right now, checks the connection works, and disconnects. The result appears under the form (“Connected to PostgreSQL 17.6”, or the error) and in the log console. Nothing is saved by testing, not even the password.

Saving

Save checks the form and saves the data source. Required fields left empty, or a port that isn’t a number, show a message under the form instead. The dialog stays open until the save has gone through; if it fails, the reason is shown in the dialog.

Cancel, Esc or a click outside the dialog closes it without saving.

Passwords and the keychain

PostgreSQL passwords are stored in your operating system’s credential store: the Keychain on macOS, Credential Manager on Windows, the Secret Service (GNOME Keyring, KWallet) on Linux. Each entry has the service name dbdesk and, as its account, the data source’s ID, a long string that never changes even if you rename the data source.

• When you save, a typed password is written to the keychain. When you edit a data source the password field is empty and says unchanged: leave it empty to keep the saved password, or type a new one to replace it.
• When dbdesk connects — the explorer, each console, and Test connection with an empty password field — it reads the password from the keychain. On macOS the system may ask whether to let dbdesk use it; see Troubleshooting.
• When you delete a data source, its keychain entry is removed too.

SQLite data sources have no password, so dbdesk never asks the keychain for them.

Editing, connecting and deleting

Right-click a data source in the explorer for:

Hover over a data source to see its driver, where it connects to and its connection state. The dot after its name shows the state of the explorer’s connection: amber while connecting, green when connected, red when the last attempt failed, and no dot when disconnected. A failed connection’s error is in the tooltip and in the log console.

The explorer

The explorer shows each data source as a tree. Nothing is loaded until you open it: expanding a node asks the database for that node’s children, and a spinner shows while it waits. Expanding a data source that isn’t connected connects it first.

Click the arrow before a node, or double-click its name, to expand or collapse it.

What the tree contains

PostgreSQL

data source
└─ database               every database on the server that accepts connections
   └─ schema
      ├─ tables
      │  └─ table
      │     ├─ columns    with their type, "not null" and "primary key"
      │     ├─ indexes
      │     ├─ constraints
      │     └─ triggers
      ├─ views
      ├─ materialized views
      ├─ functions        with their argument types, so overloads are told apart
      └─ sequences

SQLite

data source
└─ main
   ├─ tables
   │  └─ table
   │     ├─ columns
   │     ├─ indexes
   │     ├─ constraints   primary and foreign keys
   │     └─ triggers
   └─ views

MySQL and MariaDB, where a database and a schema are the same thing:

data source
└─ database               every database you may see, shown as a schema
   ├─ tables
   │  └─ table
   │     ├─ columns    with their type and "not null"
   │     ├─ indexes    with their columns, and whether they are unique
   │     ├─ constraints
   │     └─ triggers
   ├─ views
   ├─ functions
   ├─ procedures
   └─ events          scheduled with CREATE EVENT

Each kind of object has its own icon and colour, and folders that have been loaded show how many objects they hold (tables 5).

Browsing another PostgreSQL database than the one in the data source’s settings opens a separate connection to that database.

The context menu

Right-click an object for what you can do with it:

A data source’s own menu (Connect, New query console, Open saved console, Edit, Delete and so on) is described in Data sources.

Definitions

Show definition opens a window with the object’s SQL, which you can select and copy with the Copy button.

Which objects have one depends on the database:

• PostgreSQL: views, materialized views, functions, indexes, constraints and triggers.
• SQLite: tables, views, triggers, and indexes created with CREATE INDEX (not the ones SQLite makes for primary keys and unique constraints).
• MySQL and MariaDB: tables, views, functions, procedures, events and triggers, as SHOW CREATE … gives them. A routine whose source you may run but not read shows a message instead.

Filtering

Type in the box at the top of the explorer to filter the tree by name, ignoring case. An object that matches is shown with everything under it, and the nodes leading to it stay open even if they don’t match themselves.

The filter only searches what has already been loaded: it never asks the database for more. Expand the parts you want to search first.

System objects

PostgreSQL’s pg_catalog, information_schema and temporary schemas, SQLite’s internal sqlite_ tables, and MySQL’s mysql, information_schema, performance_schema and sys databases are hidden. The eye button next to + shows or hides them, for every data source at once.

When the connection closes

Disconnecting, or losing the connection, forgets everything the explorer had loaded for that data source. It is loaded again, fresh, the next time you expand it. Refresh does the same for a single node while connected, which is how you see a table you just created.

Query consoles

A query console is a SQL editor tied to one data source, with the results of its latest run underneath.

Opening a console

• Right-click a data source in the explorer and choose New query console, or use the New query console card on the Welcome tab.
• Right-click a table, view or materialized view and choose Open data: this opens a console with SELECT * FROM that object and runs it straight away.
• Right-click a data source and choose Open saved console to reopen one you closed (see below).

Consoles open as tabs next to the Welcome tab, named after their data source. A second console on the same data source is named shop (2), and so on. If the data source has a colour, the tab and a band along the top of the console carry it.

Each console has its own connection, separate from the explorer’s and from other consoles’, so a long query in one tab never blocks another. It connects the first time you run something (“Connecting…” in the toolbar), and closing the console’s tab closes the connection.

Consoles are saved

Every console is a file, consoles/<data source id>/console.sql (then console_2.sql, and so on; see Where dbdesk keeps its files). dbdesk writes your text a second after you stop typing, and when you quit. Open consoles reopen with their text the next time you start dbdesk.

Closing a console keeps its file if you typed anything in it, and deletes it otherwise (an empty console, or one opened by Open data and left as it was). Kept consoles are listed under Open saved console in their data source’s context menu. If a console can’t be saved, its toolbar says Not saved, with the reason on hover.

The editor

The editor highlights SQL keywords, strings, numbers, comments and quoted names, numbers the lines, and gives the statement that Run would run a faint background.

Completion. Typing a name, or a ., opens a list of suggestions at the cursor; ⌃Space opens it anywhere. Use ↑ and ↓ to pick, Enter or Tab to accept, Esc to close.

It suggests what fits where the cursor is:

• after alias. or table., that table’s columns; after schema., that schema’s tables;
• after FROM, JOIN, UPDATE or INTO, tables and views;
• after SELECT, WHERE, ON, GROUP BY, ORDER BY or SET, the columns of the tables the statement uses, their aliases, and functions;
• inside INSERT INTO orders (…), the columns of orders.

The statement’s own names count too: aliases, WITH queries (CTEs) and subqueries in FROM, with the columns they return. Functions come with their parentheses, the cursor between them. Each suggestion shows an icon for what it is and, for a column, its type.

You don’t have to type the start of a name: cid finds customer_id, matching the first letters of its words. Names that start with what you typed come first, and the ones you picked lately come before the rest.

Names come from what the explorer has loaded for the data source. When a suggestion needs a part that isn’t loaded yet, dbdesk loads it in the background (the list says “Loading the catalog…”), which connects the explorer if it wasn’t.

Formatting. ⌥⌘L (or Format in the toolbar, or Code → Format) lays out the selected text, or the statement at the cursor; ⇧⌥⌘L (Code → Format all) formats every statement in the console:

SELECT
    id,
    name
FROM users u
JOIN orders o ON o.user_id = u.id
WHERE u.active
    AND o.total > 10
ORDER BY name

Each clause starts a line, lists of several items put one per line, and every AND or OR of a WHERE starts a line. Subqueries are indented inside their parentheses. Statements that aren’t queries, such as CREATE FUNCTION, keep their line breaks; a CREATE TABLE gets one column per line.

Formatting only changes spaces, line breaks and the case of keywords. Strings, comments, quoted names and function bodies between $$ are never touched, and dbdesk checks the result before using it: if it would read differently to the database, the text stays as it was and the toolbar says Not formatted. The cursor stays where it was in the SQL, and ⌘Z undoes the whole format at once.

Problems while typing. A moment after you stop typing, dbdesk underlines mistakes: a red wave for errors (SQL the database can’t read), an amber one for warnings (SQL that runs but probably doesn’t do what you meant). Hover over one to read it. The toolbar counts them; click the count, or press F8 (⇧F8 for the previous one), to move the cursor to the next.

Warnings point out:

• = NULL or <> NULL, which are never true: write IS NULL or IS NOT NULL;
• UPDATE or DELETE without WHERE, which change every row;
• INSERT … SELECT *, which depends on the column order of the source;
• a table, or alias.column, the explorer has loaded and doesn’t have. These only appear for parts of the catalog the explorer has already loaded, so expand the data source to get them.

Only queries and data changes (SELECT, INSERT, UPDATE, DELETE, WITH, VALUES) are checked for syntax: dbdesk would rather miss an error in a CREATE FUNCTION than flag one that isn’t there. Once a console has run something, its own connection also asks the database whether it would accept each statement, without running it, so the database’s own messages show up too (“The database says: …”). This never happens while results are still loading or a transaction is open.

View → Settings… switches each kind of warning off, and asking the database too.

View → Settings… chooses how keywords are written (UPPER, lower, or as you typed them) and how many spaces each level is indented. They’re saved in settings.toml (see Where dbdesk keeps its files).

Running SQL

The toolbar’s buttons, and their shortcuts while the editor has focus:

On Linux and Windows, use Ctrl instead of ⌘. Hover over a button to see its current shortcut; all of them can be changed (see Keyboard shortcuts).

Which statement is “at the cursor”? dbdesk splits the text into statements at semicolons, the way the database would: semicolons inside strings, quoted names, comments, PostgreSQL’s dollar-quoted function bodies, and BEGIN … END or CASE … END blocks don’t end a statement. The statement at the cursor is the one the cursor is in, or the one just before it, so you can press ⌘↵ with the cursor right after a semicolon.

On MySQL and MariaDB, scripts can change what ends a statement with DELIMITER, as the mysql client does, so a procedure’s body can hold semicolons:

DELIMITER //
CREATE PROCEDURE touch(n INT)
BEGIN
  UPDATE items SET price = price + 1 WHERE id = n;
END//
DELIMITER ;

The DELIMITER lines are dbdesk’s to read and are never sent. MySQL’s own quoting applies too: "text" is a string, as it is without ANSI_QUOTES, names are quoted with backticks, and a backslash inside a string escapes the next character.

The toolbar shows how the last run went: Done in 12 ms, Failed or Cancelled. While a statement runs, Run, Run all and Explain are disabled.

Transactions

Below the toolbar, each console has a transaction mode:

• Auto-commit (the default): every statement is committed as soon as it succeeds, unless you start a transaction yourself with BEGIN.
• Manual commit: dbdesk starts a transaction before your first statement, and changes stay pending until you click Commit or Rollback.

While a transaction is open, the console says ● Transaction open, in either mode, and you can’t switch modes. On PostgreSQL, a statement that fails inside a transaction leaves it ● Transaction failed: the database then only accepts a rollback.

Closing a console, disconnecting its data source or quitting dbdesk with a transaction open asks whether to roll it back first. Closing the connection is what rolls it back.

Results

Under the editor, a summary line describes the result, followed by the rows:

• 8 rows · 3 ms for a query,
• 12 rows affected · 4 ms for INSERT, UPDATE, DELETE, MERGE, REPLACE and COPY,
• Done · 2 ms for anything else, such as CREATE TABLE,
• or the error message, in red.

Drag the line between the editor and the results to give either more room.

In the grid, numbers are right-aligned and NULL is shown in grey italics, so it can’t be mistaken for the text “NULL”. Drag the edges of a column header to resize it. Hovering over a column header shows the column’s type when the database reports it (SQLite does; PostgreSQL doesn’t, yet).

• Selecting and copying. Click a cell to select it; shift-click or drag to select a block. ⌘C (while no text field has focus) copies the selection, tab-separated, ready to paste into a spreadsheet. Right-click a cell for Copy selection, Copy value, Copy row and View value.
• Viewing a long value. Double-click a cell, or select it and press Space, to see the whole value in a window. JSON is shown indented; Copy copies it as stored.
• Sorting and filtering. Click a column header to sort by it (ascending, descending, off), and type in Filter loaded rows to keep the rows with a cell containing the text. Both work on the rows loaded so far, without asking the database again, and the grid says so.
• Exporting. Export → CSV… or JSON… saves the rows as shown, sorted and filtered, to a file you pick. Only loaded rows are exported.

Large results

Rows arrive 500 at a time. When there are more, the summary says so, and you get the next 500 by clicking Load more rows or by scrolling to the bottom of the grid.

A query that is still sending rows keeps its connection busy. Cancel discards the rows that haven’t been loaded (the summary then says rest discarded), and so does running something else in the same console.

Several statements

When a run includes more than one statement, numbered tabs above the summary pick which statement’s result to show. dbdesk shows the latest one that returned rows, or the one that failed; failed statements’ tabs are red. Hover over a tab to see its statement.

Editing data

You can change values in the grid when the result is a SELECT from a single table (no joins, GROUP BY or DISTINCT), the table has a primary key, and the result includes the key’s columns. Otherwise the grid says Read-only; hover over it to see why.

• Double-click a cell, or select it and press F2 or Enter, to edit it. Enter or a click elsewhere keeps the new text; Esc drops it. Set NULL in the cell’s menu sets NULL (emptying a cell gives an empty string, not NULL).
• Changed cells are tinted. Submit writes them, one UPDATE per changed row, all or none; Revert forgets them.
• If a row changed or disappeared since it was loaded, or a value doesn’t fit its column, nothing is written, your changes stay, and the error names the row.
• In manual commit mode, submitted changes join the open transaction and stay pending until you commit.

Values are sent as text and converted by the database, so type them the way the grid shows them (t for a PostgreSQL boolean, {1,2} for an array).

History

Every statement a console runs is recorded with its time, duration, row count and outcome. History in the toolbar lists the data source’s statements, newest first; type to search them, and click Insert (or double-click) to put one into the console on a line of its own.

Errors

When a statement fails, its error appears in red in the summary line and in the log console. If the database says where in the statement the error is, the editor underlines that spot in red until you edit the text. PostgreSQL reports a position for most errors; SQLite only for syntax errors.

With Run all, the statements before the failing one have already run (and, in auto-commit mode, are committed); the ones after it don’t run at all.

Statements that change every row

Before running an UPDATE or a DELETE without a WHERE, dbdesk asks first:

Nothing in the run starts until you answer: Run anyway runs everything as asked, Cancel runs nothing. The check looks at how each statement starts, so a DELETE inside a WITH query isn’t caught.

On MySQL and MariaDB, the same dialog warns before a statement that commits by itself (CREATE, ALTER, DROP, RENAME, TRUNCATE, GRANT, REVOKE) when you might be counting on Rollback: in Manual commit mode, or with a transaction open. MySQL commits such a statement at once, together with whatever the transaction held, so Rollback can’t undo either. Temporary tables are the exception, and don’t get the warning.

Keyboard shortcuts

On Linux and Windows, read Ctrl wherever this page says ⌘.

Defaults

Console shortcuts are taken before the editor sees them, so ⌘↵ runs a statement instead of inserting a new line. History, Commit and Rollback have no shortcut by default.

Changing them

Shortcuts live in keymap.toml, next to data_sources.toml (see Where dbdesk keeps its files). View → Keymap… lists every action with its id, its shortcuts and what it does, and has two buttons:

• Create keymap.toml writes a file listing every action with its default, commented out. It never replaces a file that exists.
• Reload applies your edits without restarting dbdesk.

In the file, list only the actions you want to change:

[bindings]
"console.run" = "cmd+r"                    # one shortcut
"console.explain" = ["cmd+alt+e", "f5"]    # or several
"console.cancel" = []                      # or none

A shortcut is modifiers and a key joined by +, ignoring case. cmd is ⌘ on macOS and Ctrl elsewhere; ctrl is the Control key everywhere; alt (or option) and shift are what they say. Keys are letters, digits, enter, space, tab, escape, f1 to f35, period, comma, pagedown and so on, or the character itself (cmd+.).

A mistake doesn’t cost you the rest of the file: an unknown action, a shortcut that can’t be read, or one that two actions share, is skipped and listed as a problem in the Keymap window, and the status bar shows keymap.toml: N problems. A file that isn’t valid TOML keeps every default and shows why.

Editing text

The SQL editor and the other text fields use the usual editing keys:

Dialogs

Esc closes the data source dialog, the delete confirmation and the “Run anyway?” check without doing anything.

Where dbdesk keeps its files

dbdesk keeps everything in one folder per platform:

Passwords are not in any of these files: they are in your system’s keychain, under the service name dbdesk. See Data sources.

data_sources.toml

You can edit this file by hand while dbdesk is closed. dbdesk reads it at start-up and rewrites it every time you save or delete a data source, so changes made while it runs are overwritten, and comments are not kept.

[[data_source]]
id = "6f1c0d9e-3b8a-4c3e-9f57-2d1e8a7b5c40"
name = "local"
color = "teal"
driver = "postgres"
host = "localhost"
port = 5432
database = "app"
user = "juan"

[[data_source]]
id = "b3c9e1f2-7a4d-4b8e-9c2f-1d5e6a7b8c90"
name = "production"
color = "red"
driver = "postgres"
host = "db.example.com"
port = 5432
database = "app"
user = "juan"

[data_source.tls]
mode = "verify-full"
ca_file = "/Users/juan/certs/example-ca.pem"

[[data_source]]
id = "0b6a4f8e-91d2-4e7a-a1c3-5f0e2d9b7c18"
name = "chinook.db"
driver = "sqlite"
path = "/Users/juan/data/chinook.db"
read_only = true

• id identifies the data source for good, including its keychain entry. Don’t change it; for a new data source by hand, any unique UUID will do.
• color is optional: red, orange, yellow, green, teal, blue, violet or pink.
• tls is optional for PostgreSQL, and mode defaults to prefer: disable, prefer, require or verify-full. ca_file is only read with verify-full.
• read_only is optional and defaults to false.

If the file can’t be read — say, a typo while editing it — the explorer shows the error and dbdesk refuses to save or delete anything, so it never overwrites your file with an empty list. Fix the file and restart dbdesk.

Starting over

To reset the layout, use View → Reset layout. To go back to the default shortcuts, delete keymap.toml and click Reload in View → Keymap…; for the default settings, delete settings.toml and click Reload in View → Settings…. To forget everything, quit dbdesk and delete its folders; the passwords stay in the keychain until you delete the dbdesk entries there too.

Troubleshooting

Where to look first

The log console, under the consoles, shows what dbdesk did and what went wrong, with the newest entries at the bottom. The drop-down on its left picks how much detail to show (Error, Warn, Info, Debug, Trace); the search box filters entries by text; the bin icon clears the list. It keeps the latest 10,000 entries.

The same entries, from dbdesk itself and warnings from the libraries it uses, go to a log file per day: see Where dbdesk keeps its files. Attach the day’s file when you report a problem; it never contains passwords.

TLS/SSL errors

The data source’s TLS setting decides whether dbdesk encrypts the connection (see Data sources). The usual errors, and what to change:

• pg_hba.conf rejects connection … no encryption (or no pg_hba.conf entry … SSL off): the server only accepts encrypted connections and TLS is disable. Pick require or, better, verify-full.
• server does not support TLS: TLS is require or verify-full, but the server has encryption turned off. Pick prefer or disable if the network is one you trust, such as a database in a local container, or turn TLS on in the server.
• invalid peer certificate: UnknownIssuer: with verify-full, the certificate isn’t signed by an authority dbdesk trusts. Set CA file to your provider’s or your company’s authority certificate (a PEM file).
• certificate not valid for name …; certificate is only valid for …: with verify-full, the certificate doesn’t list the Host you typed. Use one of the names the message lists, often the one in the provider’s connection string, instead of an IP address or an alias.
• could not read the CA file … or … holds no usable certificate: the CA file is missing, or isn’t a PEM file with a certificate in it (-----BEGIN CERTIFICATE-----).

Don’t turn off encryption on a server just for dbdesk.

The keychain keeps asking

On macOS, the system asks whether dbdesk may use the password it saved in your keychain the first time dbdesk reads it. Always Allow stops the questions, but macOS ties that answer to the exact program. Because you build dbdesk yourself, every rebuild is a new program to macOS, and it asks again.

dbdesk reads the password each time it opens a connection: when the explorer connects, when a console runs its first statement, and when you test a connection without typing the password. If you deny access, the connection fails with could not read the saved password.

To see or delete the saved passwords, open Keychain Access and search for dbdesk. Each entry’s account is the ID of a data source in data_sources.toml.

On Linux, dbdesk needs a running Secret Service (GNOME Keyring or KWallet) to save passwords. Without one, saving a PostgreSQL data source with a password fails with could not store the password.

A connection takes long, then fails

dbdesk gives up on a connection attempt after 15 seconds and reports could not connect within 15s. Check the host and port, and that nothing (a VPN, a firewall) is in the way. Test connection in the data source dialog is the quickest way to try again.

“unable to open database file” for SQLite

The file in the data source’s File field doesn’t exist, or dbdesk can’t read it. Connecting never creates a SQLite file, so check the path, or pick the file with Browse… in the data source dialog. To start a new database, use New… there (see Data sources).

“Can’t read data sources”

data_sources.toml exists but isn’t valid, usually after editing it by hand. dbdesk shows the error in the explorer and refuses to change the file until it is fixed, so nothing is lost. Correct the file (the error says which line), then restart dbdesk.

The status bar says the engine stopped

The engine is the part of dbdesk that talks to databases. If it stops, nothing can connect or run, and the reason is in the log console and the log file. Restart dbdesk; if it happens again, please report it with the day’s log file.

“keymap.toml: N problems” in the status bar

Some lines of keymap.toml couldn’t be used: an unknown action, a shortcut that can’t be read, or a shortcut two actions share. Click the message to open View → Keymap…, which lists each problem; fix the file and click Reload. Everything else in the file still applies.

The panels are in a mess

View → Reset layout puts every panel back where it started. If you closed the Welcome tab, this brings it back too.