Install and first launch

Download dbdesk from dbdesk.org, or from the releases page: pick the file for your system from the latest release’s Assets.

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.

Windows

1. Run dbdesk-<version>-windows-x64-setup.exe. Your browser may first say the file isn’t commonly downloaded; choose to keep it.
2. The first time you run it, Microsoft Defender SmartScreen blocks it: a blue window says “Windows protected your PC” and offers only Don’t run. This is expected. The installer isn’t signed yet, and SmartScreen holds back programs it hasn’t seen downloaded often. To go on, click More info. The window then shows the file’s name and “Unknown publisher”. Check that the name is the file you downloaded from dbdesk.org or the releases page, then click Run anyway.
3. Follow the installer. It installs dbdesk for your user alone, in %LOCALAPPDATA%\dbdesk, without asking for administrator rights, and adds dbdesk to the Start menu.

SmartScreen asks again for each new installer you download yourself, until dbdesk’s installers are signed and known to it. Updates that dbdesk installs (below) run without the warning. On Windows 11 with Smart App Control switched on (in Windows Security › App & browser control), Windows may block the unsigned installer with no Run anyway at all, and dbdesk can’t get round that until it is signed. To remove dbdesk, use Settings › Apps › Installed apps. Saved passwords go to the Windows Credential Manager.

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

On Windows, in PowerShell, print the installer’s checksum and compare it with its line in SHA256SUMS:

Get-FileHash dbdesk-*-windows-x64-setup.exe -Algorithm SHA256

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.5.0 is available. Click it to open Updates; Help › Check for updates… asks at any time.

• macOS, and the Linux AppImage: click Install and restart. dbdesk downloads the new version, checks that it was signed by the dbdesk release process, and puts it in place of the one you are running. Click Restart now to start it, or carry on and it starts next time. If a console has a transaction open, quitting asks first, as it always does.
• Windows, installed with the installer: click Install and restart. dbdesk downloads the new version’s installer and checks its signature in the same way; the dialog then says the update is downloaded. Click Restart now: dbdesk quits (asking first about open transactions), the installer shows a progress bar while it replaces dbdesk, and the new version starts. Windows can’t replace a program that is running, so if you carry on instead, the update waits until you choose Restart now, or is downloaded again next time. The installer closes any other dbdesk window that is still open.
• The .deb, a Windows copy that wasn’t installed with the installer, and builds from source: these can’t replace themselves, and the dialog says why. Open release page leads to the download; install it as above. Copies installed on Windows from version 0.12.0 or earlier are in this group too: install the next version from the release page once, and it updates itself from then on.

An update that isn’t signed with dbdesk’s key is refused before anything is replaced. On macOS, until dbdesk’s builds are signed by Apple, the first launch after an update asks again for access to each saved password; choose Always Allow.

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.

On a Mac

On macOS dbdesk’s menus are in the menu bar at the top of the screen, like any Mac app’s, and the window has no separate title bar. On Linux and Windows the menus are in the window, under its title bar, and this manual names them that way (View → Settings…). On a Mac a few of them live where Mac apps keep them:

The rest of the Mac’s menu bar:

• dbdesk → Quit dbdesk (⌘Q) quits the way closing the window does: if a console has an open transaction or unsaved changes, dbdesk asks first. Hide, Hide Others, Show All and Services are the usual ones.
• Edit has Undo, Redo, Cut, Copy, Paste and Select All for whatever has focus: the SQL editor, a text field, or the results grid (Copy copies the selected cells).
• View → Enter Full Screen (⌃⌘F), and Window with Minimize (⌘M), Zoom and Bring All to Front.
• Help → dbdesk manual opens this manual, and the Help menu’s search finds any menu item.

Items that need a console, such as File → Save or Code → Format, are greyed out until a console’s tab is selected, and every item shows its shortcut, including ones you changed in keymap.toml (see Keyboard shortcuts).

The strip along the top of the window, beside the close, minimize and zoom buttons, works as a title bar: drag it to move the window, and double-click it to zoom.

dbdesk also takes the Mac’s look: text is in the system font, SF Pro (SF Mono for SQL and results), and selected text, cells and rows are tinted with the accent colour chosen in System Settings → Appearance. Change the accent colour and dbdesk follows it when you come back to its window. The pictures in this manual were taken with dbdesk’s own fonts and colours, which it uses on Linux and Windows.