Database
Free & PremiumThe Database window (⌘5) shows your databases as a tree: source, database, table. Sources are WebDonkey's database servers, your own local connections and, with Premium, databases on your servers. Tables, structure and SQL console open as tabs in the editor area. There you look at data, edit rows, change the structure, run SQL and export results.
What you do here
- Connect a database server on your Mac that WebDonkey does not run: Local connections.
- Look at a table, filter, sort, change rows, follow foreign keys: Data.
- Change columns and indexes, create, rename and delete tables: Structure.
- Run queries: SQL console.
- Save or copy tables and results: Export.
Layout of the window
At the top are three buttons: New SQL console (opens a console on the site's database, otherwise on the first running source), Add database (+, for databases on servers, Premium) and Refresh. Below them the tree in sections:
| Section | Contents |
|---|---|
| Site … | The database of the WebDonkey site your project belongs to, if WebDonkey knows one. |
| WebDonkey | WebDonkey's own database servers (MySQL, MariaDB, PostgreSQL) with their version. A stopped server shows "not running" and cannot be unfolded. |
| Local | Your own local connections, with + for Add local connection. |
| Remote | Databases on servers, each under its SSH connection and in the same folders as in WebDonkey's connection list. With the notice for working on servers. |
A database shows its size, a table its number of rows. Views have an eye icon. Clicking a table opens it as a preview tab, a double-click as a regular tab. A folder shows how many databases it holds and folds open and shut. What you unfolded and which table you opened last, the editor remembers per project.
Context menus
| Right-click on | Entries |
|---|---|
| Server (SSH connection) | Add database …, Disconnect |
| Source | New SQL console, Refresh, for server databases Disconnect, Edit … and Remove, for your own local connections Edit … and Remove |
| Database | New SQL console, New table …, Refresh, Copy name |
| Table | Open table, Edit structure, SELECT … in new console, New table …, Rename …, Delete …, Copy name |
A server keeps its SSH connection once you opened one of its databases, until you cut it with Disconnect (plug icon on the server), for all of its databases at once.
Databases on servers
Add database opens WebDonkey's dialog: first the server (the SSH connection), then the access to the database, with Test access. They are the same entries as in WebDonkey, see Add a database in WebDonkey. Edit … and Remove in the context menu change them. Removing works like this: "Only the entry in WebDonkey and the editor is removed. Nothing is deleted on the server." When there are none yet, it says "No database on a server set up yet." with Add database.
If a connection is marked as production (red) in WebDonkey, every confirmation before a write names the target in red: "Production connection. This changes live data."
Without WebDonkey
Without WebDonkey the window works with the editor's own database: your local connections always work, databases on servers with your Premium key. WebDonkey's servers and the site's database only exist with WebDonkey.
Free and Premium
Local databases are free: WebDonkey's servers, the site's database and your own local connections, with everything that comes with them. Databases on servers are part of Premium. On Free they show locked in the list ("Remote databases are Premium"), and Add database is grey. Prices are on webdonkey.io/pricing.
The command palette (⌘K) has New SQL console and Show database window.
Local connections Free
If a database server runs on your Mac that WebDonkey does not run, from Homebrew, DBngin or Postgres.app for example, you add it as a local connection of your own. It then shows in the Database window under Local and can be browsed, edited and queried just like WebDonkey's own servers. Local connections are free and work without WebDonkey too.
Where to find it
Database window (⌘5), Local section. The + next to the heading is Add local connection. When there are none yet, it says "No local connection of your own yet." with the same button.
How to do it
- Click Add local connection.
- Pick the kind under Database: MySQL, MariaDB or PostgreSQL.
- Enter Host and Port. The defaults are
127.0.0.1and the kind's standard port (3306 for MySQL and MariaDB, 5432 for PostgreSQL). When you switch the kind, the port follows as long as you have not changed it yourself. - Or enter a Socket path (optional), for example
/tmp/mysql.sockfor MySQL and MariaDB or the socket folder/tmpfor PostgreSQL. When it is set, the editor connects through the socket instead of host and port, and those two fields are locked. - Enter Database user and Database password. The eye shows the password.
- Optional: Display name (optional). Without a name the connection is called something like
root@127.0.0.1:3306. - Click Test access. If it works, it says "Access works:" with the server's version.
- Save.
The connection now sits under Local, with user and address or the socket next to it. Unfold it to see its databases.
Edit and remove
- Right-click the connection, Edit …: the dialog Edit local connection opens with the saved values, the saved password filled in.
- Right-click, Remove: "Remove connection “…”?" Only the entry in the editor and its password in the keychain are removed. Nothing is deleted on the database server.
What happens in the background
- Name, kind, host, port, user and socket are kept by the editor in its app data folder, in a file only your user can read. The password lives only in the macOS keychain.
- The connections belong to the editor. WebDonkey does not see them.
- Tables, structure, SQL and export run through the same functions as for WebDonkey's servers.
Free and Premium
Free, with and without WebDonkey.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| An error at Test access | The server is not running, or port, user or password are wrong | Start the server, check the values. |
| Connecting through the socket fails | Wrong path | Look up the server's socket path, in its configuration for example. |
| The keychain denies access | macOS refused the request | Allow the keychain prompt. |
| "This database is no longer set up." | The connection was removed in the meantime | Reload the list with Refresh. |
See also
Data Free & Premium
A table's Data tab shows its rows. You filter with a WHERE condition, sort by clicking a column, change values right in the cell, add and delete rows, and follow a foreign key to the linked row.
Where to find it
In the Database window (⌘5) unfold source and database and click a table. A click opens it as a preview tab, a double-click or Open table in the context menu as a regular tab. At the top of the tab you switch between Data and Structure.
The bar above the table
| Element | What it does |
|---|---|
| Filter field "WHERE … (Enter applies, Esc clears)" | A condition without the word WHERE, for example order_date >= '2026-09-01'. ↩ applies it, Esc clears the field. |
| Refresh | Reads the rows again. |
| Add row (+) | Opens the form New row. Locked for views. |
| Delete row / Delete n rows (trash can) | Deletes the marked rows. |
| Export | Saves the table in a format of your choice, see Export. |
Look, sort, page
- The table loads 200 rows at a time. At the bottom you see which rows are shown and the total (with ≈ when the database only estimates). The arrows at the bottom right page forward and back.
- Clicking a column header sorts ascending, the second click descending, the third removes the sort.
- NULL is shown in italics as NULL.
- Drag column widths wider or narrower at the header.
- The arrow keys move from cell to cell. ⌘C copies the cell's value.
- You mark rows through the row numbers on the left: ⌘-click adds or removes, ⇧-click marks a range. Esc clears the marking.
Filter, sort and tab are remembered per table, for the last 40 tables you looked at.
Edit cells
- Double-click the cell, or select it and press ↩ or F2.
- Type the new value.
- ↩ or Tab saves, Esc or clicking elsewhere cancels.
Only what you typed, and only if it differs from the old value, is written. Values with line breaks open in a multi-line field, where ↩ adds a new line and ⌘↩ saves. A NULL cell stays NULL until you type something. To set a cell back to NULL, use Set to NULL in the context menu.
A cell's context menu
| Entry | What it does |
|---|---|
| Copy value (⌘C) | Copies the cell's value. |
| Copy row as / Copy n rows as | Copies the row or the marked rows in one of the export formats. |
| Filter by this value | Adds this value to the filter. |
| Exclude this value | Adds the opposite to the filter. |
| Set to NULL | Sets the cell to NULL. |
| Delete row / Delete n rows | Deletes after asking. |
If you right-click a row that is not marked, the menu applies to that row only, and it becomes the marked row.
Add and delete rows
- Add row opens New row. For each field you pick Value, NULL (for columns that allow NULL), Default or SQL expression (for example
NOW()). Fields you leave untouched stay out of the INSERT and get their default or NULL. Auto-increment columns are set to Default. - Delete row asks "Delete rows?" with the number of rows and "This cannot be undone."
Follow foreign keys
If a column belongs to a foreign key, every cell has a small arrow on the right. Its tooltip says "Go to the linked row in table.column". A click opens the linked table filtered to the row the key points at, even when it sits in another database. If that table is already open, the editor sets the filter there.
Read-only
A table without a primary or unique key is "read-only (no primary or unique key)", because the editor could not tell rows apart safely otherwise. If you try to add a row there, the dialog Rows cannot be added here explains why and offers Open structure (to add a primary key) or INSERT in console. Views are always read-only.
Free and Premium
Local databases are free, databases on servers are part of Premium.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| No structure yet | The table has no columns | Add columns. |
| Table not found | It was renamed or deleted | Create table or Refresh. |
| A cell cannot be edited | The table has no key or is a view | Add a primary key or change it with SQL. |
| A red message above the table | An error in the filter or the connection | Check the filter. |
See also
Structure Free & Premium
A table's Structure tab shows its columns, Indexes and Foreign keys, and it is the table's structure editor at the same time. You change columns and indexes in a draft without writing SQL. Nothing runs until you have reviewed and confirmed the generated SQL. This is also where you create new tables.
Where to find it
- The Structure tab in a table's tab.
- Right-click a table in the Database window: Edit structure.
- For a new table: New table … in the context menu of a database or table, or Create table on a database without tables.
Change columns and indexes
- Open the structure. The columns are listed with Column, Type, Null, Default, PK, AI, Extra and, for MySQL and MariaDB, Comment.
- Change what you need:
- Name and type right in the row.
- Null: whether the column allows NULL.
- Default: none, NULL, Value or SQL expression.
- PK: part of the primary key. AI: counts up by itself (auto-increment).
- Add column appends a new column. Delete column marks one for deletion, Restore takes that back.
- Under Indexes, Add index creates an index: its name, then "Click the columns in index order:", optionally unique. Delete index removes one.
- At the bottom it says how many changes the draft has ("3 changes" or "No changes"). Discard throws them away.
- Review SQL … opens "Change the structure of “…”?" with "This SQL runs exactly as shown:" and the SQL, warnings in red and the target (connection and database).
- Run executes it. The editor then reports "Structure changed", and the data reloads.
The Foreign keys are listed at the bottom for reference.
What the editor checks first
Before it generates SQL, the editor checks your input and marks errors, for example: name missing, name duplicated or with a character that is not allowed, type missing or invalid, NOT NULL together with a NULL default, auto-increment without an integer type, more than one auto-increment column on MySQL, an index without columns. Computed columns can only be renamed or deleted. Views cannot be restructured here.
Warnings before running
The review names consequences before anything happens, for example:
- "Column “…” will be deleted. Its data is gone afterwards."
- "“…”: … → … can shorten, round or garble values."
- A column becomes NOT NULL: what happens to existing NULL values depends on the database.
- "The primary key goes away. Without a key, rows can no longer be edited here."
- When renaming: queries and code using the old name stop working afterwards.
If data is lost along the way, you also have to tick "I understand that data will be lost."
Create a table
- New table … opens the tab New table with Table (the name) and, for PostgreSQL, Schema.
- Add columns and indexes as above.
- Create table … shows "Create table “…”?" with the SQL.
- Create. The editor reports "Table “…” created".
Rename and delete
- Rename … asks in the dialog Rename table for the new name ("New name for “…”") and then shows the SQL for confirmation. Queries and code using the old name stop working afterwards. The editor reports "The table is now called “…”".
- Delete … shows "Delete “…”?" with the SQL and asks you to type the table's name to confirm. Then Delete.
What happens in the background
While you edit, nothing runs against the database. Only the confirmed SQL goes to the server, exactly as shown in the dialog. On a connection marked as production in WebDonkey, the dialog also says in red "Production connection. This changes live data."
Free and Premium
Local databases are free, databases on servers are part of Premium.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Review SQL … is locked | The draft has errors or no changes | Fix the marked fields. |
| "Without the server's column definition (SHOW CREATE TABLE) this column cannot be changed safely" | The server does not return the definition | Make the change with SQL in the console. |
| The server reports an error when running | For example NULL values in a column that is to become NOT NULL | Clean up the data first, then run again. |
See also
SQL console Free & Premium
The SQL console runs queries against a database. It opens as a tab with an editor for your SQL at the top and the results below. Statements that change data only run after you confirm them.
Where to find it
- In the Database window (⌘5), New SQL console at the top: on the database of your project's site, otherwise on the first running source.
- Right-click a source or database: New SQL console.
- Right-click a table: SELECT … in new console opens the console with
SELECT * FROM … LIMIT 100;. - Command palette (⌘K): New SQL console.
The console's bar
At the top are the source's name and the Database select (or (no database)), on the right Run, Run all, History and Export result. For databases on servers the notice for working on servers sits above.
How to do it
- Write your statement. Separate several statements with
;. - ⌘↩ (Run) runs the statement under the cursor and selects it. ⇧⌘↩ (Run all) runs all of them.
- The results appear below, for several statements as "Result 1", "Result 2" and so on. Underneath is the number of rows ("42 rows") and, for statements that change data, "… rows changed".
- If a statement returns no rows, it says "The statement returned no rows."
Each result shows at most 1000 rows. If there are more, "more rows exist (limit 1000)" is added. You can browse and copy a result like a table.
Statements that change data
If a statement writes to the database (UPDATE, DELETE, ALTER and the like), the console asks first: "Change data?" with "This statement writes to the database. Run it?", the SQL and the target (connection and database). On a connection marked as production in WebDonkey, the target shows in red with "Production connection. This changes live data." Run executes the statement, Cancel does not.
History
History shows the last 30 statements you ran on this source. A click appends one at the end of your SQL. While the list is empty it says "Nothing run yet". Your SQL itself is remembered per tab.
Free and Premium
Consoles on local databases are free, on databases on servers they are part of Premium.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A red error below the editor | The server rejected the statement | Fix the SQL. |
| "The database client (mysql/psql) was not found." | The machine the query runs on lacks the database's command line program | Install the client there. |
| New SQL console at the top does nothing | No source is running | Start a database server. |
See also
Export Free & Premium
You save a table or a query's result as a file, as CSV for Excel or as SQL INSERT for another database, for example. Single rows you copy to the clipboard in the same formats.
Where to find it
- In a table's tab: Export (download icon) in the bar.
- In the SQL console: Export result.
- Right-click rows: Copy row as or Copy n rows as.
Save
- Click Export or Export result and pick the format.
- Choose place and name in the macOS dialog. The suggestion is the table's name,
queryin the console, each with the matching extension. - While exporting, the bottom says "exporting … KB …".
- When done, the editor reports "Exported … rows to …" and shows the file in the Finder.
| Format | Extension | For |
|---|---|---|
| CSV | .csv |
Comma-separated, for most programs. |
| CSV (Excel) | .csv |
The CSV flavour for Excel. |
| TSV | .tsv |
Tab-separated. |
| JSON | .json |
For scripts and APIs. |
| SQL INSERT | .sql |
INSERT statements to load into another database. |
| Markdown table | .md |
To paste into Markdown, a README for example. |
| HTML table | .html |
To paste into a web page. |
| XML | .xml |
For tools that expect XML. |
What exactly is exported
- Export in a table writes the whole table, not just the 200 visible rows, with the filter and sort that are set.
- Export result in the console runs the last executed statement again and writes its result to the file. With SQL INSERT the table in the statements is called
query. The button is grey until you have run something.
The editor writes the export into the file piece by piece and shows how much has been written so far.
Copy
- Mark rows through the row numbers (⌘-click, ⇧-click).
- Right-click, Copy n rows as (for a single row Copy row as) and a format.
- The rows are on the clipboard.
Copy value (⌘C) copies just the cell.
Free and Premium
Exporting from local databases is free, from databases on servers it is part of Premium.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Export result is grey | Nothing has been run yet | Run a statement first. |
| A red message after the export | The query or writing the file failed | Check the query and the target folder. |