# dj-database-url > Use Database URLs in your Django Application. - **URL**: https://www.freshcrate.ai/projects/dj-database-url - **Author**: Jazzband community - **Category**: Databases - **Latest version**: `3.1.2` (2026-04-21) - **License**: Unknown - **Source**: https://github.com/jazzband/dj-database-url/issues - **Homepage**: https://pypi.org/project/dj-database-url/ - **Language**: Python - **GitHub**: 1,573 stars, 216 forks - **Registry**: pypi (`dj-database-url`) - **Tags**: `pypi` ## 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 `_ 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 `_ 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 ## Recent releases | Version | Date | Urgency | Changes | | --- | --- | --- | --- | | `3.1.2` | 2026-04-21 | Low | Imported from PyPI (3.1.2) | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | | `v3.1.2` | 2026-02-19 | Low | ## What's Changed * Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/293 * Bump django from 5.2.9 to 5.2.11 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/294 * Bump urllib3 from 2.6.2 to 2.6.3 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/295 * Bump wheel from 0.45.1 to 0.46.2 by @dependabot[bot] in https://github.com/jazzband/dj-database-url/pull/296 * [pre-commit.ci] pre-comm | ## Citation - HTML: https://www.freshcrate.ai/projects/dj-database-url - Markdown: https://www.freshcrate.ai/projects/dj-database-url.md - Dependencies JSON: https://www.freshcrate.ai/api/projects/dj-database-url/deps _Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._