dj-database-url 3.1.2

Installation

Installation is simple:

$ pipinstalldj-database-url

Usage

1. If DATABASES is already defined:

• Configure your database in settings.py from DATABASE_URL:

  importdj_database_urlDATABASES['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:

  importdj_database_urlDATABASES = { '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'})

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:

importdj_database_url# registration should be performed only oncedj_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 to register() (note that register() is used as a decorator(!) in this case):

importdj_database_url@dj_database_url.register("mssql", "sql_server.pyodbc")defstringify_port(config): config["PORT"] = str(config["PORT"])@dj_database_url.register("redshift", "django_redshift_backend")defapply_current_schema(config): options = config["OPTIONS"] schema = options.pop("currentSchema", None) if schema: options["options"] = f"-c search_path={schema}"@dj_database_url.register("snowflake", "django_snowflake")defadjust_snowflake_config(config): config.pop("PORT", None) config["ACCOUNT"] = config.pop("HOST") name, _, schema = config["NAME"].partition("/") if schema: config["SCHEMA"] = schema config["NAME"] = name options = config.get("OPTIONS", {}) warehouse = options.pop("warehouse", None) if warehouse: config["WAREHOUSE"] = warehouse role = options.pop("role", None) if role: config["ROLE"] = role

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.