{"id":1820,"library":"dj-database-url","title":"dj-database-url","description":"dj-database-url is a simple Django utility that allows you to configure your Django application's database using a single 12-factor inspired `DATABASE_URL` environment variable. It parses the URL and returns a Django-compatible database connection dictionary, supporting various backend types like PostgreSQL, MySQL, SQLite, and Oracle. Currently at version 3.1.2, it is actively maintained by the Jazzband community with regular updates.","status":"active","version":"3.1.2","language":"en","source_language":"en","source_url":"https://github.com/jazzband/dj-database-url","tags":["Django","database","configuration","12factor","environment variables","URL parsing","PostgreSQL","MySQL","SQLite","Oracle"],"install":[{"cmd":"pip install dj-database-url","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for PostgreSQL database connections (optional).","package":"psycopg2-binary","optional":true},{"reason":"Required for MySQL database connections (optional).","package":"mysqlclient","optional":true},{"reason":"Required for Oracle database connections (optional).","package":"cx_Oracle","optional":true}],"imports":[{"note":"Primary function for configuring from DATABASE_URL environment variable.","symbol":"config","correct":"from dj_database_url import config"},{"note":"Used to parse a database URL string directly.","symbol":"parse","correct":"from dj_database_url import parse"}],"quickstart":{"code":"import os\nimport dj_database_url\n\n# In your Django settings.py\nDATABASES = {\n    'default': dj_database_url.config(\n        default=os.environ.get('DATABASE_URL', 'sqlite:///db.sqlite3'),\n        conn_max_age=600,\n        conn_health_checks=True,\n    )\n}\n\n# Example of how DATABASE_URL might be set in your environment (e.g., .env file or deployment config)\n# export DATABASE_URL=\"postgres://user:password@host:port/dbname\"\n# export DATABASE_URL=\"sqlite:///path/to/my/db.sqlite3\"","lang":"python","description":"To quickly set up `dj-database-url` in your Django `settings.py`, use the `config()` function. It reads the `DATABASE_URL` environment variable, falling back to a SQLite default if not present. It's recommended to include `conn_max_age` and `conn_health_checks` for production reliability."},"warnings":[{"fix":"Review the official documentation for the new registry pattern if you have custom database string implementations or are extending functionality. Ensure your Python and Django versions meet the new requirements (e.g., Python >=3.10, Django >=4.x).","message":"Version 3.0.0 introduced a new decorator registry pattern for database connection string checks and broke some API compatibility. It also updated supported Python and Django versions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Python environment to 3.9+ (preferably 3.10+) and your Django project to Django 4.0+.","message":"Version 2.3.0 removed support for Python 3.8 and Django 3.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"Pass `conn_max_age=600` (or another appropriate value) and `conn_health_checks=True` to `dj_database_url.config()`.","message":"For performance and reliability in production, it's highly recommended to explicitly set `conn_max_age` (for persistent connections) and `conn_health_checks` (for checking connection validity) when using `dj_database_url.config()`.","severity":"gotcha","affected_versions":"All"},{"fix":"Use the `sqlite:////` prefix for absolute file paths, or `sqlite:///./relative/path.sqlite3` for relative paths.","message":"When connecting to SQLite with an absolute file path, ensure you use four slashes (e.g., `sqlite:////full/path/to/your/database/file.sqlite`). The extra slashes are necessary because the 'file' portion is treated as the database's filename, not a hostname.","severity":"gotcha","affected_versions":"All"},{"fix":"Format Oracle URLs with `user:pass@host:port/dbname` or use DSN/TNS in the `NAME` part as per Oracle's connection string specifications, ensuring proper colon separation for user/password.","message":"Oracle database URLs expect the format `user:password` separated by a colon, not a forward slash as sometimes seen in other Oracle tools. You can also omit `HOST` and `PORT` and provide a full DSN string or TNS name in the `NAME` part of the URL.","severity":"gotcha","affected_versions":"All"},{"fix":"Always provide a `default` argument to `dj_database_url.config()` (e.g., `default='sqlite:///db.sqlite3'`) or ensure the `DATABASE_URL` environment variable is set in your execution environment.","message":"`dj_database_url.config()` will raise a `UserWarning` if no `DATABASE_URL` environment variable is set and no `default` URL is provided in the function call.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}