Turbine

Turbine helps you write and check data contracts from VS Code. It shows contract errors while you type, suggests fields and check names, validates live database schema, and runs data quality checks from the editor.

The VS Code extension works with the Turbine Python package installed in your workspace. Install the extension once in VS Code, then add turbine-data to each project that uses Turbine. If you install the extension first, it will show a setup prompt with the same commands listed below.

Requirements

• VS Code 1.80 or newer
• Python 3.13 or newer
• uv for project dependency management
• A workspace folder opened at your project root

The PyPI package is named turbine-data. The commands it installs are still named turbine and turbine-lsp.

Install Turbine in your project

Run one of these commands in the project where you want to use Turbine.

PostgreSQL

uv add "turbine-data[postgres]"

Use this for PostgreSQL databases. The postgres extra installs the PostgreSQL driver, API support, Python checks, telemetry support, and the language server used by this extension.

Snowflake

uv add "turbine-data[snowflake]"

Use this for Snowflake warehouses. The snowflake extra installs the Snowflake connector, API support, Python checks, telemetry support, and the language server used by this extension.

DuckDB

uv add "turbine-data[duckdb]"

Use this for local files, demos, onboarding, and lightweight projects. DuckDB is the fastest way to try Turbine without database credentials. The duckdb extra also installs the language server used by this extension.

Everything

uv add "turbine-data[all]"

Use this when you want every supported database driver, the language server, and dashboard dependencies in one environment.

Start a new Turbine project

Start the project setup:

uv run turbine init

Copy the environment template and fill in your database credentials:

cp .env.example .env

Then check that Turbine works:

uv run turbine lint contracts/example.yml
uv run turbine validate --datasource default contracts/example.yml
uv run turbine check --datasource default contracts/example.yml

If you used the recommended src/{project_name} layout, your starter contract may be under src/{project_name}/contracts/example.yml instead.

Use the extension

1. Open the project root in VS Code.
2. Open a contract YAML file, datasource YAML file, quality spec, or SQL check.
3. Wait for Turbine to start. If there are any problems they should appear in the editor and in the Problems panel.
4. Use the command palette or editor actions:

Turbine: Validate Contract
Turbine: Run Quality Checks
Turbine: Run Quality on Workspace
Turbine: Jump to Contract
Turbine: Start Onboarding

The extension starts the language server with this command by default:

uv run turbine-lsp

That means the language server must be installed in the same workspace environment.

Existing projects

For an existing Turbine project, make sure your repository has:

pyproject.toml
contracts/
datasources/
quality/        # optional
checks/         # optional

Your pyproject.toml should include a Turbine section:

[tool.turbine]
root = "."

If your Turbine files live under another folder, set root to that folder:

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

If you do not use uv

The extension can also run a globally installed turbine-lsp command. Install Turbine with pip:

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

Then change the VS Code setting turbine.serverCommand to:

["turbine-lsp"]

Use the matching database extra for your project: postgres, snowflake, or duckdb. Each one includes the language server.

Troubleshooting

The extension says uv cannot be found

Install uv, then restart VS Code:

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

On macOS, VS Code sometimes starts with a limited PATH. If uv is installed but VS Code cannot find it, set turbine.serverCommand to the full path, for example:

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

The extension opens a setup prompt

Choose the database you use. Turbine opens a terminal with the matching install command. For a new project, it also runs:

uv run turbine init

The extension says turbine-lsp cannot be found

Install the language-server extra in the workspace:

uv add "turbine-data[lsp]"

If you also need a database driver, install the matching database extra:

uv add "turbine-data[postgres]"

No diagnostics appear

Check these first:

1. Open the repository root, not only the contracts/ folder.
2. Confirm pyproject.toml contains [tool.turbine].
3. Open Output > Turbine LSP in VS Code and read the startup log.
4. Run the server manually:

uv run turbine-lsp

Database validation or quality checks fail

Check your datasource file and .env values. PostgreSQL and Snowflake need live credentials. DuckDB needs the configured database file to exist.

You can test from the terminal first:

uv run turbine validate --datasource default contracts/example.yml
uv run turbine check --datasource default contracts/example.yml

Common install commands

# PostgreSQL project
uv add "turbine-data[postgres]"

# Snowflake project
uv add "turbine-data[snowflake]"

# DuckDB project
uv add "turbine-data[duckdb]"

# Everything, including dashboard support
uv add "turbine-data[all]"

After installing, the commands are:

uv run turbine --version
uv run turbine-lsp