Projects and files

Strata SQL keeps everything in plain files, so a model reviews, diffs and merges like code.

What a project looks like#

A project is a folder. Even with one model it has the same shape, so adding models later means adding folders, never moving files.

sales-warehouse/
├── strata.project.json                       the project manifest
├── data_models/
│   └── sales-warehouse/
│       ├── sales-warehouse.model.json        the model
│       ├── sales-warehouse.model.layout.json diagram positions
│       └── data/                             sample data, one CSV per table
├── history/
│   └── sales-warehouse.history.jsonl         the version log
├── .gitattributes   .gitignore
└── .strata/                                  personal settings and caches (never commit)

The files#

File	Purpose
`*.model.json`	The model: catalogs, schemas, tables, columns, relationships, and the optional conceptual, logical and semantic levels with governance values and policies. Small, sorted and readable by people and by AI assistants. It holds no diagram positions and no version pointers. Keys Strata SQL does not know are kept.
`strata.project.json`	The manifest: the project's name and its models. After an import it also holds a `dbt` or `sql` block with the source paths and the last sync time. A few lines; you rarely edit it.
`history/<name>.history.jsonl`	The version log: one entry per line, only ever added to, each chained to the previous one by a SHA-256 hash. Never edit it by hand.
`*.model.layout.json`	Where the tables sit on the diagram, per level. Not versioned. Commit it if you want everyone to see the same picture.
`data/*.csv`	Sample data: one `catalog.schema.table.csv` per table.
`*.model.embeddings.json`	Generated search vectors for AI assistants. Regenerable; never edit.
`.strata/`	Personal: your name and e-mail, window state, a rebuildable cache. Do not commit it.

Any file ending in .model.json opens in the Strata SQL editor. Use Reopen Editor With... → Text Editor to see the raw JSON. An older bare x.model.json opens as a one-model project and gets a manifest the first time you save.

Saving#

Cmd/Ctrl + S writes the version log first, then the model. Moving a table on the diagram is not a model change: it writes only the layout file, straight away.

New project options#

Run Strata SQL: New Project (Command Palette, right-click a folder in the Explorer, or the button on the empty screen).

Starting point: Blank, Northwind, FpML, Dimensional star, a dbt project, or DDL / SQL scripts.
Blank only: choose the database technology and the methodology.
Team setup (optional): tick Git files to write .gitattributes and .gitignore, and choose whether to commit the layout file.

Strata SQL writes the first history entry, the model, its layout, sample data, the manifest and the two Git helper files, in that order. Existing .gitattributes and .gitignore are added to, never replaced.

From a terminal#

The strata-sql command does the same without VS Code, and opens the editor in your browser. From a source checkout, run npm link once to put it on your PATH, or call node cli.js by its full path. It is also the command of the @stratasql/strata-sql npm package.

strata-sql init --name "Sales Warehouse" --template star --dir ./sales
strata-sql live                          # open the project in your browser
strata-sql import-dbt --from ./analytics --name "Jaffle Shop"
strata-sql import-sql --ddl schema.sql --dml reports.sql --dry-run

Command	What it does
`init`	Creates a project: blank, or from a sample. Never overwrites anything.
`live`	Opens the editor in your browser. See Live view in the browser.
`import-dbt`	Reads a dbt project (needs `target/manifest.json`); re-run it to re-sync. See Import from dbt.
`import-sql`	Reads `CREATE TABLE` scripts and queries; re-run it to re-sync. See Import from SQL scripts.
`split` / `join`	Splits a project into one file per domain, or joins the parts back into one. See Domains.

strata-sql --help lists the commands and strata-sql <command> --help explains one. Commands that print a list (init, the two imports, split, join) stop after a few lines; add --verbose to see every item. init options: --template blank|northwind|fpml|star, --platform, --methodology (blank projects), --no-git, --ignore-layout. --dir defaults to the current folder.

Supported databases#

SQL Server, PostgreSQL, MySQL, Oracle, SQLite, Databricks, Snowflake, Google BigQuery, Trino/Presto and DuckDB. Databases with catalogs use three-part names (catalog.schema.table); the others use two-part names.

Methodologies#

ER (1NF, 2NF, 3NF), Dimensional Modelling, Data Vault and One Big Table. The choice is recorded on the project; you model as you like.

Splitting a big project by domain#

Group concepts into domains such as Sales or Catalog on the Domains tab, each with an owner. Strata SQL: Split into Domains then writes one model file per domain, so teams work in parallel, and Strata SQL: Open Project View shows the whole project on one canvas with every card badged by its domain. The original file is kept, renamed, read-only.