Workspace

Connections

One TOML file per connection, committed with the repo. The app loads them into a registry you open, test, and disconnect from the sidebar.

Connections are not trapped in a GUI settings dump. They live under .based/connections/ as small TOML files. Opening a Based project loads every *.toml in that tree (files whose names start with _ are skipped, so drafts can sit beside real connections).

Identity is the path

There is no id field in the file. The stable id is the path relative to connections/ without the .toml suffix:

File	Connection id
`connections/northwind.toml`	`northwind`
`connections/local/northwind.toml`	`local/northwind`
`connections/public/ebi_postgres.toml`	`public/ebi_postgres`

Saved queries point at this id in [target].connection. Rename or move the file and the id changes — git will show both sides of the update. Nested folders are for humans (sidebar grouping). They do not change engine behavior; use tags for anything queries match against.

Common fields

Field	Required	Meaning
`schema_version`	Yes	Connection file format. Currently `1`.
`label`	Yes	Name in the tree, status bar, and menus.
`engine`	Yes	`postgres` (alias `postgresql`), `sqlite`, or `mongodb` (alias `mongo`).
`tags`	No	String labels for query `[target]` matching. A tag named `readonly` (any case) implies SQLite read-only if `read_only` is omitted.
`read_only`	No	When `true`, SQLite opens `mode=ro`. Explicit `false` wins over a `readonly` tag.

Engine files

PostgreSQL

.based/connections/local/postgres.toml

schema_version = 1
label = "Local PostgreSQL (Docker)"
engine = "postgres"
tags = ["local", "dev"]

host = "localhost"
port = 5432
database = "based"
username = "based"
password = { env = "LOCAL_PG_PASSWORD" }
ssl = false

ssl = true → Require; ssl = false → Disable. For Verify CA / Verify Full, use the in-app wizard (session connection) until those modes exist on the file format.

Optional [ssh] adds one hop: Based SSHs to the bastion, then local-forwards to host:port as seen from that machine. Host keys are checked against ~/.ssh/known_hosts. Leave key_path out to use the SSH agent. Verify CA / Verify Full are not supported through the tunnel yet — use Require.

.based/connections/prod.toml

schema_version = 1
label = "Prod Postgres"
engine = "postgres"

host = "mydb.internal"
port = 5432
database = "app"
username = "app"
password = { env = "BASED_PROD_PASSWORD" }
ssl = true

[ssh]
host = "bastion.example.com"
port = 22
user = "ec2-user"
# omit key_path to use ssh-agent
key_path = "~/.ssh/id_ed25519"
key_passphrase = { env = "BASED_PROD_SSH_KEY_PASSPHRASE" }

SQLite

.based/connections/local/northwind.toml

schema_version = 1
label = "Northwind"
engine = "sqlite"
tags = ["local", "demo"]
read_only = false
file = "data/northwind.db"

[pragma]
journal_mode = "wal"
synchronous = "normal"
foreign_keys = true

MongoDB

.based/connections/staging/analytics.toml

schema_version = 1
label = "Analytics MongoDB"
engine = "mongodb"
tags = ["staging"]

url = { env = "MONGO_URL" }
database = "analytics"

Secrets

Any password or URI field can be a literal string or { env = "VAR" }. Based resolves the latter from the process environment at connect time. If the variable is missing, connect fails with a clear error.

Keep values out of git: commit .based/.env.example with empty keys, and a gitignored .based/.env on each machine. Launch Based from an environment that has those variables set (your shell, direnv, or a wrapper). Do not put secrets in the connection TOML when you can avoid it.

Inline passwords are allowed for local demos only. They will be committed if the file is. Prefer { env = "…" }.

In the app

Project connections

File → Open Project (⌘O / Ctrl+O) picks a folder that contains .based/. Connections appear in the left icon rail. Click a disconnected row to connect; the catalog loads and the center workspace switches to that engine. Disconnect from the connection context menu or the status-bar chip.

Ephemeral connections

Home → New Connection opens an engine picker and a wizard (Postgres / SQLite / MongoDB). Test reports latency and server version. Connect adds the connection to this session only — it does not write a file under .based/connections/. To share it, add a TOML file yourself (or wait for the project wizard).

Connection tree

Icon rail: every connection, engine icon, state color.
Content rail: catalog grouped by schema (Postgres) or a flat list (SQLite, MongoDB). Search filters objects.
Object actions: Open Data, Open Structure (SQL tables/views), Copy Name, copy connection string / CLI command, Refresh, Disconnect.

Tags are parsed and used by query targeting; they are not shown as badges in the tree yet. The title-bar environment name is display-only — switching environments is not in the UI.

Reload

Based watches .based/. After git pull or an external edit, connections and saved queries reload without restarting the app. Switching project or quitting prompts if you still have live connections or dirty tabs.