Registry /
workflow / apache-airflow-providers-jdbc
Install & Compatibility
Where this runs
tested against v5.5.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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 24.4s · import 5.054s · 256MB
257MB installed
● package 257MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JdbcHook
✓ from airflow.providers.jdbc.hooks.jdbc import JdbcHook
SQLExecuteQueryOperator
✓ from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
✗ from airflow.providers.jdbc.operators.jdbc import JdbcOperator
The `JdbcOperator` has been deprecated and removed in recent versions of the provider. Use `SQLExecuteQueryOperator` from `common.sql` instead.
This quickstart demonstrates how to use the `SQLExecuteQueryOperator` to interact with a JDBC-compatible database. It requires a pre-configured Airflow connection, a JVM, the `JAVA_HOME` environment variable, and the specific JDBC driver JAR file for your database. The `SQLExecuteQueryOperator` can execute single or multiple SQL queries. For fetching results, a `handler` callable can be provided. Make sure to replace placeholder values for the JDBC connection details and SQL queries with your actual data.
from __future__ import annotations
import os
from airflow.models.dag import DAG
from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
from airflow.utils.dates import days_ago
with DAG(
dag_id='example_jdbc_sql_query',
start_date=days_ago(1),
schedule_interval=None,
catchup=False,
tags=['jdbc', 'example', 'sql'],
) as dag:
# To run this DAG, ensure you have:
# 1. A JVM installed and JAVA_HOME environment variable set.
# 2. The specific JDBC driver JAR file for your database available (e.g., /path/to/your/driver.jar).
# 3. An Airflow JDBC connection configured with:
# - Conn Id: 'my_jdbc_connection'
# - Conn Type: 'JDBC Connection'
# - Host: 'jdbc:<vendor>://<host>:<port>/<database>' (the full JDBC URL)
# - Login: '<username>'
# - Password: '<password>'
# - Extra: {'driver_path': '/path/to/your/driver.jar', 'driver_class': 'com.vendor.DriverClass'}
# Refer to official documentation for specific database driver_class and driver_path values.
# Example 1: Execute a SELECT query
execute_select_query = SQLExecuteQueryOperator(
task_id='execute_select_query',
conn_id='my_jdbc_connection',
sql="SELECT * FROM example_table WHERE status = 'active';",
handler=lambda cursor: [row for row in cursor], # Example handler to fetch results
)
# Example 2: Execute an INSERT statement
execute_insert_statement = SQLExecuteQueryOperator(
task_id='execute_insert_statement',
conn_id='my_jdbc_connection',
sql="INSERT INTO log_table (event_time, message) VALUES (NOW(), 'Data processed successfully');",
autocommit=True,
)
execute_select_query >> execute_insert_statement
airflow --version
Debug
Known issues
breakingThe `JdbcOperator` has been deprecated and subsequently removed from the `apache-airflow-providers-jdbc` package. Users should migrate to `airflow.providers.common.sql.operators.sql.SQLExecuteQueryOperator` for executing SQL commands via JDBC.fixReplace `JdbcOperator` imports and usage with `SQLExecuteQueryOperator`. The parameters `sql`, `conn_id`, and `autocommit` are largely compatible.
affects: Provider versions 5.x.x and later. Deprecated in earlier 4.x versions, removed in 5.x.
breakingMinimum Apache Airflow version requirements have increased across provider versions. Ensure your Airflow installation meets the minimum version for the installed provider version to avoid issues related to API changes and decorator removals (e.g., `apply_default`).fixUpgrade your Apache Airflow installation to at least the minimum required version for the `apache-airflow-providers-jdbc` package you are using. If upgrading from Airflow < 2.1.0, manually run `airflow upgrade db` after the Airflow core upgrade.
affects: Provider versions >= 2.0.0 require Airflow >= 2.1.0; Provider versions >= 3.0.0 require Airflow >= 2.2.0; Provider versions >= 4.2.0 require Airflow >= 2.6.0; Provider version 5.4.2 requires Airflow >= 2.11.0.
gotchaConnecting to JDBC databases requires a properly configured Java environment, including a Java Virtual Machine (JVM), the `JAVA_HOME` environment variable set, and the specific JDBC driver `.jar` file for your database.fixInstall a JVM, set the `JAVA_HOME` environment variable to its installation path, and download the appropriate JDBC driver `.jar` file. Ensure `jaydebeapi` is installed in your Airflow environment.
affects: All versions
gotchaFor security reasons, `allow_driver_class_in_extra` and `allow_driver_path_in_extra` configuration options in `airflow.cfg` (under `[providers.jdbc]`) are `False` by default. If you need to specify `driver_class` or `driver_path` in the Airflow Connection's 'Extra' field, these options must be explicitly set to `True`.fixIf safe to do so in your environment, set `allow_driver_class_in_extra = True` and/or `allow_driver_path_in_extra = True` in your `airflow.cfg` or via environment variables (e.g., `AIRFLOW__PROVIDERS_JDBC__ALLOW_DRIVER_CLASS_IN_EXTRA=True`). Exercise caution as enabling these allows users to specify custom drivers and paths via the UI, which could have security implications if not properly managed.
affects: Provider versions >= 4.0.0
gotchaThe `JdbcOperator` (when it was in use) and `SQLExecuteQueryOperator` primarily execute SQL statements and do not automatically return query results to logs or XComs. To fetch results from a `SELECT` query, you typically need to use the `JdbcHook` directly or provide a `handler` callable to the operator.fixTo fetch results, use `JdbcHook.get_pandas_df()` within a `PythonOperator` or define a `handler` function for the `SQLExecuteQueryOperator` to process the `cursor` object.
affects: All versions for `JdbcHook`, `SQLExecuteQueryOperator`
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers.jdbc'
The 'apache-airflow-providers-jdbc' package is not installed or not properly configured.
fixInstall the package using 'pip install apache-airflow-providers-jdbc'.
RuntimeException: Class com.mysql.cj.jdbc.Driver not found
The JDBC driver class is not found because the JAR file is missing or the classpath is not set correctly.
fixEnsure the JDBC driver JAR is placed in the correct directory and the classpath is set properly.
The conn_id <random string> isn't defined
The connection ID specified in the Airflow UI does not exist or is misconfigured.
fixVerify that the connection ID is correctly defined in Airflow's connections and that all required fields are properly set.
java.lang.RuntimeException: driver class not found
The specified JDBC driver class or its corresponding JAR file is not found in the Java Classpath accessible by the Airflow environment. This often means the driver JAR is missing or the `driver_path` and `driver_class` are incorrectly configured.
fixEnsure the JDBC driver JAR file is present in a location accessible to Airflow (e.g., in a DAGs folder or a mounted volume), and correctly specify the `driver_class` and `driver_path` in your Airflow JDBC connection's 'Extra' field or directly in your `JdbcHook` instantiation. Also, confirm a Java Virtual Machine (JVM) is installed and `JAVA_HOME` is set.
Connection Refused / Password authentication failed for user
The Airflow JDBC connection parameters (host, port, username, password, or JDBC URL) are incorrect, preventing a successful connection to the database, or the database server is not running/accessible.
fixVerify all connection details in the Airflow UI (or your connection string) including host, port, username, and password. Ensure the database server is running and network accessible from where Airflow is running.
Upgrade
Version history
5.5.1latest on PyPI · released Aug 23, 2026
Audit
Dependencies
apache-airflowrequiredCore Apache Airflow installation is required.
jaydebeapirequiredPython DB-API 2.0 adapter for JDBC.
apache-airflow-providers-common-compatrequiredCross-provider dependency for compatibility.
apache-airflow-providers-common-sqlrequiredCommon SQL functionality for providers, which includes SQLExecuteQueryOperator.
JVM (Java Virtual Machine)requiredRequired to run JDBC drivers.
JAVA_HOME environment variablerequiredMust be set to the path of your JVM installation.
JDBC driver JAR file for your specific databaserequiredRequired to connect to the target database.