Clarify document DATABASES change

[joejasinski]

I really like the new format of settings.py 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 settings.py API documentation.

# Database
# https://docs.djangoproject.com/en/dev/ref/settings/#databases

DATABASES = {
    '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 settings.py 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::

DATABASES = {
    '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.::

    DATABASES = {
        '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.

[Marc Tamlyn]

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.

[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?

[Tim Graham]

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.

[LouisF]

Here is an idea:

​https://github.com/tkman/django/compare/development

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.

[Tim Graham <timograham@…>]

In e15f7f31d048ead5453b5ee810235cf88b42b3cc:

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

Thanks joejasinski for the suggestion.

[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