Django 5 and Oracle Autonomous Database

I’m posting this quick blog in the ‘so I can find it again’ category. The question came up about how to connect to Oracle Autonomous Database using Django and a wallet ZIP file.

Photo by Brecht Corbeel on Unsplash

Make sure Django and python-oracledb are up to date:

python3 -m pip install Django oracledb --upgrade

At time of writing, this installed Django 5.0.4 and python-oracledb 2.1.2.

Oracle ADB-S with 1-way TLS

If your Autonomous Database was created using the ‘Secure access from allowed IPs and VCNs only’ option which gives you 1-way TLS, then you will have allow-listed the machine (or network) where you are running Django. In this case, your Django settings.py DATABASES entry will be the standard Oracle username/password/connection strings for the database and you don’t need the wallet file. You can find the connection string by clicking the ‘Database connection’ button on the cloud console for the database, Changing the ‘TLS authentication’ drop-down in the ‘Connection Strings’ pane to be ‘TLS’, and then copying one of the connection strings.

Your Django settings.py file can then look like:

DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.oracle',
    'NAME': '(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=xxx.oraclecloud.com))(connect_data=(service_name=xxx_cjdb_high.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)))',
    'USER': 'admin',
    'PASSWORD': 'xxxxxxxxxx',
  }
}

On macOS, if you run your Django python3 manage.py runserver command and get an error like:

oracledb.exceptions.OperationalError: DPY-6005: cannot connect to database (CONNECTION_ID=xxxx).
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1000)

you can follow this solution and first run a command like:

/Applications/Python\ 3.12/install\ Certificates.command

(using the appropriate Python version path).

Oracle ADB-S with mTLS

However if your Autonomous Database was created with the ‘Secure access from everywhere’ setting, you will need to download and use the wallet.zip file containing the access certificate from the cloud console.

Download the wallet file by clicking the ‘Database connection’ button on the cloud console for the database. This will prompt you to create a wallet password.

Next, unzip the wallet file — it must be unzipped. In the example below, my directory /Users/cjones/CJMTLS contains the files:

  -rw-r--r--@  1 cjones  staff   3029 22 Apr 00:07 README
  -rw-r--r--@  1 cjones  staff   5349 22 Apr 00:07 cwallet.sso
  -rw-r--r--@  1 cjones  staff   5304 22 Apr 00:07 ewallet.p12
  -rw-r--r--@  1 cjones  staff   5710 22 Apr 00:07 ewallet.pem
  -rw-r--r--@  1 cjones  staff   3192 22 Apr 00:07 keystore.jks
  -rw-r--r--@  1 cjones  staff    691 22 Apr 00:07 ojdbc.properties
  -rw-r--r--@  1 cjones  staff    114 22 Apr 00:07 sqlnet.ora
  -rw-r--r--@  1 cjones  staff    768 22 Apr 00:07 tnsnames.ora
  -rw-r--r--@  1 cjones  staff   2056 22 Apr 00:07 truststore.jks

Then your Django settings.py file will need to contain this:

DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.oracle',
    'NAME': 'cjmtls_high',
    'USER': 'admin',
    'PASSWORD': 'xxxxxxxxxxxx',
    'OPTIONS': {
        "config_dir": "/Users/cjones/CJMTLS",
        "wallet_location": "/Users/cjones/CJMTLS",
        "wallet_password": "xxxxxxxxxx"
    }
  }
}

The NAME field is one of the connection aliases in the tnsnames.ora file. This file is read from the “config_dir” folder. Note that you have to supply the wallet directory location in “wallet_location”, and also the wallet password to open the PEM file. This is the password you created when you downloaded the wallet.zip file. This password is needed at runtime in the default ‘Thin’ mode of the python-oracledb driver.

For python-oracledb Thick mode use — which requires different settings, and for general background, see the python-oracledb doc Connecting to Oracle Cloud Autonomous Databases.