based
Star 41 Download

Workspace

Editor

Center-tab SQL and aggregation editors: run, results, explain, variables, and saved query files.

Each connection owns query tabs in the center dock. PostgreSQL and SQLite get a SQL editor; MongoDB gets a JSON aggregation pipeline builder. New query tabs always open a fresh tab (they are not deduped).

Open and run

Action How
New query ⌘⌥N / Ctrl+Alt+N (needs a focused connection), File menu, connection menu, Home, or command palette
Run ⌘Enter / Ctrl+Enter with the editor focused, or the Run button

Run executes the entire buffer. Selection-only run and “statement at cursor” are not shipped. SQLite may contain multiple statements; Based runs the script and shows the last result set.

New query tabs auto-run when the buffer is already non-empty (for example a saved query or a palette-generated SELECT *).

Result panes

Under the editor:

  • Results — the same table grid as data viewers (see Table grid).
  • Messages — errors and OK summaries.
  • Explain — Postgres EXPLAIN (FORMAT JSON); SQLite EXPLAIN QUERY PLAN as a tree.

Export the current result to CSV or XLSX from the viewer chrome.

Variables

Query text can include $NAME placeholders from .based/vars.toml:

.based/vars.toml 
[vars]
SCHEMA = "public"

Unknown $NAME tokens are left as-is. The editor toolbar has a variables popover; Edit file opens vars.toml in your system editor.

Postgres also resolves Postman-style {{name}} templates and builtins:

Token Result
{{$randomUUID}} UUID v4
{{$timestamp}} Unix timestamp (UTC)
{{$isoTimestamp}} RFC 3339 timestamp
{{$randomInt(min,max)}} Inclusive random integer

Saved queries

One file per query under .based/queries/**/*.toml (skip _*.toml). The file path relative to queries/ is the internal identity. Folders group the Saved pane; they do not pick the connection. That is [target].

Field Required Meaning
schema_version Yes Query file format. Currently 1.
name Yes Label in Saved, palette, and tabs.
description No Longer explanation.
tags No Labels on the query itself (search/filter). Unrelated to connection tags.
[target] Yes Which connection(s) may run this query.
[sql] or [aggregate] Exactly one SQL body, or Mongo pipeline + collection.

Portable SQL (any Postgres)

.based/queries/pg-list-tables.toml 
schema_version = 1

name = "List Tables"
description = "Postgres information_schema tables"

[target]
engine = "postgres"

[sql]
query = """
SELECT table_schema AS schema, table_name AS name
FROM information_schema.tables
WHERE table_type = 'BASE TABLE'
  AND table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY 1, 2;
"""

Pinned to one connection

.based/queries/northwind/recent-orders.toml 
schema_version = 1
name = "Recent Orders"
tags = ["orders"]

[target]
connection = "local/northwind"

[sql]
query = """
SELECT OrderID, OrderDate FROM Orders
ORDER BY OrderDate DESC
LIMIT 50;
"""

Mongo aggregation

.based/queries/orders/completed-by-plan.toml 
schema_version = 1
name = "Completed by plan"

[target]
engine = "mongodb"

[aggregate]
collection = "orders"
pipeline = """
[
  { "$match": { "status": "completed" } },
  { "$group": { "_id": "$plan", "count": { "$sum": 1 } } },
  { "$sort": { "count": -1 } }
]
"""

Query targets

Fields combine with AND. No globs and no nested tag language in v1.

Field Rule
connection string Exclusive: only this id. Must not be combined with engine, tags, or exclude_tags.
connection array Id must be one of the listed ids. May combine with the filters below.
engine postgres, sqlite, or mongodb.
tags Connection must have every listed tag (case-sensitive).
exclude_tags Connection must have none of these tags.

When you open or run a query:

  1. Exclusive string → that connection (error if missing).
  2. Otherwise compute the matching set.
  3. If the focused connection is in the set, prefer it.
  4. One match → use it. Several → picker. None → error.

The query text is never rewritten per connection.

Favorites and history

Starring a query writes .based/state/favorites.toml (gitignored). It does not edit the query file. History is append-only .based/local/history.jsonl, capped per connection, also gitignored. Open either from the right panes or the command palette.