dj-database-url 2.0.0

Supported Databases

Support currently exists for PostgreSQL, PostGIS, MySQL, MySQL (GIS), Oracle, Oracle (GIS), Redshift, CockroachDB, Timescale, Timescale (GIS) and SQLite.

Installation

Installation is simple:

$ pip install dj-database-url

Usage

1. If DATABASES is already defined:

• Configure your database in settings.py from DATABASE_URL:

  import dj_database_url
  
  DATABASES['default'] = dj_database_url.config(
      conn_max_age=600,
      conn_health_checks=True,
  )

• Provide a default:

  DATABASES['default'] = dj_database_url.config(
      default='postgres://...',
      conn_max_age=600,
      conn_health_checks=True,
  )

• Parse an arbitrary Database URL:

  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:

  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:

  DATABASES = {
      'default': dj_database_url.config(
          default='postgres://...',
          conn_max_age=600,
          conn_health_checks=True,
      )
  }

• Parse an arbitrary Database URL:

  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_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.

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:

postgres://user:p#ssword!@localhost/foobar

and should instead be passed as:

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'})

URL schema

Contributing

We welcome contributions to this project. Projects can take two forms:

1. Raising issues or helping others through the github issue tracker.

2. Contributing code.