Oracle Database Python Driver

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.

Install

• pip install oracledb Install latest version

Imports

• oracledb

  import oracledb

• connect

  oracledb.connect(...)

Quickstart

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.")