Connect Python Applications Using TLS

You can connect Python applications to your Autonomous Database instance without a walletusing TLS. Connecting a Python application without a wallet (TLS)with TLS provides security for authentication and encryption, and security is enforced using client credentials (by providing a username and password).

The Python python-oracledb driver's default "Thin mode" connects directly to Oracle Database. It can optionally use Oracle Client libraries ("Thick mode") for some additional functionality. The Oracle Client libraries can be from Oracle Instant Client, the full Oracle Client, or an Oracle Database installation.

Follow these steps to connect your Python application to an Autonomous Database instance without a wallet (TLS)using TLS:

  1. Install Python and the python-oracledb Driver

  2. Enable TLS on Autonomous Database and Obtain Connection String

  3. Run Python Application Without a WalletUsing TLS

See Enabling python-oracledb Thick mode for information on Thick mode.

Install Python and the python-oracledb Driver

To connect to Autonomous Database from your Python application, install Python and the python-oracledb driver.

  1. Install Python 3, if it is not already available.

    The version of Python depends on the client-side operating system:

    For example, on the following operating systems you can use:

    • On Windows, use Python 3.7 to 3.10

    • On macOS, use Python 3.7 to 3.10

    • On Linux, use Python 3.6 to 3.10

  2. Install the python-oracledb driver from PyPI.

    The python-oracledb driver is a Python programming language extension module allowing Python programs to connect to Oracle Database. It is the renamed, new major release of the popular cx_Oracle driver.

    Run the following command to upgrade python:

    python -m pip install oracledb --upgrade

    You should see output similar to the following:

    Collecting oracledb
      Downloading oracledb-1.0.3-cp310-cp310-win_amd64.whl (1.0 MB)
         ---------------------------------------- 1.0/1.0 MB 1.8 MB/s eta 0:00:00
    Collecting cryptography>=3.4
      Downloading cryptography-37.0.4-cp36-abi3-win_amd64.whl (2.4 MB)
         ---------------------------------------- 2.4/2.4 MB 3.5 MB/s eta 0:00:00
    Collecting cffi>=1.12
      Downloading cffi-1.15.1-cp310-cp310-win_amd64.whl (179 kB)
         ---------------------------------------- 179.1/179.1 kB 5.4 MB/s eta 0:00:00
    Collecting pycparser
      Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)
         ---------------------------------------- 118.7/118.7 kB 7.2 MB/s eta 0:00:00
    Installing collected packages: pycparser, cffi, cryptography, oracledb
    Successfully installed cffi-1.15.1 cryptography-37.0.4 oracledb-1.0.3 pycparser-2.21

    Notes for installing python-oracledb:

    • If you are behind a proxy, use the --proxy option to add a proxy server to the command. For example:

      python -m pip install oracledb --upgrade --proxy=http://proxy.example.com:80
    • In the case where you do not have permission to write to system directories, include the --user option. For example:

      python -m pip install oracledb --upgrade --user
    • If a binary package is not available for your platform, running pip will download the source package instead. The source is compiled and the resulting binary is installed.

    See Installing python-oracledb for additional options and tips.

  3. If you want to use the python-oracledb driver in Thick mode, install Oracle Client software.

    By default, python-oracledb runs in Thin mode which connects directly to Oracle Database. Thin mode does not require Oracle Client libraries. However, some additional functionality is available when python-oracledb runs in Thick mode.

    Note:

    See Oracle Database Features Supported by python-oracledb for information on supported features in python-oracledb Thin and Thick modes. Not all of the features shown in this link are available with Autonomous Database.

    Python-oracledb uses Thick mode when you use either the Oracle Instant client libraries or the Oracle Database Client libraries and you call oracledb.init_oracle_client() in your Python code.

    When you install Oracle Client Software, there are differences in required minimum versions for mTLS and TLS connections, as follows:

    • Mutual TLS (mTLS) Connections:

      • If your database is on a remote computer, then download the free Oracle Instant Client “Basic” or “Basic Light” package for your operating system architecture. Use Oracle Instant Client 12.1.0.2 (or higher).

      • Alternatively, you can use the Full Oracle Database client libraries when they are available on your system (including Full Oracle Database Client 11.2.0.4 or higher).

    • TLS Connections: Oracle Call Interface (OCI) clients support TLS authentication without a wallet if you are using the following client versions:

      • Oracle Instant Client/Oracle Database Client 19.14 (or later) and 21.5 (or later) - all platforms
      • Alternatively, you can use the Full Oracle Database client libraries when they are available on your system, including Full Oracle Database Client 19.14 (or later) and 21.5 (or later).

Enable TLS on Autonomous Database and Obtain Connection String

APPLIES TO: Applicable Exadata Cloud@Customer only

To run a Python application without a walletusing TLS, enable the Autonomous Database instance for TLS connections and obtain a connection string to contact the database from the Python application.
  1. Determine if your Autonomous Database instance is enabled for TLS connections.

    If the instance is enabled for TLS connections, in the Network area on the details page of the parent Autonomous VM Cluster (AVMC) resource shows One way TLS for Authentication Mode.

    If the instance is enabled for TLS connections, in the Network area on the Oracle Cloud Infrastructure Console the Mutual TLS (mTLS) authentication field shows: Not Required:

    Description of adb_mutual_tls_not_required.png follows
    Description of the illustration adb_mutual_tls_not_required.png

    If your instance requires Mutual TLS authentication, allow TLS connections on your Autonomous Database instance. See Update your Autonomous Database Instance to Allow both TLS and mTLS Authentication for details.

  2. Obtain an Autonomous Database service connection string to access the database as follows:
    1. On the details page of your database, click DB Connection.
    2. Copy the Connection String for the database service you want to use with your application.
    1. On the Oracle Cloud Infrastructure Console, click DB Connection.
    2. Select TLS in the Database Connection dialog box, under Connection Strings, in the TLS Authentication drop-down list.

      Note:

      You must select TLS in the TLS Authentication drop-down to obtain the TLS connection strings before you copy a connection string (when the value is Mutual TLS the connection strings have different values and do not work with TLS connections).
    3. Copy the Connection String for the database service you want to use with your application.
    See for more information.

Run Python Application Without a WalletUsing TLS

A Python application can connect to your Autonomous Database instance without a wallet (TLS)with TLS using the database credentials and a connect descriptor.

  1. Obtain the connection string, as described in Enable TLS on Autonomous Database and Obtain Connection String.
  2. In your Python application set the following connection parameters to connect to an Autonomous Database instance:
    • dsn: Use the connection string to specify the desired database service name.
    • password: Specifies the database user password.
    • user: Specifies the database user.

    For example:

    cs='''(description = (retry_count=20)(retry_delay=3)(address=(protocol=tcps)
         (port=1522)(host=xxx.oraclecloud.com))
         (connect_data=(service_name=xxx.adb.oraclecloud.com))
         (security=(ssl_server_dn_match=yes)(ssl_server_cert_dn="CN=xxx.oraclecloud.com,OU=Oracle BMCS US,
          O=Oracle Corporation, L=Redwood City, T=California, C=US")))'''
    
    connection=oracledb.connect(
         user="admin",
         password=password,
         dsn=cs)
  3. If you want to connect in Thick mode, include oracledb.init_oracle_client() in your Python application.

    For example:

    cs='''(description = (retry_count=20)(retry_delay=3)(address=(protocol=tcps)
         (port=1522)(host=xxx.oraclecloud.com))
         (connect_data=(service_name=xxx.adb.oraclecloud.com))
         (security=(ssl_server_dn_match=yes)(ssl_server_cert_dn="CN=xxx.oraclecloud.com,OU=Oracle BMCS US,
          O=Oracle Corporation, L=Redwood City, T=California, C=US")))'''
    
    oracledb.init_oracle_client()
    connection=oracledb.connect(
         user="admin",
         password=password,
         dsn=cs)