Project

Configuration

The .based/ project folder is the git-friendly unit: committed connections and queries, gitignored secrets and personal state, plus machine-local app prefs.

based has no server-side project. The unit of collaboration is a .based/ directory in a git repo. Teammates clone, fill in secrets locally, and open the folder. File watchers reload after git pull.

Design rules

Version controlled by default — connections (non-secret), queries, and shared project settings are plain files you commit.
One concern per file — small diffs, fewer merge conflicts, easy review.
Secrets stay out of git — passwords and tokens use environment variables, not committed literals.
User preference stays local — favorites, history, and UI state are not team-wide.
Explicit over implicit — which connection a query runs against is declared in [target], not inferred from folders.

Directory layout

.based/

.based/
  project.toml                 # Project manifest (committed)
  connections/
    **/*.toml                   # One file per connection (committed)
  queries/
    **/*.toml                   # One file per saved query (committed)
  vars.toml                    # Query $VAR map (committed if shared)
  .env                         # Local secrets (gitignored)
  .env.example                 # Template for required env vars (committed)
  state/                       # Per-user project preferences (gitignored)
  local/                       # Ephemeral runtime data (gitignored)

Recommended .based/.gitignore:

.based/.gitignore

local/
state/
.env
.env.local
.DS_Store
Thumbs.db

Committed vs local

Path	In git?	Purpose
`project.toml`	Yes	Project name and global settings
`connections/*/.toml`	Yes	Connection definitions
`queries/*/.toml`	Yes	Saved SQL and aggregations
`vars.toml`	Usually	Non-secret query variables
`.env.example`	Yes	Documents env vars teammates need
`.env`	No	Secret values for this machine
`state/`	No	Favorites, active environment, UI prefs
`local/`	No	Query history, session snapshots, caches

Schema version

Every committed Based file carries its own schema_version (integer). It describes that file’s structure, not the whole project. Connection format v2 does not imply query format v2. Unknown versions fail to load with an upgrade/migrate message. New files use schema_version = 1.

`project.toml`

.based/project.toml

schema_version = 1

name = "my-app"
description = "Database queries and connections for my-app"

[settings]
query_timeout = 30000
max_result_rows = 1000
enable_query_cache = true
cache_ttl = 3600

Field	Required	In the app today
`schema_version`	Yes	Must be `1`.
`name`	Yes	Shown in the title bar.
`description`	No	Display only.
`query_timeout`	No	Milliseconds. On project open, converted to seconds and written into the app’s query-timeout preference.
`max_result_rows`	No	Parsed, not enforced yet.
`enable_query_cache` / `cache_ttl`	No	Parsed, not enforced yet.

Project query_timeout overwrites the Settings value when you open the project. It does not stay scoped only to that repo after you change Settings again.

Connections and queries

File formats, ids, tags, engines, and [target] resolution are specified on Connections and Editor. Skip files named _*.toml.

Variables

.based/vars.toml

[vars]
SCHEMA = "public"
LIMIT = "100"

Loaded at startup into a process-wide map. SQL uses $SCHEMA substitution. Keep secrets out of this file — it is usually committed.

Secrets

.based/.env.example

# .env.example
LOCAL_PG_PASSWORD=
MONGO_URL=mongodb://localhost:37017

Connection fields use password = { env = "LOCAL_PG_PASSWORD" } or url = { env = "MONGO_URL" }. Resolution reads the process environment at connect time. Copy .env.example to .env and arrange for those variables to be set in the environment you launch Based from (shell, direnv, or a wrapper). Never commit .env.

Local state

`state/favorites.toml`

.based/state/favorites.toml

schema_version = 1

[[favorite]]
path = "northwind/recent-orders"

[[favorite]]
path = "mindsdb/fraud-summary"

Paths are relative to queries/ without .toml. Starring from Saved writes here, not into the query file.

Other state (planned)

File	Purpose
`state/active_environment.toml`	Selected environment name. Displayed in the title bar; switching is not in the UI yet.
`state/ui.toml`	Sidebar expansion and similar chrome (planned).

Local runtime

File	Purpose
`local/history.jsonl`	Append-only run history, capped per connection.
`local/session.json`	Open tabs / cursors (optional).

App preferences

Theme, fonts, density, page size, table interaction, and updater flags live in native_preferences.toml next to other OS app data — see Settings. That file also stores last_opened_project and recent_projects (recent submenu UI is still pending).

There is no project-level or user-level keybindings file. Shortcuts are built in.