Screens: Connections and explorer

Object explorer

The object explorer on the left of the project screen shows your connections and the live databases under them as a tree. Here you find tables and objects and open them in detail tabs, drag them into an ERD, and refresh, create or drop things from the context menu. How connections, databases and schemas relate is explained in Connections and execution targets.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

What's on the screen

No.NameDescription
1Project railExplorer buttonThe top button on the left rail. It opens the explorer. Pressing it again while the explorer is open collapses the left panel.
2Connection... buttonOpens the window for a new connection. See Create and edit a connection.
3Filter tables... boxKeeps only the tables, views and objects whose names contain what you type. See "Finding a table" below.
4Connection nodeThe dot before the name is the connection state. See "Nodes and indicators" below.
5Refresh and edit buttons of the connectionThe refresh button reads this connection's lists from the database again, and the pencil button opens the connection window. Database, schema and group nodes also have a refresh button.
6Schema nodeA schema you selected in the connection window. DBMSs with a database level have a database node above it.
7Group nodeThe Tables group, the Views group and the object groups of each DBMS. The number in parentheses is how many items it holds.
8Table nodeDouble-click it to open the table tab (Table tab). The refresh button at the right end re-reads only this table, and the ⋮ button opens the context menu.
9ERD and SQL listThe project's ERDs and SQL documents. See ERD and SQL list.
  • The Secret Key Lock button on the right of the toolbar appears only in account projects while signed in. Only the owner can turn it on. See Zero-knowledge encryption.
  • With no connections, the tree is replaced by the No connections yet message and the Add connection button.

Nodes and indicators

The tree goes connection › (database) › schema › group › object. Database nodes exist only for DBMSs with a database level, such as PostgreSQL and SQL Server. Only the schemas you selected on the Schema tab of the connection window appear, not every schema in the database.

NodeIndicator and meaning
ConnectionThe dot before the name: green is connected, yellow is connecting, a red × is a failed connection (hover to see the error), and a hollow grey circle is not connected yet. Expanding the node connects.
Connection (no connection details)The name is followed by Not configured. It is a design-only connection with just a DBMS chosen, so menus that read the database are absent.
Connection (disabled)Shown dimmed with a lock icon and Disabled. In the web app, SQLite and localhost connections look like this with Desktop only.
Orange warning on a connectionThe custom driver set for the connection is missing on this device. The bundled driver with the same driver class is used if there is one; otherwise it cannot connect (Custom driver is missing on this device. The bundled driver with the same driver class is used if there is one; otherwise the connection fails.).
Shield icon on a connectionIn PostgreSQL, some tables have row-level security (RLS) enabled and the signed-in user cannot bypass it. Queries may return only some rows.
Database, schemaHover to see the database comment, if there is one. A schema without a name shows as (no schema).
System schemasGathers system schemas such as PostgreSQL's pg_catalog and schemas you marked as system, shown in grey. Tables in system schemas cannot be edited.
GroupUnder a schema: the Tables group, the Views group and groups that differ by DBMS (indexes, triggers, Routines for functions and procedures, and so on). The Server Objects group right under the connection holds server-level objects such as users, sessions, locks and server settings. A group is read from the database the first time you expand it.
Table, viewThe name color shows how it differs from the database: green is a virtual table not yet in the database, blue has changes not yet applied, and red strikethrough is marked for deletion. A renamed table is followed by ←old name. Expand it to see the columns.
ObjectA single object such as a sequence, function or trigger. Functions show their arguments in short form, and indexes and triggers show the table they belong to. Objects with compile errors carry a red mark.
Data DictionaryAppears only when a data dictionary is assigned to the connection. Clicking it opens the data dictionary tab of the connection window, and clicking the domain or dictionary node below it opens that tab. See Assigning to a connection.

When you switch to another tab, the connection, database and schema it points to are highlighted in the tree, which scrolls to them if they are out of view.

Opening nodes

NodeClickDouble-click
Connection, database, schema, groupA schema is selected. Expand and collapse with the arrow in frontNo tab opens. Groups that have their own list screen (Views, indexes, the groups under Server Objects, and so on) open the list in an object tab (Object tabs)
TableSelects itOpens the table tab (Table tab)
View, objectSelects itOpens an object tab (Object tabs). A progress indicator spins on the node while the definition is read from the database
  • The Explorer context menuView Detail menu in the context menu does the same as double-clicking a table or view. With several selected, it opens a tab for each.
  • Groups under Server Objects that have no dedicated list screen open in the Document tabObject list tab, a simple screen with the list of rows and the properties of the selected row.

Finding a table

  1. Type part of a table name in the Filter tables... box (3). Case does not matter.
  2. Only tables, views and objects whose names contain the text remain. Indexes and triggers are also matched by the name of their table. Connection, schema and group nodes stay.
  3. Clear the box to see every node again.
  • The filter only looks at nodes already read. It cannot find objects in a group you have never expanded, so expand it first.
  • Changing the filter clears a multiple selection.

Selecting several nodes

  • Click with Ctrl (Cmd on macOS) held to add or remove one at a time. Click with Shift held to select from the last node you clicked to the one you click now.
  • Only nodes under the same parent can be selected together. Clicking a node in another group starts a new selection. Schemas can be combined with Ctrl even across connections (this is for Schema compare).
  • Right-clicking one of the selected nodes applies the menu to all of them, and only menus that every selected node accepts appear. Right-clicking a node outside the selection clears it and shows the menu for that node alone.

Bringing tables into an ERD

  1. Open an ERD tab.
  2. Drag a table node from the explorer onto the ERD canvas. On hover the icon turns into a drag handle (Drag to ERD or SQL editor). If you selected several tables, drag one of them to bring them all.
  3. The table appears where you dropped it, several tables stacked vertically. Save the ERD.
  • The Explorer context menuAdd to Current ERD menu in the context menu places the table in the middle of the ERD tab you are looking at and saves the ERD right away. It cannot be pressed unless an ERD tab is in front.
  • Tables from another connection cannot be dropped. An ERD made for one schema accepts only tables of that schema. Tables already in the ERD are skipped.
  • Dropping a table node on the SQL editor opens a menu that writes SQL such as SELECT or INSERT. See SQL editor.

Refreshing

After changing the database with another tool or applying changes, refresh to bring the tree in line with the database.

TargetWhat is read again
A node's refresh buttonThe list under the node (the tables of a schema, the objects of a group, and so on)
A table node's refresh button, the Explorer context menuRefresh menu on a tableThat table's columns, keys and indexes
The Explorer context menuRefresh menu on a connection, schema or groupThe lists below it, and the information of the tables visible under it

When tables are read again and some of them have changes not yet applied to the database, you are asked what to do.

ButtonResult
Replace buttonDiscards all changes, resets to the database state and saves.
Merge buttonTakes the current structure from the database while keeping the entity settings for code generation. Does not save.
  • Tables linked by foreign keys are read again too. If there are any, their names are shown and you are asked to continue.
  • Pressing the window's close button reads nothing.
  • Disabled connections and virtual tables not yet in the database cannot be refreshed.

Connecting and disconnecting

A connection connects on its own when you expand its node or open one of its tabs. To connect or disconnect yourself, right-click the connection.

  1. Right-click the connection node.
  2. If it is not connected, press the Explorer context menuConnect menu. If it is connected or connecting, press the Disconnect menu.
  • Use the Connect menu to retry a connection that failed. A failed connection is not retried automatically.
  • When connecting takes long, a connection task appears in the Background Processes window of the status bar. If a firewall blocks the connection, it fails after the connection timeout and the error stays in the window (App menu, top bar and status bar).
  • The Disconnect menu only closes the link to the database. The connection, ERDs and SQL documents stay. Expanding the node or opening a tab afterwards connects again.

Context menu

Right-click a node to see only the menus that apply to it, grouped by separators. Menus that read or change the database appear only for connections with connection details. The ⋮ button on table and object nodes opens the same menu.

MenuOn which nodesWhat it does
Explorer context menuView DetailTable, viewOpens the detail tab ("Opening nodes" above).
Explorer context menuRefreshConnection, database, schema, group, table, view, objectSame as "Refreshing" above.
Explorer context menuConnectConnectionSame as "Connecting and disconnecting" above. Shown as the Disconnect menu when connected.
Explorer context menuEdit... / Explorer context menuDuplicate...ConnectionOpens the connection window to edit it, or copies its settings into a new connection. Create and edit a connection
Explorer context menuEnableDisabled connectionTurns a connection disabled by plan cleanup back on and reads its lists. Account projects only. Manage Subscription
Explorer context menuData Dictionary...ConnectionOpens the data dictionary tab of the connection window. Assigning to a connection
Explorer context menuAdd to Current ERDTableAdds the table to the ERD you are looking at ("Bringing tables into an ERD" above).
Explorer context menuData Export... / Explorer context menuData Import...TableExports the table's data to a file or imports it from one. Data export, import and native backup
Explorer context menuNative Backup... / Explorer context menuNative Reload...Table, schema, database or connection, depending on the DBMSBacks up and restores with the DBMS's dump tools. Data export, import and native backup
Explorer context menuNew SQL Editor...Most nodes, from connections down to columnsOpens an SQL tab targeting that location. If SQL documents exist for the same location, you can pick one from a submenu. SQL editor
Explorer context menuNew ERD...Same as aboveCreates a new ERD for that location. ERD and SQL list
Explorer context menuNew TableSchema, TablesCreates a virtual table and opens its table tab. Table tab
Explorer context menuCreate ...Groups of objects that can be created (sequences, functions, and so on)Opens an object tab that creates that object. Object tabs
Explorer context menuCreate User Mapping / Explorer context menuEdit User MappingUser mappings of a PostgreSQL foreign serverCreates or edits a user mapping. Object tabs
Explorer context menuImport Tables from DDL...Connection, database, schema, TablesReads DDL statements and creates virtual tables. Import tables from DDL
Explorer context menuModify SchemaDatabase, schemaChanges the comment or owner. Shown only for DBMSs that have such properties. On a database node it appears as the Modify Database menu.
Explorer context menuRename Schema...Database, schemaRenames it. ERDs, SQL tabs and cached tables that use the name follow the new name. Shown only for DBMSs that support it, and never on system schemas. On a database node it appears as the Rename Database... menu.
Explorer context menuCreate DatabaseConnection (not SQLite)Creates a database and adds it to the tree. MySQL, MariaDB and H2 show the Create Schema menu, and Oracle shows the Create Schema (User) menu, which opens an object tab that creates a user.
Explorer context menuCreate Schema...DatabaseCreates a schema in that database and adds it to the tree.
Explorer context menuApply Changes to DB...Connection, schema, Tables, index group, tableShows the DDL for the changed tables inside and runs it. Apply changes to the database
Explorer context menuGenerate QueryTable, view, function, procedure, sequenceWrites and shows SQL such as SELECT. SQL editor
Explorer context menuGenerate Source Code...TableGenerates source code from templates. Generating source code
Explorer context menuReport...Connection, database, schemaDownloads a table report as an Excel file. Table report
Explorer context menuSchema Compare...Schema (two schemas when two are selected)Compares the structure of two schemas. Schema compare
Explorer context menuRole Matrix... / Explorer context menuTest with RLS...PostgreSQL schema / table or view with RLS enabledShows RLS permissions per role, and lets you query as another role. RLS matrix and simulator
Explorer context menuMark as system schemaSchemaMoves the schema into the System schemas group. See "Marking system schemas" below.
Explorer context menuUnmark as system schemaSchema you marked as systemRemoves the mark.
Explorer context menuDelete ConnectionConnectionDeletes the connection from the project. See "Deleting" below.
Explorer context menuRemove from ProjectSchemaRemoves the schema from the project only. The schema in the database stays.
Explorer context menuDrop Database...DatabaseDrops the database on the live database server.
Explorer context menuDrop SchemaSchema (not SQLite)Drops the schema on the live database server. Oracle shows the Drop Schema (User) menu.
Explorer context menuDrop Table...Table, viewMarks the table for deletion or drops it in the database. On a view it appears as the Drop View... menu.
Explorer context menuCancel Table DeletionTable marked for deletionRemoves the deletion mark. A marked table shows this menu instead of the Explorer context menuDrop Table... menu.
  • With several nodes selected, only menus that work on all of them appear. For example, the Explorer context menuSchema Compare... menu appears when exactly two schemas are selected, and the data menus when the tables belong to the same connection and database.
  • The Explorer context menuData Export..., Explorer context menuData Import..., Explorer context menuNative Backup... andExplorer context menuNative Reload... menus also appear in the web app, but pressing them only shows This feature is only available in the desktop app.. Use the desktop app.
  • Right-clicking an empty part of the explorer shows the Project Settings... item, the New Connection... item, theExplorer context menuReport... menu and the new SQL and ERD menus. Account projects also show the zero-knowledge encryption menu.

The pictures show a SQLite connection in the desktop app. SQLite has no menus to create or drop databases and schemas. Other DBMSs show the corresponding menus from the table above.

Creating and changing databases and schemas

  1. Right-click the connection node for a new database, or a database node for a new schema.
  2. Press the Explorer context menuCreate Database menu or the Explorer context menuCreate Schema... menu.
  3. Enter the name and properties in the window and run it. What you create is added to the connection's schema list and appears in the tree right away.
  • Change the comment and owner with the Explorer context menuModify Schema menu, and the name with theExplorer context menuRename Schema... menu. After a rename, ERDs, SQL tabs and cached tables that used the old name move to the new one. Renaming a database ends the sessions of SQL tabs connected to it.
  • These menus run DDL on the live database. In account projects they are dimmed and cannot be pressed for members whose DDL is restricted. They cannot be pressed on disabled connections either.
  • In Oracle a schema is a user, so the Create Schema (User) menu opens an object tab that creates a user. If the signed-in account may not create users, the menu is dimmed.

Marking system schemas

Marking a schema the database relies on, or one you will not touch, as a system schema moves it into the System schemas group in grey.

  1. Right-click the schema node and press the Explorer context menuMark as system schema menu.
  2. The schema moves into the System schemas group.
  3. To undo, right-click the schema and press the Explorer context menuUnmark as system schema menu.
  • System schemas are grey in the ERD and SQL editor too, and their tables cannot be edited. The Explorer context menuRename Schema... and Explorer context menuDrop Schema menus in the explorer are blocked as well.
  • System schemas defined by the DBMS, such as PostgreSQL's pg_catalog and information_schema, cannot be unmarked.
  • The mark is saved in the connection settings.

Deleting

The delete menus of the explorer either remove something from the project only or drop it in the live database. Check the menu name before you press it.

MenuWhere it deletesWhat else happens
Explorer context menuDelete ConnectionProjectDeletes the connection, the ERDs made with it, and the dashboard tiles that use it. In account projects, ERD copies posted to the gallery are deleted too. SQL documents are kept and only unlinked from the connection. If anything is affected, a table lists it for you to confirm. The database does not change.
Explorer context menuRemove from ProjectProjectDeletes ERDs made for this schema alone, and removes this schema's tables from ERDs that hold several schemas. The schema in the database is not dropped.
Explorer context menuDrop Database...Live database serverShows the DDL first and runs only after you type the database name exactly. You can choose to end connected sessions and drop. The maintenance database cannot be dropped.
Explorer context menuDrop SchemaLive database serverAfter a confirmation, drops the schema with every object and row in it. In SQL Server the schema must be empty, and in Oracle the user account is dropped too. System schemas cannot be dropped.
Explorer context menuDrop Table...Your choiceExplained below.

When a database or schema is dropped in the database, the ERDs and SQL tab bindings made from it are cleaned up as well.

  1. Right-click a table (several also work) and press the Explorer context menuDrop Table... menu.
  2. In the Delete Tables / Views window, choose what to do with the tables that exist in the database. Flag Only (Keep in the database) only marks them for deletion, and Execute DROP TABLE (Delete from the database) shows and runs the DROP TABLE statement.
  3. Press the Delete button.
  • A marked table stays in red strikethrough and is dropped from the database at the next apply (Apply changes to the database). Until then, undo it with the Explorer context menuCancel Table Deletion menu.
  • Virtual tables not yet in the database are removed from the project without a choice. Views are dropped right away with DROP VIEW.
  • Tables in system schemas cannot be deleted. In account projects, members whose DDL is restricted cannot drop views, and dropping a table becomes an approval request instead of running.

Things to keep in mind

  • The Explorer context menuRemove from Project menu and the Explorer context menuDrop Schema menu appear side by side. The first only removes the schema from the project; the second drops the schema and its data in the live database and cannot be undone.
  • The Explorer context menuDelete Connection menu also deletes the ERDs made with that connection. To change only the connection details, use theExplorer context menuEdit... menu.
  • Choosing the Replace button when refreshing discards every table change not yet applied to the database.
  • The explorer shows only the schemas selected in the connection window. If a schema is missing, add it in Create and edit a connection.
  • Use SQLite and localhost connections in the desktop app. A lock marks them in the web explorer. Web and desktop