[Django] #21070: Clarify document DATABASES change
Django
-------------------------------+--------------------
Reporter: joejasinski | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+--------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21070>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: joejasinski | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by mjtamlyn):
* needs_better_patch: => 0
* stage: Unreviewed => Accepted
* type: Uncategorized => Cleanup/optimization
* needs_tests: => 0
* needs_docs: => 0
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:1>
Django
Reporter: joejasinski | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (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?
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:2>
Django
Reporter: joejasinski | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:3>
Django
Reporter: joejasinski | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by EvilDMP):
* keywords: => afraid-to-commit
* cc: EvilDMP (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:4>
Django
Reporter: joejasinski | Owner: LouisF
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by LouisF):
* status: new => assigned
* owner: nobody => LouisF
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:5>
Django
Reporter: joejasinski | Owner: LouisF
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by LouisF):
Here is an idea:
https://github.com/tkman/django/compare/development
Please have a look and I Will send a pull request if your happy.
It's based on Joe Jasinski's suggestion in the original ticket
description.
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:6>
Django
Reporter: joejasinski | Owner: LouisF
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"e15f7f31d048ead5453b5ee810235cf88b42b3cc"]:
{{{
#!CommitTicketReference repository=""
revision="e15f7f31d048ead5453b5ee810235cf88b42b3cc"
Fixed #21070 -- Added a more complex database configuration example.
Thanks joejasinski for the suggestion.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:7>
Django
Reporter: joejasinski | Owner: LouisF
Type: Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: afraid-to-commit | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"a6a5c8b06df9334e546795b96566d25c6396209a"]:
{{{
#!CommitTicketReference repository=""
revision="a6a5c8b06df9334e546795b96566d25c6396209a"
[1.6.x] Fixed #21070 -- Added a more complex database configuration
example.
Thanks joejasinski for the suggestion.
Backport of e15f7f31d0 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21070#comment:8>