Description

DJ-Database-URL ~~~~~~~~~~~~~~~ .. image:: https://jazzband.co/static/img/badge.png :target: https://jazzband.co/ :alt: Jazzband .. image:: https://github.com/jazzband/dj-database-url/actions/workflows/test.yml/badge.svg :target: https://github.com/jazzband/dj-database-url/actions/workflows/test.yml .. image:: https://codecov.io/gh/jazzband/dj-database-url/branch/master/graph/badge.svg?token=7srBUpszOa :target: https://codecov.io/gh/jazzband/dj-database-url This simple Django utility allows you to utilize the `12factor <http://www.12factor.net/backing-services>`_ inspired ``DATABASE_URL`` environment variable to configure your Django application. The ``dj_database_url.config`` method returns a Django database connection dictionary, populated with all the data specified in your URL. There is also a `conn_max_age` argument to easily enable Django's connection pool. If you'd rather not use an environment variable, you can pass a URL in directly instead to ``dj_database_url.parse``. Installation ------------ Installation is simple: .. code-block:: console $ pip install dj-database-url Usage ----- 1. If ``DATABASES`` is already defined: - Configure your database in ``settings.py`` from ``DATABASE_URL``: .. code-block:: python import dj_database_url DATABASES['default'] = dj_database_url.config( conn_max_age=600, conn_health_checks=True, ) - Provide a default: .. code-block:: python DATABASES['default'] = dj_database_url.config( default='postgres://...', conn_max_age=600, conn_health_checks=True, ) - Parse an arbitrary Database URL: .. code-block:: python DATABASES['default'] = dj_database_url.parse( 'postgres://...', conn_max_age=600, conn_health_checks=True, ) 2. If ``DATABASES`` is not defined: - Configure your database in ``settings.py`` from ``DATABASE_URL``: .. code-block:: python import dj_database_url DATABASES = { 'default': dj_database_url.config( conn_max_age=600, conn_health_checks=True, ), } - You can provide a default, used if the ``DATABASE_URL`` setting is not defined: .. code-block:: python DATABASES = { 'default': dj_database_url.config( default='postgres://...', conn_max_age=600, conn_health_checks=True, ) } - Parse an arbitrary Database URL: .. code-block:: python DATABASES = { 'default': dj_database_url.parse( 'postgres://...', conn_max_age=600, conn_health_checks=True, ) } ``conn_max_age`` sets the |CONN_MAX_AGE setting|__, which tells Django to persist database connections between requests, up to the given lifetime in seconds. If you do not provide a value, it will follow Django’s default of ``0``. Setting it is recommended for performance. .. |CONN_MAX_AGE setting| replace:: ``CONN_MAX_AGE`` setting __ https://docs.djangoproject.com/en/stable/ref/settings/#conn-max-age ``conn_health_checks`` sets the |CONN_HEALTH_CHECKS setting|__ (new in Django 4.1), which tells Django to check a persisted connection still works at the start of each request. If you do not provide a value, it will follow Django’s default of ``False``. Enabling it is recommended if you set a non-zero ``conn_max_age``. .. |CONN_HEALTH_CHECKS setting| replace:: ``CONN_HEALTH_CHECKS`` setting __ https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks Strings passed to `dj_database_url` must be valid URLs; in particular, special characters must be url-encoded. The following url will raise a `ValueError`: .. code-block:: plaintext postgres://user:p#ssword!@localhost/foobar and should instead be passed as: .. code-block:: plaintext postgres://user:p%23ssword!@localhost/foobar `TEST <https://docs.djangoproject.com/en/stable/ref/settings/#test>`_ settings can be configured using the ``test_options`` attribute:: DATABASES['default'] = dj_database_url.config(default='postgres://...', test_options={'NAME': 'mytestdatabase'}) Supported Databases ------------------- Support currently exists for PostgreSQL, PostGIS, MySQL, MySQL (GIS), Oracle, Oracle (GIS), Redshift, CockroachDB, Timescale, Timescale (GIS) and SQLite. If you want to use some non-default backends, you need to register them first: .. code-block:: python import dj_database_url # registration should be performed only once dj_database_url.register("mysql-connector", "mysql.connector.django") assert dj_database_url.parse("mysql-connector://user:password@host:port/db-name") == { "ENGINE": "mysql.connector.django", # ...other connection params } Some backends need further config adjustments (e.g. oracle and mssql expect ``PORT`` to be a string). For such cases you can provide a post-processing function t