# Turbine for VS Code

Write and check data contracts directly in your editor. The extension catches contract mistakes as you type, completes field names and check types, validates your contract against the live database, and runs quality checks without leaving VS Code.

It pairs with the [Turbine Python package](https://pypi.org/project/turbine-data/), which actually runs your contracts. The extension is the interface; the package is the engine.

## Install the extension

Open the Extensions view (`Cmd+Shift+X` / `Ctrl+Shift+X`), search for **Turbine**, click Install. From the command line:

```bash
code --install-extension enexis.turbine-lsp
```

## Set up your project from the sidebar

Open your project folder in VS Code, then click the **Turbine** icon in the Activity Bar.

<p align="center">
  <img src="screenshots/sidebar-onboarding.png" alt="The Turbine sidebar on a fresh project" width="320">
</p>

The sidebar walks you through setup one step at a time. Click each button as it appears — you do not need the command palette for any of it.

1. **Initialize Python project.** On a fresh folder the sidebar's first card runs `uv init` for you. Skipped automatically if your folder already has a `pyproject.toml`.
2. **Pick a database.** The next card shows tiles for DuckDB, Postgres, Snowflake, and an LSP-only option. **For the tutorial, pick DuckDB** — it carries a `REQUIRED FOR TUTORIAL` badge so you cannot miss it. DuckDB runs against local files and needs no warehouse credentials.
3. **Install the right extra.** The sidebar runs `uv add "turbine-data[duckdb]"` (or whichever database you picked) in your workspace's terminal.
4. **Scaffold and tour.** The sidebar drops `[tool.turbine]` into `pyproject.toml`, creates the project layout, opens the starter contract, and launches the guided tour.

The sidebar reflects state live, so you can stop after any step and resume later. If you already have a Turbine project, the sidebar skips straight to the tour entry.

## What the extension does

**Diagnostics as you type.** Contract YAML, datasource YAML, quality specs, and SQL check templates validate continuously. Mistakes show up in the Problems panel; hover the squiggle for the explanation.

**Schema-aware completion.** Field names, check types, dimension names, threshold operators — all autocomplete with descriptions. Hover any ODCS field to see what it means.

**Quick fixes.** Common mistakes ship with a code action that fixes them in place. `Cmd+.` / `Ctrl+.` on the squiggle.

**Run checks from the editor.** Three commands you'll use daily:

- `Turbine: Validate Contract` — compare the contract to the live database schema
- `Turbine: Run Quality Checks` — run every check defined in this contract
- `Turbine: Run Quality on Workspace` — same, for every contract in the project

**Live database actions.** Right-click any datasource file to test the connection or scaffold a new contract from an existing database table.

## Project layout

The extension expects:

```
your-project/
├─ pyproject.toml          [tool.turbine] section present
├─ contracts/              DataContract YAML files
├─ datasources/            warehouse connection YAML files
├─ quality/                (optional) QualitySpec files
└─ checks/                 (optional) SQL Check Templates
```

If your Turbine files live somewhere other than the repo root, set `root`:

```toml
[tool.turbine]
root = "src/my_data_product"
```

## Troubleshooting

**No diagnostics show up.**
Open the repo root, not just the `contracts/` folder. Check that `pyproject.toml` contains `[tool.turbine]`. Read **Output → Turbine LSP** for the startup log.

**`uv` cannot be found.**
Install `uv` and restart VS Code:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

On macOS, VS Code may start without your full shell `PATH`. Launch it from the terminal (`code .`), or set `turbine.serverCommand` to the absolute path:

```json
["/Users/you/.local/bin/uv", "run", "turbine-lsp"]
```

**`turbine-lsp` cannot be found.**
Install one of the database extras — every extra includes the language server:

```bash
uv add "turbine-data[duckdb]"
```

**Not using `uv`?**
Install with pip:

```bash
python -m pip install "turbine-data[postgres]"
```

Then set `turbine.serverCommand` to `["turbine-lsp"]`.

## Beyond the editor

Once your contracts work locally, the same checks run anywhere the Turbine package is installed:

- **CI** — `turbine check` exits non-zero on quality failures
- **Server** — `turbine serve` exposes runs and results over HTTP, with a dashboard
- **Orchestrators** — [`dagster-turbine`](https://pypi.org/project/dagster-turbine/) and [`airflow-turbine`](https://pypi.org/project/airflow-turbine/) wrap Check Runs as native asset checks and operators

The [`turbine-data` PyPI page](https://pypi.org/project/turbine-data/) and the [main repo README](https://enx.gitlab.schubergphilis.com/1000078-app-keten-shared/applications/turbine-platform/turbine) have the full picture.
