Add service URI parsing support

[codingjoe]

Code of Conduct

• I agree to follow Django's Code of Conduct

Package Information

• dj-database-url
• django-service-urls

Problem

With the JazzBand sailing off into the sunset and dj-database-url being one of the most downloaded Django packages on PyPi, I'd love to make a push to add a URL settings parser to Django.

Rationale

URI-based credentials have become the norm for most datastores. From RDBs to KV stores, their CLIs usually support URIs natively. Yet Django doesn't, even though the 12-factor-fanclub and the Django community are heavily overlapping.

I believe most people don't spend a second thought before installing dj-database-url by default. However, with the JazzBand end, I think this package has earned its spot in Django's utils and future DSF support.

Scope limitation

This proposal does NOT aim to include environment parsing. The proposal is limited to parsing URIs into service setting objects. Nothing more. URI may be provided however a user chooses to. 3rd-parties may expand on the parser and use it to provide narrower integrations.

Additional Details

#8562
ticket-28236

Implementation Details

I am not saying to include the whole package, but the dictionary parser.

Especially with the email setting becoming a dictionary too. We can provide a neat experience for external services.

Something like

from django.conf.utils import parse_service_uri

DATABASE = {
    "default": parse_service_uri(os.getenv("DATABASE_URL")),
}

CACHES = {
    "default": parse_service_uri(os.getenv("REDIS_URL"), options={
        "pool_class": "redis.BlockingConnectionPool"
    }),
}

[github-actions]

Thank you codingjoe for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[codingjoe]

Noticed there already is an accepted issue on trac: ticket-28236

[codingjoe]

I had perplexity dig up the decade of history on this ticket.

---

Django ticket #28236 proposes integrating dj-database-url‑style functionality into Django so database (and later cache) configuration can be expressed as URLs, with an optional convention of reading a DATABASE_URL environment variable. From the later PR discussion and the linked mailing‑list thread, core developers preferred a smaller, more explicit feature: a helper that converts a URL string into a Django DATABASES‑style dict, without Django itself automatically reading DATABASE_URL or otherwise “blessing” that environment variable. cloud.google

Ticket and PR summary

• The ticket (opened by Kenneth Reitz) asks to “integrate dj-database-url into Django,” highlighting two benefits:
  1. representing database settings as a single URL string, and
  2. automatically using the DATABASE_URL environment variable if present. cloud.google
• The ticket notes this was discussed informally in the past and argues it would “vastly improve the usability of Django,” especially for 12‑factor‑style deployments. cloud.google
• Tom Forbes (orf) opened PR #8562 “Fixed #28236 – Integrate dj-database-url into Django,” initially copying much of dj-database-url’s parsing logic and tests into Django, then iterating on a more class‑based, extensible design. django.readthedocs

In later revisions, the PR:

• Introduces a generic URL‑config module and a registry for backends, plus config_from_url classmethods on database backends and cache backends, so URLs can be mapped to connection dictionaries and extended by third‑party backends. django.readthedocs
• Adds support for configuring both DATABASES and CACHES via URLs, and reworks the parsing to return a mutable dict rather than a namedtuple. django.readthedocs

What was missing from the original submission

Two different “original submissions” matter here: the ticket itself and the first iterations of the PR.

From the ticket side:

• The ticket jumps straight to “integrate dj-database-url into core” without first going through the Django‑developers mailing list for broader design discussion; a core dev explicitly comments on the ticket that proposals like this are better discussed on the Developers mailing list for more feedback. cloud.google
• The ticket’s scope includes both “URL parsing” and “automatically use DATABASE_URL,” but it doesn’t separate those concerns or argue why Django should own the DATABASE_URL convention rather than just provide parsing utilities. groups.google

From the PR side:

• The PR author himself notes at one point that documentation is still missing and needs to be written before the feature can be considered ready. django.readthedocs
• Review comments also point out missing or unclear API documentation for people implementing custom database or cache backends, for example around the requirement that custom DB backends expose a .base.DatabaseWrapper and have a config_from_url method. django.readthedocs
• Reviewers raise open design questions on overriding parts of the parsed configuration (e.g. nested OPTIONS) and on how consistent cache integration should be with database integration; the PR acknowledges these need further thought. django.readthedocs

So, in short, the original submission lacked:

• Prior design consensus from the mailing list about how big the feature should be and how it should interact with settings and env vars.
• Fully fleshed‑out documentation and a clearly locked‑down public API for third‑party backends.
• A narrowed, agreed‑upon scope that the core team was comfortable supporting long‑term.

Preferred scope from the PR comment / mailing‑list discussion

A later discussion on the Django‑developers list (“Potential way forward for DATABASE_URL”) is referenced in the PR discussion and effectively captures the maintainers’ preferred scope. groups.google

Key points from that discussion:

• Django today expects DATABASES to be a dictionary; many users install dj-database-url or similar libraries, which take a URL from an environment variable and return that dictionary. github
• The suggested core feature is a helper that takes a URL string and returns a Django database configuration dict, so you can write something like:

  from django.conf import db_url  # hypothetical helper
  DATABASES = {
      "default": configure_db(os.environ["DATABASE_URL"]),
  }

  rather than having Django itself read environment variables or bless any particular env var name. groups.google
• The mailing‑list author explicitly notes that what’s “notably absent” from their proposal is any “blessing” of DATABASE_URL: you still write os.environ["DATABASE_URL"] yourself; Django doesn’t automatically pick it up. groups.google
• They argue that this explicit pattern is “good enough,” easier to debug (no hidden magic), and avoids Django being responsible for all the edge‑cases and compatibility behavior that dj-database-url has accreted over time. pypi

Putting that together:

• Preferred scope:
  • Provide a built‑in converter from a DSN/URL string → DATABASES‑style dict.
  • Possibly make it generic enough that cache URLs and other “service URLs” could use the same mechanism, but that’s secondary and needs separate review. groups.google
  • Do not have Django automatically read DATABASE_URL (or any env var) or tightly couple Django to dj-database-url’s exact behavior. Users or third‑party packages remain responsible for environment handling. groups.google

So compared to the original ticket (“integrate dj-database-url, including automatic DATABASE_URL support”), the preferred direction is a smaller, explicit helper focused on parsing URL strings, leaving environment conventions and broader configuration orchestration outside Django core.