Opened 22 months ago

Closed 22 months ago

Last modified 22 months ago

#21070 closed Cleanup/optimization (fixed)

Clarify document DATABASES change

Reported by: joejasinski Owned by: LouisF
Component: Documentation Version: master
Severity: Normal Keywords: afraid-to-commit
Cc: EvilDMP Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no


I really like the new format of in master. In particular, I like that sqlite is configured as a default for the DATABASES dictionary. In the new change, a comment links back to the DATABASES variable API documentation.

# Database

    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),

Prior to this change, the 'default' databases dictionary created by startproject also included HOST, PORT, and USER settings keys, with the values defaulted to empty. For most cases, these connection settings provided all the settings needed to connect to most non-sqlite databases. And, for example, if one wished to use the default port and/or localhost, they would simply leave those keys blank.

My worry with this change is that with the removal of these explicit settings from and with the verbose "api-style" documentation, newer users may have difficulty getting started using a non-sqlite database. There are 20+ options for the database setting, and it may be difficult for users unfamiliar with the documentation and for users new to Django to determine which specific settings they need to connect to a database server.

One suggestion is to place an example of the original DATABASES format in the documentation. The original format has served the Django community for years, and provides a nice staring point for identifying the default parameters needed to connect to most external databases; therefore, the original format may be a good candidate to add as an example in the documentation. New developers, looking for the basic settings needed to connect to a database server, would quickly be able to find them in the documentation. People who have been using Django for awhile would also find utility in being be able to quickly find the syntax for the original dictionary, which could help with a transition to the new default.

Here is one thought on how the wording might change in django/docs/ref/settings.txt to accommodate this.

The simplest possible settings file is for a single-database setup using
SQLite. This can be configured using the following::

    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': 'mydatabase'

When connecting to other database backends, such as MySQL, Oracle, or
PostgreSQL, additional connection parameters will be required.  See
the  :setting:`ENGINE <DATABASE-ENGINE>` setting below to specify the database type.::

        'default': {
            'ENGINE': 'django.db.backends.backend_name',
            'NAME': 'mydatabase',
            'USER': 'mydatabaseuser',
            'PASSWORD': '',
            'HOST': '',
             'PORT': '',

For a full list of database "inner" options available for this setting,
refer to the following:

Understandably, the django/docs/ref/settings.txt may not be an appropriate place for a full-form example such as this. At the sprint, it was mentioned that users who copied this new example would still need to modify the setting dictionary, which could lead to some confusion. Given this concern, are there any thoughts on how we might clarify this change (in the documentation or otherwise) to ensure Django continues to be easy to setup for new users? Or is my concern perhaps unwarranted? Thank you for your consideration and I look forward to your feedback.

Change History (8)

comment:1 Changed 22 months ago by mjtamlyn

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

The overall gist of this is good. I think in particular that the example in the docs should read the same as that in the default setting file. As for the other example, I'd prefer to see a concrete example, probably using postgres, with a changed host name etc.

To be honest, that section of documentation is so long with all the options I think there is some merit in separating it out into a separate page. That would allow for a bit more prose about the setting before the api docs. We may also want to restructure into common connection config, test config, oracle specific settings etc.

comment:2 Changed 22 months ago by joejasinski

I'd be glad to take a stab at starting such a new page and submitting for review, if desired. Where would be a good place in the doc codebase to place such a page? In the ideal layout, would the API docs remain mostly as is (with the addition of a link to the new section) or should the new section include the available DATABASES keys as well as some prose and examples?

comment:3 Changed 22 months ago by timo

There are a couple examples of DATABASES in docs/ref/databases.txt -- perhaps this could go there, although I think a basic example in ref/settings.txt would be fine.

comment:4 Changed 22 months ago by EvilDMP

  • Cc EvilDMP added
  • Keywords afraid-to-commit added

comment:5 Changed 22 months ago by LouisF

  • Owner changed from nobody to LouisF
  • Status changed from new to assigned

comment:6 Changed 22 months ago by LouisF

Here is an idea:

Please have a look and I will send a pull request if you're happy.

It's based on Joe Jasinski's suggestion in the original ticket description.

Last edited 22 months ago by LouisF (previous) (diff)

comment:7 Changed 22 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In e15f7f31d048ead5453b5ee810235cf88b42b3cc:

Fixed #21070 -- Added a more complex database configuration example.

Thanks joejasinski for the suggestion.

comment:8 Changed 22 months ago by Tim Graham <timograham@…>

In a6a5c8b06df9334e546795b96566d25c6396209a:

[1.6.x] Fixed #21070 -- Added a more complex database configuration example.

Thanks joejasinski for the suggestion.

Backport of e15f7f31d0 from master

Note: See TracTickets for help on using tickets.
Back to Top