sql2sqlx¶

Convert BigQuery SQL into Dataform SQLX with conservative, dependency-aware migration tooling.

sql2sqlx turns plain .sql pipelines - DDL, DML and BigQuery scripts - into a complete Dataform project:

typed actions - table, view, incremental, operations and declaration, chosen per statement;
${ref(...)} dependency wiring - every read of a table another statement produces is rewritten, and ordering is preserved with dependencies edges;
metadata mapping - PARTITION BY, CLUSTER BY and OPTIONS(...) map to the Dataform config block;
a machine-readable report - every decision, fallback and warning, ready to triage or gate CI on.

SQL that is not explicitly rewritten is retained character-for-character after decoding, and the defaults never change what your SQL does.

pip install sql2sqlx
sql2sqlx ./legacy_sql -o ./dataform/definitions --report report.json --init-project

Why it is safe to run¶

The whole tool is built on one rule: convert only when it is provably safe, otherwise keep the statement verbatim and record a warning. A verbatim operations action runs your original SQL unchanged, so a first conversion never alters behavior - it gives you a working Dataform project on day one, which you then make more idiomatic by opting into typed strategies you have validated. See core concepts for the output anatomy and limitations & guarantees for the precise contract.

Where to go next¶

New here? Start with installation and the quick start.
Migrating a real codebase? Follow the migration guide.
Want to know exactly how a statement converts? See the conversion rules.
Building on the Python API? See the API reference.

Under the hood

Project