sqllineage

library1.5.8pypypi✓ verified 22d ago

SQLLineage is a Python library designed for SQL lineage analysis, capable of identifying source and target tables, as well as providing column-level lineage from SQL queries. It leverages popular SQL parser libraries like sqlfluff and sqlparse, and uses networkx for graph representation. The library is actively maintained, with its current version being 1.5.7, and sees regular minor releases to introduce enhancements and bug fixes.

database data

pip install sqllineage

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · SQLLINEAGE

sqllineage

databasepythonv1.5.8

Install

9.1s avg

Import

3443ms

Disk

156MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 3.582s · 166.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.1s · import 3.304s · 164MB

156MB installed

● package 156MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LineageRunner

✓ from sqllineage.runner import LineageRunner

This quickstart demonstrates how to initialize `LineageRunner` with a SQL statement and extract the source and target tables. For accurate column-level lineage, especially with `SELECT *` or unqualified columns, providing a `MetaData` object (e.g., via `DummyMetaDataProvider` or `SQLAlchemyMetaDataProvider`) is crucial.

from sqllineage.runner import LineageRunner sql = "INSERT INTO target_schema.target_table SELECT col1, col2 FROM source_schema.source_table WHERE col3 > 100" runner = LineageRunner(sql) print(f"Source Tables: {[str(t) for t in runner.source_tables]}") print(f"Target Tables: {[str(t) for t in runner.target_tables]}") # For column-level lineage (requires metadata for full accuracy) # from sqllineage.core.metadata_provider import DummyMetaDataProvider # metadata = { # 'source_schema.source_table': ['col1', 'col2', 'col3'] # } # runner_with_metadata = LineageRunner(sql, metadata_provider=DummyMetaDataProvider(metadata)) # for path in runner_with_metadata.get_column_lineage(): # print(f"Column Lineage: {path.source.column} -> {path.target.column}")

sqllineage --version

Debug

Known issues

breakingStarting with v1.5.x, `ansi` is the default SQL dialect. This might cause parsing issues for non-ANSI compliant SQL that previously worked without explicit dialect specification. Non-validating dialects are targeted for deprecation in v1.6.

fix

Always explicitly pass the `dialect` parameter to `LineageRunner` or the CLI for your specific SQL dialect (e.g., `sparksql`, `hive`, `tsql`) to ensure correct parsing, especially for complex or dialect-specific SQL. Use `sqllineage --dialects` to see available options.

affects: >=1.5.0

gotchaColumn-level lineage can be inaccurate or incomplete without providing table metadata. For queries involving `SELECT *` or unqualified column names, `sqllineage` cannot fully resolve column dependencies without schema information.

fix

Provide a `MetaData` object or use a `MetaData` provider (like `SQLAlchemyMetaDataProvider`) to `LineageRunner`. This allows `sqllineage` to access schema details and fully resolve column-level lineage.

affects: All versions

breakingPython 3.9 support was dropped, and Python 3.14 support was added in `v1.5.7`. Python 3.8 was deprecated in `v1.5.4`. Ensure your environment uses a compatible Python version.

fix

Upgrade your Python environment to a supported version (e.g., Python 3.10 to 3.14 for `v1.5.7`). Check the official documentation for the latest Python compatibility matrix.

affects: >=1.5.4 (for 3.8), >=1.5.7 (for 3.9)

gotchaComplex SQL patterns, deeply nested subqueries, large UNION chains, dynamic table/column name resolution, or vendor-specific functions can challenge generic SQL parsers, including `sqllineage`, potentially leading to incomplete or incorrect lineage.

fix

For highly complex or non-standard SQL, manual inspection and possibly pre-processing the SQL (e.g., by expanding templates, normalizing vendor-specific syntax) may be necessary to improve lineage accuracy. Providing a `MetaData` provider is also crucial for such cases.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sqllineage'

The `sqllineage` Python package has not been installed in the current environment.

fix

pip install sqllineage

AttributeError: 'LineageResult' object has no attribute 'source_tables'

The `LineageResult` object provides source and target tables via its `read` and `write` attributes, not directly as `source_tables` or `target_tables`.

fix

Access the input tables using `result.read` and output tables using `result.write`.

KeyError: 'some_unsupported_dialect'

An invalid or unsupported SQL dialect string was provided to the `dialect` parameter when extracting lineage.

fix

Use one of the officially supported dialects such as `'ansi'`, `'bigquery'`, `'databricks'`, `'hive'`, `'mssql'`, `'mysql'`, `'postgres'`, `'redshift'`, `'snowflake'`, `'sparksql'`, or `'tsql'`.

ModuleNotFoundError: No module named 'sqlfluff'

The `sqlfluff` library, a conditional dependency required for column-level lineage, is not installed.

fix

Install `sqllineage` with the `sqlfluff` extra using `pip install sqllineage[sqlfluff]` or install `sqlfluff` separately via `pip install sqlfluff`.

Upgrade

Version history

1.5.8latest on PyPI · released May 16, 2026

Audit

Dependencies

sqlfluffrequiredCore SQL parsing engine.

sqlparserequiredCore SQL parsing engine.

networkxrequiredDefault graph operator for lineage representation.

sqlalchemyoptionalRequired for MetaDataProviders to enhance column lineage accuracy by retrieving metadata from SQL databases.

rustworkxoptionalExperimental alternative graph operator for improved performance on large SQL/graphs.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/reata/sqllineage ↗

packagehttps://pypi.org/project/sqllineage/ ↗

homepagehttps://reata.github.io/sqllineage/ ↗

docshttps://sqllineage.readthedocs.io/en/latest/ ↗

changeloghttps://github.com/reata/sqllineage/releases ↗