Oracle Database Python Driver

3.4.2 verified Tue May 12 auth: no python install: draft

oracledb is the official Oracle Database adapter for Python, designed to connect Python applications directly to Oracle Database. It is the successor to the popular cx_Oracle driver, providing a modern, high-performance interface that conforms to the Python Database API v2.0 Specification. It features both a 'Thin' mode, which requires no Oracle Client libraries, and an optional 'Thick' mode for advanced functionalities. The library is actively maintained by Oracle, with frequent releases; the current version is 3.4.2.

pip install oracledb

Common errors

error ModuleNotFoundError: No module named 'oracledb' ↓

cause The 'oracledb' package is either not installed in the active Python environment or the Python interpreter being used cannot find it. This often happens in virtual environments or when multiple Python installations exist.

fix

Ensure you have the 'oracledb' library installed in your current Python environment by running: python -m pip install oracledb. If using an IDE, confirm it's configured to use the correct Python interpreter where 'oracledb' is installed.

error DPI-1047: Oracle Client library cannot be loaded ↓

cause This error occurs when `oracledb` is attempting to use its 'Thick mode' (requiring Oracle Client libraries), but it cannot find the necessary Oracle Client libraries or they are incompatible (e.g., incorrect version, 32-bit vs. 64-bit mismatch, or missing environment variables/paths).

fix

If 'Thin mode' (default, no client libraries) meets your needs, remove any oracledb.init_oracle_client() calls. If 'Thick mode' is required: 1. Install the appropriate Oracle Instant Client libraries (matching your Python's bitness). 2. For Windows/macOS, pass the lib_dir parameter to oracledb.init_oracle_client() pointing to the Instant Client directory. 3. For Linux, ensure the Instant Client libraries are in the system's library search path (e.g., LD_LIBRARY_PATH environment variable set before Python starts, or configured via ldconfig). Never set ORACLE_HOME with Instant Client.

error ORA-12154: TNS:could not resolve the connect identifier specified ↓

cause The Oracle client cannot resolve the connection string or service name provided, usually due to an incorrect or missing entry in the `tnsnames.ora` file, an incorrectly configured `sqlnet.ora`, or an unreachable Oracle Listener.

fix

Verify the connection string for typos and ensure the service name is correctly defined in your tnsnames.ora file. Confirm that tnsnames.ora is accessible and in the expected location (or that the TNS_ADMIN environment variable points to its directory). Check that the Oracle Listener is running on the database server.

error DPY-6005: cannot connect to database. Connection failed with "[Errno 61] Connection refused" ↓

cause This `oracledb` Thin mode error indicates a network problem where the client application was unable to establish a connection with the database server. This commonly means the database listener is not running, the hostname or port is incorrect, or a firewall is blocking the connection.

fix

Verify that the Oracle Database listener is running on the specified host and port. Check network connectivity between your client and the database server. Ensure no firewalls (client or server side) are blocking the connection on the database port (default 1521). Double-check the hostname and port in your connection string.

error DPY-3010: connections to this database server version are not supported by python-oracledb in thin mode. ↓

cause This specific error occurs when `oracledb` in Thin mode attempts to connect to an older Oracle Database version (specifically 11.2 or earlier), which is not supported by Thin mode.

fix

To connect to Oracle Database 11.2 or earlier, enable oracledb Thick mode by installing Oracle Client libraries and calling oracledb.init_oracle_client() in your code. Alternatively, upgrade your Oracle Database to version 12.1 or later to use Thin mode.

Warnings

breaking oracledb is the renamed successor to cx_Oracle. While the API is largely compatible, all new development should use `oracledb` as `cx_Oracle` is now obsolete and no longer actively developed. The primary change is the import statement and the default 'Thin mode'. ↓

fix Replace `import cx_Oracle` with `import oracledb`. Review and update any explicit `cx_Oracle` class instantiations or methods, although most should be a drop-in replacement.

gotcha oracledb operates in two modes: 'Thin' (default, pure Python, no client libraries needed) and 'Thick' (requires Oracle Client libraries for extended features). You can only enable 'Thick mode' once per process by calling `oracledb.init_oracle_client()` *before* creating any connections or connection pools. Attempting to call it after connections are established will result in an error. ↓

fix Understand the differences between Thin and Thick modes. Call `oracledb.init_oracle_client()` at the very beginning of your application's lifecycle if 'Thick mode' functionality is required.

deprecated The `oracledb.makedsn()` method is deprecated. Modern code should construct connection strings directly using keyword arguments in `oracledb.connect()` or `oracledb.create_pool()`, or use an Easy Connect string. ↓

fix Instead of `dsn = oracledb.makedsn(host, port, service_name)`, use a formatted string directly like `dsn = f'{host}:{port}/{service_name}'` or pass keyword arguments: `oracledb.connect(host=host, port=port, service_name=service_name, ...)`

gotcha In 'Thin mode', `oracledb` does not support Oracle Database native network encryption or checksumming. If these are required, 'Thick mode' must be used, or TLS encryption can be enabled as an alternative. ↓

fix For native network encryption/checksumming, enable 'Thick mode' by installing Oracle Client libraries and calling `oracledb.init_oracle_client()`. Alternatively, configure TLS for secure connections in Thin mode.

gotcha When connecting to an Oracle Autonomous Database (ADB) in 'Thin mode' using a wallet, the `wallet_password` parameter in the connection string or `oracledb.connect()` is *not* your database user password. It is the password used to encrypt the ADB wallet itself, set when downloading the wallet from the Oracle Cloud Console. ↓

fix Ensure you are using the correct wallet password, distinct from your database user's password, when configuring ADB connections in Thin mode.

breaking The library failed to connect with `DPY-6005: cannot connect to database` and `Connection refused`. This error typically indicates that the specified database host or port is incorrect, the Oracle Database server or its listener is not running, or a firewall is blocking the connection. ↓

fix Verify that the database host, port, and service name (or SID) in your connection string are correct. Ensure the Oracle Database server and its listener are running and are accessible from the client machine. Check any relevant firewall rules between the client and the database server.

gotcha Installing `oracledb` from source (e.g., when a pre-built wheel is unavailable for your Python version and platform) requires a C compiler (like `gcc`) and Python development headers. Without these, the build process for its C extensions will fail. ↓

fix Ensure that build tools, including a C compiler (e.g., `build-base` package on Alpine Linux, or `build-essential` on Debian/Ubuntu) and Python development headers (e.g., `python3-dev` on Alpine for Python 3.x or `python3-dev` on Debian/Ubuntu), are installed in your environment before attempting to install `oracledb`.

Install compatibility draft last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) build_error - - - -

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 2.8s 0.25s 43M

3.10 slim (glibc) - - 0.29s 42M

3.11 alpine (musl) build_error - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 2.6s 0.67s 46M

3.11 slim (glibc) - - 0.60s 44M

3.12 alpine (musl) build_error - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 2.2s 0.73s 37M

3.12 slim (glibc) - - 0.84s 36M

3.13 alpine (musl) build_error - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 2.4s 0.71s 37M

3.13 slim (glibc) - - 0.83s 35M

3.9 alpine (musl) build_error - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 3.4s 0.36s 43M

3.9 slim (glibc) - - 0.32s 42M

Imports

oracledb
```
import oracledb
```
connect
```
oracledb.connect(...)
```

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to establish a connection to an Oracle Database using `oracledb` in its default Thin mode, execute a simple SQL query, and fetch the result. It uses environment variables for credentials to avoid hardcoding sensitive information.

import os
import oracledb

# Database credentials from environment variables for security
USERNAME = os.environ.get('ORACLE_DB_USER', 'your_username')
PASSWORD = os.environ.get('ORACLE_DB_PASSWORD', 'your_password')
CONNECT_STRING = os.environ.get('ORACLE_DB_DSN', 'localhost/orclpdb') # e.g., 'hostname:port/service_name'

try:
    # Establish a connection in Thin mode (default)
    with oracledb.connect(user=USERNAME, password=PASSWORD, dsn=CONNECT_STRING) as connection:
        print(f"Successfully connected to Oracle Database: {connection.version}")

        with connection.cursor() as cursor:
            # Execute a simple query
            cursor.execute("SELECT SYSDATE FROM DUAL")
            for row in cursor:
                print(f"Current database date: {row[0]}")

except oracledb.Error as e:
    error_obj, = e.args
    print(f"Error connecting to Oracle Database: {error_obj.message}")
    print("Please ensure ORACLE_DB_USER, ORACLE_DB_PASSWORD, and ORACLE_DB_DSN environment variables are set correctly,")
    print("or replace the placeholder values in the script.")