Registry /
workflow / apache-airflow-providers-common-sql
The `apache-airflow-providers-common-sql` package provides a foundational set of SQL-related functionalities for Apache Airflow, including operators, hooks, sensors, and triggers for interacting with various SQL databases. It leverages SQLAlchemy for seamless integration and simplifies connection management. As of its current version 1.34.0, it is actively maintained with regular updates.
Install & Compatibility
Where this runs
tested against v2.0.1 · 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
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 5.406s · 250.1MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 23.4s · import 5.035s · 248MB
250MB installed
● package 250MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SQLExecuteQueryOperator
✓ from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
SQLColumnCheckOperator
✓ from airflow.providers.common.sql.operators.sql import SQLColumnCheckOperator
SQLTableCheckOperator
✓ from airflow.providers.common.sql.operators.sql import SQLTableCheckOperator
DbApiHook
✓ from airflow.providers.common.sql.hooks.sql import DbApiHook
SqlSensor
✓ from airflow.providers.common.sql.sensors.sql import SqlSensor
This quickstart demonstrates how to define a simple Airflow DAG using the `SQLExecuteQueryOperator` to execute SQL queries. It shows both a direct SQL string execution and an example of a templated SQL query that could load from a file.
from airflow import DAG
from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
from datetime import datetime
with DAG(
'sql_example_dag',
start_date=datetime(2023, 1, 1),
schedule_interval=None,
catchup=False,
tags=['sql', 'example']
) as dag:
# Ensure 'my_database_conn' is configured in Airflow Connections
execute_query_task = SQLExecuteQueryOperator(
task_id='run_simple_sql_query',
conn_id='my_database_conn',
sql='SELECT 1;'
)
# Example of running a SQL query from a file
# For this to work, you would typically place 'my_query.sql' in your DAGs folder's 'include' directory,
# or set the template_searchpath in the DAG definition.
# For demonstration, we'll use a placeholder string.
execute_templated_query = SQLExecuteQueryOperator(
task_id='run_templated_sql_query',
conn_id='my_database_conn',
sql="""SELECT * FROM users WHERE registration_date < '{{ ds }}';""",
parameters={'table_name': 'users'}
)
Debug
Known issues
breakingProvider version 1.33.0 (and later) removes all deprecated classes, parameters, and features. Users with very old provider versions or custom code relying on private functions of `common.sql` might experience issues. This release is only available for Airflow 2.9+.fixUpgrade Airflow to at least 2.9.0 and refactor DAGs to use current, non-deprecated APIs. Consult the official changelog for specific removals.
affects: >=1.33.0
breakingThe `apache-airflow-providers-common-sql==1.3.0` release was known to break BigQuery operators from `apache-airflow-providers-google==8.4.0` due to implicit dependencies and refactoring. This resulted in `1.3.0` being yanked.fixAvoid installing `apache-airflow-providers-common-sql==1.3.0`. Downgrade to `1.2.0` or upgrade to a later compatible version (e.g., `1.3.4` or newer for common-sql, and potentially `8.5.0` or newer for google provider, depending on Airflow version).
affects: 1.3.0
breakingProvider versions `1.3.0` and `1.5.0` were yanked from PyPI due to potential issues: `1.3.0` broke BigQuery operators, and `1.5.0` could cause unconstrained installation of old Airflow versions leading to `RuntimeError`.fixDo not use `apache-airflow-providers-common-sql==1.3.0` or `==1.5.0`. Ensure your `requirements.txt` or `pip install` commands specify a working version range.
affects: 1.3.0, 1.5.0
gotchaThe `apache-airflow-providers-common-sql` package is preinstalled by default with Apache Airflow (since Airflow 2.4.0+). While it can be upgraded independently, attempting to install it separately on a system with an older Airflow version (e.g., <2.4.0) will fail at runtime, even if not explicitly specified in dependencies, due to internal compatibility checks.fixEnsure your Airflow installation meets the minimum requirement for the desired provider version (e.g., Airflow 2.11.0 for provider 1.33.0+). Do not attempt to install this provider with Airflow versions lower than its minimum requirement.
affects: <2.4.0 (for Airflow version)
breakingA SQL Injection vulnerability (CVE-2025-30473) existed in `SQLTableCheckOperator` when using the `partition_clause` parameter with externally-influenced input. An authenticated UI user could inject arbitrary SQL commands.fixUpgrade `apache-airflow-providers-common-sql` to version `1.24.1` or higher to fix this vulnerability.
affects: <1.24.1
breakingThe `schedule_interval` parameter in the `DAG` class was deprecated in Airflow 2.0 and completely removed in Airflow 2.2. Using it with Airflow versions 2.2.0 or newer will result in a `TypeError`.fixRefactor your DAG definition to use the `schedule` parameter instead of `schedule_interval` (e.g., `schedule='@daily'` or `schedule=timedelta(days=1)`).
affects: apache-airflow>=2.2.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers.common.sql'
The 'apache-airflow-providers-common-sql' package is not installed.
fixpip install apache-airflow-providers-common-sql
ImportError: cannot import name 'SQLExecuteQueryOperator' from 'airflow.providers.common.sql.operators.sql'
The 'SQLExecuteQueryOperator' class is not available in the installed version of 'apache-airflow-providers-common-sql'.
fixUpgrade to a version where 'SQLExecuteQueryOperator' is available, e.g., 'pip install apache-airflow-providers-common-sql>=1.3.0'
AttributeError: module 'airflow.providers.common.sql.hooks.sql' has no attribute 'DbApiHook'
The 'DbApiHook' class has been moved or renamed in the 'apache-airflow-providers-common-sql' package.
fixUpdate the import statement to 'from airflow.hooks.dbapi import DbApiHook'
TypeError: 'NoneType' object is not iterable
The 'SQLExecuteQueryOperator' is returning 'None' due to an issue with the 'split_statements' parameter.
fixEnsure that the 'split_statements' parameter is set correctly, or upgrade to a version where this issue is resolved.
ImportError: cannot import name 'SQLCheckOperator' from 'airflow.providers.common.sql.operators.sql'
The 'SQLCheckOperator' class is not available in the installed version of 'apache-airflow-providers-common-sql'.
fixUpgrade to a version where 'SQLCheckOperator' is available, e.g., 'pip install apache-airflow-providers-common-sql>=1.1.0'
Audit
Dependencies
sqlparserequiredRequired for SQL parsing capabilities within some operators.
apache-airflowrequiredThis is an Airflow provider; it requires Apache Airflow. Minimum supported version is 2.11.0 (for provider version 1.33.0+), though earlier provider versions supported Airflow 2.4.0+.