id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
21070	Clarify document DATABASES change	joejasinski	LouisF	"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. 

"	Cleanup/optimization	closed	Documentation	dev	Normal	fixed	afraid-to-commit	Daniele Procida	Accepted	0	0	0	0	1	0