Use Database URLs in your Django Application.

Related tags

Djangodj-database-url
Overview

DJ-Database-URL

https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fjacobian%2Fdj-database-url%2Fbadge&style=for-the-badge

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.

Supported Databases

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

Installation

Installation is simple:

$ pip install dj-database-url

Usage

Configure your database in settings.py from DATABASE_URL:

import dj_database_url

DATABASES['default'] = dj_database_url.config(conn_max_age=600)

Provide a default:

DATABASES['default'] = dj_database_url.config(default='postgres://...')

Parse an arbitrary Database URL:

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

The conn_max_age attribute is the lifetime of a database connection in seconds and is available in Django 1.6+. If you do not set a value, it will default to 0 which is Django's historical behavior of using a new database connection on each request. Use None for unlimited persistent connections.

URL schema

Engine Django Backend URL
PostgreSQL django.db.backends.postgresql [1] postgres://USER:[email protected]:PORT/NAME [2]
PostGIS django.contrib.gis.db.backends.postgis postgis://USER:[email protected]:PORT/NAME
MSSQL sql_server.pyodbc mssql://USER:[email protected]:PORT/NAME
MySQL django.db.backends.mysql mysql://USER:[email protected]:PORT/NAME
MySQL (GIS) django.contrib.gis.db.backends.mysql mysqlgis://USER:[email protected]:PORT/NAME
SQLite django.db.backends.sqlite3 sqlite:///PATH [3]
SpatiaLite django.contrib.gis.db.backends.spatialite spatialite:///PATH [3]
Oracle django.db.backends.oracle oracle://USER:[email protected]:PORT/NAME [4]
Oracle (GIS) django.contrib.gis.db.backends.oracle oraclegis://USER:[email protected]:PORT/NAME
Redshift django_redshift_backend redshift://USER:[email protected]:PORT/NAME
[1] The django.db.backends.postgresql backend is named django.db.backends.postgresql_psycopg2 in older releases. For backwards compatibility, the old name still works in newer versions. (The new name does not work in older versions).
[2] With PostgreSQL, you can also use unix domain socket paths with percent encoding: postgres://%2Fvar%2Flib%2Fpostgresql/dbname.
[3] (1, 2) SQLite connects to file based databases. The same URL format is used, omitting the hostname, and using the "file" portion as the filename of the database. This has the effect of four slashes being present for an absolute file path: sqlite:////full/path/to/your/database/file.sqlite.
[4] Note that when connecting to Oracle the URL isn't in the form you may know from using other Oracle tools (like SQLPlus) i.e. user and password are separated by : not by /. Also you can omit HOST and PORT and provide a full DSN string or TNS name in NAME part.
Comments
  • 📣  looking for maintainers

    📣 looking for maintainers

    I'd adopted this codebase with every intention of being a good maintainer, but that's clearly not happening. There's a backlog of issues I'm unable to get to, and it's clearly leading to some frustration. So, I'm taking the nudge of Volunteer Responsibility Amnesty Day and looking for new maintainers.

    If you'd like to pick up maintaining this repo, leave a comment here and let me know. I'll check back in a week or so and do the logistics.

    I am mildly wary of supply-chain attacks, so I do have a few requirements to try to protect our users:

    1. If more than one person step up I'd like y'all to coordinate creating an organization to transfer this repo to; if it's just a single person I can transfer it to your personal github or a repo, either way.
    2. Anyone who's going to be a maintainer needs at least a bit of history here on github -- I won't be ok transferring this to a new account.
    3. I'd like you to commit to cutting a new release within a month or so, as a way of notifying users that the ownership has changed. I'll grant you access to PyPI to do the release, but I'll also keep access; I'll had that last bit over once this new release goes out.

    Sorry I haven't been a good steward; I'm sure the next folks will do better!

    opened by jacobian 16
  • Implement Jazzband guidelines for dj-database-url

    Implement Jazzband guidelines for dj-database-url

    This issue tracks the implementation of the Jazzband guidelines for the project dj-database-url

    It was initiated by @jacobian who was automatically assigned in addition to the Jazzband roadies.

    See the TODO list below for the generally required tasks, but feel free to update it in case the project requires it.

    Feel free to ping a Jazzband roadie if you have any question.

    TODOs

    • [x] Fix all links in the docs (and README file etc) from old to new repo
    • [x] Add the Jazzband badge to the README file
    • [x] Add the Jazzband contributing guideline to the CONTRIBUTING.md or CONTRIBUTING.rst file
    • [x] Check if continuous testing works with GitHub Actions
    • [x] Check if test coverage is tracked with Codecov
    • [x] Add jazzband account to PyPI project as maintainer role (e.g. URL: https://pypi.org/manage/project/dj-database-url/collaboration/)
    • [ ] Add jazzband-bot as maintainer to the Read the Docs project (e.g. URL: https://readthedocs.org/dashboard/dj-database-url/users/)
    • [ ] Add incoming GitHub webhook integration to Read the Docs project (e.g. URL: https://readthedocs.org/dashboard/dj-database-url/integrations/)
    • [x] Fix project URL in GitHub project description
    • [x] Review project if other services are used and port them to Jazzband
    • [x] Decide who is project lead for the project (if at all)
    • [x] Set up CI for Jazzband project releases if needed and open ticket if yes

    Project details

    Description Use Database URLs in your Django Application.
    Homepage https://pypi.python.org/pypi/dj-database-url
    Stargazers 1238
    Open issues 34
    Forks 185
    Default branch master
    Is a fork False
    Has Wiki True
    Has Pages False
    opened by jazzband-bot 12
  • Handle special characters in database URL

    Handle special characters in database URL

    If the password contains special characters such as ? or /, the following exception is raised (here I tried to use "foo?bar" as a password):

    Traceback (most recent call last):
      File "./manage.py", line 19, in <module>
        execute_from_command_line(sys.argv)
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/core/management/__init__.py", line 399, in execute_from_command_line
        utility.execute()
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/core/management/__init__.py", line 376, in execute
        sys.stdout.write(self.main_help_text() + '\n')
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/core/management/__init__.py", line 240, in main_help_text
        for name, app in six.iteritems(get_commands()):
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/core/management/__init__.py", line 107, in get_commands
        apps = settings.INSTALLED_APPS
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/conf/__init__.py", line 54, in __getattr__
        self._setup(name)
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/conf/__init__.py", line 49, in _setup
        self._wrapped = Settings(settings_module)
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/conf/__init__.py", line 128, in __init__
        mod = importlib.import_module(self.SETTINGS_MODULE)
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/django/utils/importlib.py", line 40, in import_module
        __import__(name)
      File "/var/www/myproject/dev/myproject/myproject/settings/base.py", line 175, in <module>
        'default': dj_database_url.parse(get_env_variable('DATABASE_URL'))
      File "/var/www/myproject/dev/env/local/lib/python2.7/site-packages/dj_database_url.py", line 84, in parse
        'PORT': url.port or '',
      File "/usr/lib/python2.7/urlparse.py", line 110, in port
        port = int(port, 10)
    ValueError: invalid literal for int() with base 10: 'foo'
    

    I tried to escape the special characters with backslashes but then it got interpreted as "foo". I also tried to url-encode them, ie. replacing "?" by %63 but then the password returned by dj-database-url was "foo%63bar".

    The issue can be easily reproduced with the following URL: postgres://foo:[email protected]/foobar.

    Maybe I'm just missing something but if that's the case I think it would be worth documenting it somewhere.

    opened by sephii 12
  • See about moving this to an official Django project

    See about moving this to an official Django project

    Given the widespread use of dj-database-url, it seems a good idea for it to become Official Project, per DEP 7. Maintenance burden seems minimal but important.

    Read DEP 7 for full details, but roughly there are 4 steps:

    1. Pre-proposal discussion
    2. Form a team
    3. Formal proposal
    4. Django Technical Board Vote

    Let's use this thread to tackle (1) and (2). This means we need to

    work out if there is rough agreement that the project is a good thing for Django to adopt, particularly focusing on any alternative approaches to the same problem and the relative merits of them, including code design, scalability, alignment with existing Django design and philosophy, and having an available development and maintenance team.

    What do folks thing?

    Also: I'll be the shepherd for this proposal, but for it to go forward we'd need a larger maintenance team than just me. If there's anyone -- Django committer or not -- who would be willing to commit to long-term maintenance, please ✋ raise your hand here.

    [Backstory, and why this is living on my personal github right now. @kennethreitz was looking for a new maintainer, and reached out to me to see if Django might be interested. I thought perhaps so, and offered to take over maintainership in the meantime while we work through the DEP 7 process. If it turns out that an Official Project is the wrong home for this, I'll either maintain it long-term or transfer it again.]

    question 
    opened by jacobian 10
  • Django 3.0+ Uses deprecated postgresql_psycopg2 package

    Django 3.0+ Uses deprecated postgresql_psycopg2 package

    I'm getting this error

    Traceback (most recent call last):
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/django/db/backends/base/base.py", line 220, in ensure_connection
        self.connect()
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/django/utils/asyncio.py", line 26, in inner
        return func(*args, **kwargs)
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/django/db/backends/base/base.py", line 197, in connect
        self.connection = self.get_new_connection(conn_params)
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/django/utils/asyncio.py", line 26, in inner
        return func(*args, **kwargs)
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/django/db/backends/postgresql/base.py", line 185, in get_new_connection
        connection = Database.connect(**conn_params)
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/psycopg2/__init__.py", line 125, in connect
        dsn = _ext.make_dsn(dsn, **kwargs)
      File "/Users/jesse.kleve/src/playgrounds/django/dori/api/venv/lib/python3.7/site-packages/psycopg2/extensions.py", line 174, in make_dsn
        parse_dsn(dsn)
    psycopg2.ProgrammingError: invalid dsn: invalid connection option "init_command"
    

    It seems to be using the wrong backend. It's using 'django.db.backends.postgresql_psycopg2' with DATABASE_URL='postgres://root:[email protected]:5432/django'.

    This is with Django version 3.0

    opened by jkleve 8
  • Modernize dj-database-url

    Modernize dj-database-url

    I think this PR addresses a number of outstanding issues, namely:

    • The ability to register custom backends/schemas (and simultaneously only support "blessed" Django backends by default)
    • The ability to pass arbitrary OPTIONS into config and parse
    • Cleaner customization of backend-specific options
    • Modernize the testing matrix
    • Blacken (and isort) the codebase

    As I don't want to impose any more maintenance burden on you, consider this PR also as an offer to maintain this library. My original plan was to simply fork it and release under a new name, but figured it was worth offering. The current test suite is almost entirely unchanged (and passing - https://github.com/imsweb/django-dburl/actions/runs/1373144981) - it only drops pre-2.0 Django support, and registers the previously-supported backends:

    https://github.com/imsweb/django-dburl/blob/modernize/test_dj_database_url.py#L12-L23

    Happy to discuss further. I have a few projects at work that use this, so I'm invested in keeping it up to date, either by maintaining this library directly or maintaining my own fork under a new name.

    opened by dcwatson 7
  • PyPi dj-database-url points to different/old github codebase.

    PyPi dj-database-url points to different/old github codebase.

    I have just realised that the PyPi dj-database-url is pointing to a forked version of this under a different name (https://github.com/kennethreitz/dj-database-url , 0.5.0 from 2018, and no recent activity), but this repo looks like it has more recnt active than that and more up to date with new Django versions.

    Are you aware of this?

    I am interested in using this. Hense, is there a 'stable/production' version of this available via Pip install?

    Will your next release replace the above or be under a different name?

    Kind Regards, Hitesh Patel

    docs 
    opened by hcpatel 6
  • fix #96 deprecated postgres backend strings

    fix #96 deprecated postgres backend strings

    The database backend "django.db.backends.postgresql_psycopg2" has been deprecated in Django 2.0 in favor of "django.db.backends.postgresql".

    https://docs.djangoproject.com/en/2.0/releases/2.0/#id1

    opened by jtdoepke 6
  • URL-decode whole hostname when appropriate

    URL-decode whole hostname when appropriate

    Adds support for other special characters in UNIX socket path names, like the colons in Cloud SQL paths.

    See also: https://github.com/kennethreitz/dj-database-url/issues/66

    opened by jdp 6
  • Added support for percent-encoded Postgres paths.

    Added support for percent-encoded Postgres paths.

    This allows the user to specify unix domain sockets as host.

    Example: postgresql://%2Fvar%2Flib%2Fpostgresql/dbname

    Reference: http://www.postgresql.org/docs/9.2/interactive/libpq-connect.html#AEN38162

    opened by dbrgn 6
  • Exception while using the connection string with postgres

    Exception while using the connection string with postgres

    Hi, I am getting the following exception when using the connection string.

    engine = SCHEMES[url.scheme] if engine is None else engine KeyError: 'postgresql+psycopg2'

    Also my connection string starts with postgresql+psycopg2

    Can you please suggest me how to fix it? Thanks!

    opened by zugspitze 5
  • Support MongoDB with djongo backend

    Support MongoDB with djongo backend

    opened by Nagico 1
  • Throw warning/exception if DATABASE_URL isn't set

    Throw warning/exception if DATABASE_URL isn't set

    Fixes https://github.com/jazzband/dj-database-url/issues/114

    Along the way, to make the test cleaner, it fixes all the explicit "set os.environ" calls with mock.patch work instead.

    opened by palfrey 3
  • Generic backend registration and arbitrary django settings support

    Generic backend registration and arbitrary django settings support

    Add support for custom backend registration with optional config post-processing. Add support for passing arbitrary django database settings as kwargs. Add feature description to README and make README more clear. Extract tests with deprecated options to separate suite to simplify further removal.

    opened by alexanderGerbik 5
  • Should we raise a KeyError if the env var is missing and default is None?

    Should we raise a KeyError if the env var is missing and default is None?

    Shouldn't this function raise a KeyError if s is None?

    def config(env=DEFAULT_ENV, default=None, engine=None, conn_max_age=0, ssl_require=False):
        """Returns configured DATABASE dictionary from DATABASE_URL."""
    
        config = {}
    
        s = os.environ.get(env, default)
    
        if s:
            config = parse(s, engine, conn_max_age, ssl_require)
    
        return config
    

    If the user has not properly configured his environment settings (most likely), and not provided a default fallback value either (also likely), the config will return an empty dictionary, implicitly silencing the issue... (speaking of experience here...) https://devcenter.heroku.com/articles/heroku-postgresql#connecting-in-python

    question 
    opened by dschenck 6
  • heroku+django+mysql: sslmode not supported.

    heroku+django+mysql: sslmode not supported.

    Based on docs: there's no 'sslmode' attribute. The following code gives me the exception: 'sslmode' is an invalid keyword argument. This issue is possibly related to other backends like sqlite as well.

    Workaround: On settings.py after: django_heroku.settings(locals()) add: del DATABASES['default']['OPTIONS']['sslmode']

    feature needs pr easy pickings 
    opened by lwaite 13
Releases(v1.2.0)
  • v1.2.0(Dec 13, 2022)

    What's Changed

    • allow TEST settings to be passed into a db config by @Brodan in https://github.com/jazzband/dj-database-url/pull/116
    • Support urlencoding/decoding for hostname by @Dresdn in https://github.com/jazzband/dj-database-url/pull/181
    • [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/jazzband/dj-database-url/pull/194
    • Fixes #195 - config missin conn_health_check parameter

    New Contributors

    • @Brodan made their first contribution in https://github.com/jazzband/dj-database-url/pull/116
    • @Dresdn made their first contribution in https://github.com/jazzband/dj-database-url/pull/181

    Full Changelog: https://github.com/jazzband/dj-database-url/compare/v1.1.0...v1.2.0

    Source code(tar.gz)
    Source code(zip)
  • v1.1.0(Dec 12, 2022)

    What's Changed

    • Added support for Timescale and Timescale (GIS) by @lino in https://github.com/jazzband/dj-database-url/pull/174
    • [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/jazzband/dj-database-url/pull/175
    • [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/jazzband/dj-database-url/pull/177
    • Fix linter violation by @alexanderGerbik in https://github.com/jazzband/dj-database-url/pull/179
    • [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/jazzband/dj-database-url/pull/182
    • Support Django 4.1 and remove compatibility code by @adamchainz in https://github.com/jazzband/dj-database-url/pull/183
    • [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/jazzband/dj-database-url/pull/188
    • Use urlsplit() instead of urlparse() by @adamchainz in https://github.com/jazzband/dj-database-url/pull/184
    • CHANGELOG: Fix date format by @cfra in https://github.com/jazzband/dj-database-url/pull/192
    • add support to python 3.11 by @jairhenrique in https://github.com/jazzband/dj-database-url/pull/189
    • [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/jazzband/dj-database-url/pull/193
    • Improve by @jairhenrique in https://github.com/jazzband/dj-database-url/pull/190
    • Add ability to set CONN_HEALTH_CHECKS by @adamchainz in https://github.com/jazzband/dj-database-url/pull/185

    New Contributors

    • @lino made their first contribution in https://github.com/jazzband/dj-database-url/pull/174
    • @alexanderGerbik made their first contribution in https://github.com/jazzband/dj-database-url/pull/179
    • @adamchainz made their first contribution in https://github.com/jazzband/dj-database-url/pull/183
    • @cfra made their first contribution in https://github.com/jazzband/dj-database-url/pull/192
    • @jairhenrique made their first contribution in https://github.com/jazzband/dj-database-url/pull/189

    Full Changelog: https://github.com/jazzband/dj-database-url/compare/v1.0.0...v1.1.0

    Source code(tar.gz)
    Source code(zip)
  • v1.0.0(Jul 29, 2022)

    Initial release since the project was migrated to Jazzband.

    We are bumping to version 1.0.0 for a couple of reasons, though none of them are truely breaking API changes.

    • 1.0.0 dignifies a long awaited release of dj-database-url, the first since 2018.
    • We are dropping support of python2.7 🪦
    • Supported python versions >=3.7

    Thank you for helping to push this project forwards.

    Source code(tar.gz)
    Source code(zip)
django-reversion is an extension to the Django web framework that provides version control for model instances.

django-reversion django-reversion is an extension to the Django web framework that provides version control for model instances. Requirements Python 3

Dave Hall 2.8k Jan 02, 2023
A Django app to initialize Sentry client for your Django applications

Dj_sentry This Django application intialize Sentry SDK to your Django application. How to install You can install this packaging by using: pip install

Gandi 1 Dec 09, 2021
The Django Leaflet Admin List package provides an admin list view featured by the map and bounding box filter for the geo-based data of the GeoDjango.

The Django Leaflet Admin List package provides an admin list view featured by the map and bounding box filter for the geo-based data of the GeoDjango. It requires a django-leaflet package.

Vsevolod Novikov 33 Nov 11, 2022
An URL Shortener with Basic Features.

Simple Url Shortener What is that? Yet another url shortener built with Django framework. Preview HOW TO RUN? 1. Virtual Environment First create a vi

Ethem Turgut 6 Jan 25, 2022
Declarative model lifecycle hooks, an alternative to Signals.

Django Lifecycle Hooks This project provides a @hook decorator as well as a base model and mixin to add lifecycle hooks to your Django models. Django'

Robert Singer 1k Dec 31, 2022
Twitter Bootstrap for Django Form

Django bootstrap form Twitter Bootstrap for Django Form. A simple Django template tag to work with Bootstrap Installation Install django-bootstrap-for

tzangms 557 Oct 19, 2022
Ugly single sign-on for django projects only

django-usso Ugly single sign-on for django projects only. Do you have many django apps with different users? Do you want to use only one of those apps

Erwin Feser 1 Mar 01, 2022
Django Advance DumpData

Django Advance Dumpdata Django Manage Command like dumpdata but with have more feature to Output the contents of the database from given fields of a m

EhsanSafir 7 Jul 25, 2022
Django StatusPage - App to display statuspage for your services

Django StatusPage - App to display statuspage for your services

Gorlik 1 Oct 27, 2021
xsendfile etc wrapper

Django Sendfile This is a wrapper around web-server specific methods for sending files to web clients. This is useful when Django needs to check permi

John Montgomery 476 Dec 01, 2022
A reusable Django app that configures your project for deployment

django-simple-deploy This app gives you a management command that configures your project for an initial deployment. It targets Heroku at the moment,

Eric Matthes 205 Dec 26, 2022
Store events and publish to Kafka

Create an event from Django ORM object model, store the event into the database and also publish it into Kafka cluster.

Diag 6 Nov 30, 2022
Django-Docker - Django Installation Guide on Docker

Guía de instalación del Framework Django en Docker Introducción: Con esta guía p

Victor manuel torres 3 Dec 02, 2022
Use webpack to generate your static bundles without django's staticfiles or opaque wrappers.

django-webpack-loader Use webpack to generate your static bundles without django's staticfiles or opaque wrappers. Django webpack loader consumes the

2.4k Dec 24, 2022
A simple E-commerce shop made with Django and Bulma

Interiorshop A Simple E-Commerce app made with Django Instructions Make sure you have python installed Step 1. Open a terminal Step 2. Paste the given

Aditya Priyadarshi 3 Sep 03, 2022
A reusable Django model field for storing ad-hoc JSON data

jsonfield jsonfield is a reusable model field that allows you to store validated JSON, automatically handling serialization to and from the database.

Ryan P Kilby 1.1k Jan 03, 2023
Django-static-site - A simple content site framework that harnesses the power of Django without the hassle

coltrane A simple content site framework that harnesses the power of Django with

Adam Hill 57 Dec 06, 2022
Meta package to combine turbo-django and stimulus-django

Hotwire + Django This repository aims to help you integrate Hotwire with Django 🚀 Inspiration might be taken from @hotwired/hotwire-rails. We are sti

Hotwire for Django 31 Aug 09, 2022
Django Starter is a simple Skeleton to start with a Django project.

Django Starter Template Description Django Starter is a simple Skeleton to start

Numan Ibn Mazid 1 Jan 10, 2022
An insecure login and registration website with Django.

An insecure login and registration website with Django.

Luis Quiñones Requelme 1 Dec 05, 2021