Registry / workflow / apache-airflow-providers-jdbc

apache-airflow-providers-jdbc

JSON →
library5.5.1pypypi✓ verified 23d ago

The Apache Airflow JDBC Provider extends Airflow's functionality by enabling interaction with JDBC-compatible databases through specialized hooks and operators. It is part of the larger Apache Airflow ecosystem, with frequent releases that align with new Airflow versions and community contributions. The current version is 5.4.2.

pip install apache-airflow-providers-jdbc
INSTALL
IMPORT
SIG · APACHE-AIRFLOW-PRO
A
apache-airflow-providers-jdbc
workflowpythonv5.5.1
Install
24.4s avg
Import
5054ms
Disk
257MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
build_error
glibc
py 3.103.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.
fix
Replace `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`).
fix
Upgrade 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.
fix
Install 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`.
fix
If 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.
fix
To 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.
fix
Install 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.
fix
Ensure 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.
fix
Verify 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.
fix
Ensure 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.
fix
Verify 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.
Agent activity
50 hits · last 30 days
node
42
OpenAI (training)
3
Resources
apache-airflow-providers-jdbc — pip install apache-airflow-providers-jdbc · libregistry