Start
Docs
How based works as a desktop database client: engines, connections, the editor, the grid, the UI, and the files you commit.
based is a local-first desktop client for PostgreSQL, SQLite, and MongoDB.
There is no account and no backend. You open a folder that contains a
.based/ project, connect straight from your machine, and keep
shared setup in plain files.
Two layers of state
Almost every control in the app belongs to one of two layers. Mixing them up is the usual source of “why didn’t this sync to my teammate?”
| Layer | Where it lives | Shared? |
|---|---|---|
| Project | .based/ in the repo — connections, saved queries,
project.toml, vars.toml | Commit what the team should share. Gitignore secrets and personal state. |
| App |
Settings window → native_preferences.toml on this machine
| Theme, fonts, page size, table behavior. Not part of the repo. |
Workspace map
The main window is a three-pane shell: catalog on the left, tabs in the center, optional Inspector / History / Saved on the right. Home is the default center tab until you connect.
| Area | What you do there |
|---|---|
| Left sidebar | Pick a connection, browse schema objects, open data or a new query. |
| Center tabs | Query editor, table viewer, structure inspector, Home, Mongo pipeline builder. |
| Right panes | Inspector metadata, per-connection run history, project saved queries. |
| Command palette | Jump to objects, queries, history, and workspace commands without the mouse. |
Guides
Databases
PostgreSQL, SQLite, and MongoDB — what each engine can do in the app today.
Connections
Project connection files, the connection tree, wizards, secrets, and connect lifecycle.
Editor
SQL and aggregation editors, run, results, explain, variables, and saved queries.
Table grid
Data viewers, pagination, filters, sorting, export, and grid preferences.
UI
Title bar, sidebar, center tabs, side panes, Home, command palette, and theme.
Navigation
Tabs, shortcuts, catalog, saved queries, history, favorites, and pop-out windows.
Settings
The settings window: appearance, updates, query defaults, and table interaction.
Configuration
The .based/ folder, project.toml, vars, secrets, local state, and native preferences.