Examples and notebooks¶

These notebooks mirror the runnable examples shipped in the repository and are checked into the documentation with executed outputs. They are guided, browser-friendly walkthroughs for common sql2sqlx migration tasks, so readers can inspect both the code and the rendered results on the website.

Notebook walkthroughs

Script examples¶

The repository also includes standalone scripts under examples/:

01_convert_string.py demonstrates in-memory conversion.
02_convert_file.py converts one SQL file.
03_convert_directory.py converts an input directory.
04_custom_options.py shows option customization.
05_programmatic_report.py inspects conversion reports.
06_benchmark.py generates benchmark corpora.

Copy-paste recipes¶

Short, self-contained snippets for the most common tasks. All use the public API described in the API reference.

Convert one statement and print it¶

from sql2sqlx import convert_string

result = convert_string("CREATE OR REPLACE TABLE ds.t AS SELECT 1 AS x;")
print(result.files[0].content)

Convert a tree and write it, with options¶

from sql2sqlx import ConversionOptions, convert_directory

convert_directory(
    "legacy_sql",
    "project/definitions",
    ConversionOptions(
        default_project="my-gcp-project",
        default_dataset="analytics",
        insert_strategy="incremental",
        merge_strategy="incremental-when-safe",
        declare_external=True,
        tags=["migrated"],
    ),
)

Convert without writing, then inspect and write yourself¶

from sql2sqlx import convert_directory, write_result

result = convert_directory("legacy_sql")   # output_dir omitted -> nothing written
print(result.report.actions_by_type)
for f in result.files:
    print(f.relpath, f.action_type.value, f.action_name)

write_result(result, "project/definitions")  # write when you are ready

Group warnings by code¶

from collections import Counter
from sql2sqlx import convert_directory

report = convert_directory("legacy_sql").report
by_code = Counter(w.code for w in report.warnings)
for code, n in by_code.most_common():
    print(f"{n:4}  {code}")

Fail CI on parse failures or a disallowed code¶

import sys
from sql2sqlx import convert_directory

report = convert_directory("legacy_sql").report
blocking = {"DEPENDENCY_CYCLE"}
if report.failures or any(w.code in blocking for w in report.warnings):
    sys.exit(1)

See the report reference for the full report structure and conversion rules for every warning code.