Django 5.0 supports python-oracledb natively

A new major release of Django is available with native support for python-oracledb.

Photo by De an Sun on Unsplash

This is a guest post by Suraj Shaw, a member of Oracle Database’s Technical Staff, who works on language drivers and frameworks.

Django is a high-level Python web framework. The Django tag line is “Django makes it easier to build better web apps more quickly and with less code.” Python-oracledb is an open source package for the Python Database API specification with many additions to support advanced Oracle Database features. It is the new name for the cx_Oracle driver

Django has long had support for Oracle Database’s cx_Oracle driver. Before Django 5.0, an additional code snippet was needed in your settings.py file to use the newer python-oracledb driver instead. But now from Django 5.0 that code is not required and python-oracledb can be used directly. (See this blog if you using older Django versions and want to use oracledb).

To use Django 5.0, install Python 3.10, 3.11, or 3.12 and then install Django and python-oracledb 1.3.2 or later. For example with pip:

$ python -m pip install Django oracledb

The following will show the correct version if installation is successful:

$ python
>>> import django
>>> django.__version__
'5.0'

Now you can create a Django project with:

$ django-admin.py startproject myproject

To connect to Oracle Database, your settings.py file connection settings will be as normal, for example:

DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.oracle',
    'NAME': 'example.com:1521/orclpdb',
    'USER': 'scott',
    'PASSWORD': 'XXXX'
  }
}

Django gives preference to using python-oracledb. If python-oracledb is not found then cx_Oracle will be used. Settings are the same for these new and old drivers. Support for the old driver namespace is deprecated and will be removed in Django 6.0.

Start the server with python manage.py runserver. The server will start on localhost:8000.

You can call init_oracle_client() in your code too, if you have Oracle Client libraries and want to use python-oracledb ‘Thick’ mode.

This example used an Easy Connect string to access the database. Many options can be added to the connection string to enhance the behavior.

A big thanks to the Django community and the Oracle team for making this change land in Django 5.0. Special thanks to Jingbei Li and Mariusz Felisiak for their big efforts.

python-oracledb References

Home page: oracle.github.io/python-oracledb/index.html

Installation instructions: python-oracledb.readthedocs.io/en/latest/installation.html

Documentation: python-oracledb.readthedocs.io/en/latest/index.html

Release Notes: python-oracledb.readthedocs.io/en/latest/release_notes.html

Discussions: github.com/oracle/python-oracledb/discussions

Issues: github.com/oracle/python-oracledb/issues

Source Code Repository: github.com/oracle/python-oracledb