【Django】settings 详解

转自：http://blog.csdn.net/feng88724/article/details/7221973

作者:	Django 团队
译者:	weizhong2004@gmail.com
翻译开始日期:	2006-04-04
翻译完成日期:	2006-04-04
修订日期:	2006-05-06
原文版本:	2789

Django settings 文件包含你的 Django 安装的所有配置信息．本文档解释了 settings 如何工作及共有哪些选项可用．

基本设置

一个 settings 文件就是一个拥有一些模块级变量的 Python 模块．

下面是几个 settings 的例子:

DEBUG = False
DEFAULT_FROM_EMAIL = 'webmaster@example.com'
TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')

由于一个 settings 文件就是一个 Python 模块, 所以必须遵守以下规则:

不允许有 Python 语法错误．
通过使用正常的 Python 语法，可以动态设置 settings ．举例来说:
MY_SETTING = [str(i) for i in range(30)]
可以从其它 settings 文件中导入值.

设置

使用 Django 时, 你必须告诉它你使用的是哪个 settings . 要做到这一点，使用环境变量 DJANGO_SETTINGS_MODULE.

DJANGO_SETTINGS_MODULE 的值是一个 Python 路径, 举例来说 "mysite.settings". 注意 settings 模块应该在 Python import 搜索路径中.

django-admin.py 应用程序

使用 django-admin.py 时, 你可以一次性设定环境变量, 也可以在运行该程序时每次显式的将 settings 模块显式的传递给它.

例子 (Unix Bash shell):

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin.py runserver

例子 (Windows shell):

set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin.py runserver

使用 --settings 命令行参数手工指定 settings

django-admin.py runserver --settings=mysite.settings

服务器环境 (mod_python)

如果是在服务器环境, 必须告诉 Apache/mod_python 你要使用的是哪个 settings 文件. 通过 SetEnv 来做到这一点:

<Location "/mysite/">
    SetHandler python-program
    PythonHandler django.core.handlers.modpython
    SetEnv DJANGO_SETTINGS_MODULE mysite.settings
</Location>

阅读 Django mod_python 文档以得到更多信息.

默认 settings

如果不需要, Django settings 文件可以不必定义任何 settings. 因为每个设置都有默认值. 这些默认值定义在 django/conf/global_settings.py.

下面是 Django 使用 settings 的法则:

从 global_settings.py 载入默认设置.

从指定的 settings 文件载入用户设置, 需要时覆盖掉默认设置.

注意一个用户 settings 文件不必t 导入 global_settings, 这是多余的.

查看你改变了哪些设置

有一个简单的办法可以查看你修改了哪些设置.命令 python manage.py diffsettings 显示当前 settings 文件与 Django 默认设置的不同之处.

参阅 diffsettings documentation.

在你的代码中使用 settings

通过从模块 django.conf.settings 导入你需要的变量, 你的代码可以访问这个变量. 例子:

from django.conf.settings import DEBUG

if DEBUG:
    # Do something

注意一定不要从 global_settings 或你自己的 settings 模块导入设置变量到你的代码. django.conf.settings 概括了默认设置和站点自定义设置的概念,它提供了一个统一的接口用于用户代码访问, 也降低了用户代码与用户设置的耦合程度.

在运行时修改 settings

不应该在程序运行时修改 settings. 举例来说, 不要在一个 view 中做这样的事:

from django.conf.settings import DEBUG

DEBUG = True   # Don't do this!

你只应该在你的 settings 文件中设置 settings, 记住,这是原则.

安全性

由于 settings 文件包含敏感信息,象数据库密码等.你应该非常小心的设置它的访问权限. 举例来说, 你可以只允许你和 WEB 服务器用户阅读该文件.在一个共享主机环境时,这一点格外重要.

可用选项

下面是所有可用选项的列表及它们的默认值(按字母顺序排列).

ABSOLUTE_URL_OVERRIDES

默认值: {} (空字典)

一个字典映射 "app_label.module_name" 字符串到一个函数, 该函数接受一个model对象作为参数并返回它的 URL. 这是在一个安装上覆盖 get_absolute_url() 方法的一种方式. 例子:

ABSOLUTE_URL_OVERRIDES = {
    'blogs.blogs': lambda o: "/blogs/%s/" % o.slug,
    'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

ADMIN_FOR

默认值: () (空的tuple)

用于 admin-site settings 模块, 若当前站点是 admin ,它则是一个由 settings 模块组成的 tuple (类似 'foo.bar.baz' 这样的格式).

admin 站点在 models, views,及 template tags 的自动内省的文档中使用该设置.

ADMIN_MEDIA_PREFIX

默认值: '/media/'

The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use a trailing slash.

ADMINS

默认值: () (空的 tuple)

一个2-元素tuple的 tuple. 列出了有权接收代码错误提示的人. 当 DEBUG=False 时,一个 view 引发了异常, Django 会将详细异常信息用电子邮件的方式发送给这些人. 该tuple的每个成员应该是这种格式: (Full name, e-mail address). 例子:

(('John', 'john@example.com'), ('Mary', 'mary@example.com'))

ALLOWED_INCLUDE_ROOTS

默认值: () (空的 tuple)

一个字符串tuple, 只有以列表中的元素为前缀的模板Django才可以以``{% ssi %}`` 形式访问 . 出于安全考虑, 在不应该访问时,即使是模板的作者也不能访问这些文件.

举例来说, 若 ALLOWED_INCLUDE_ROOTS 是 ('/home/html', '/var/www'), 那么 {% ssi /home/html/foo.txt %} 可以正常工作, 不过 {% ssi /etc/passwd %} 却不能.

APPEND_SLASH

默认值: True

是否给URL添加一个结尾的斜线. 只有安装了 CommonMiddleware 之后,该选项才起作用. (参阅 middleware 文档). 参阅 PREPEND_WWW.

CACHE_BACKEND

默认值: 'simple://'

后端使用的 cache . 参阅 cache docs.

CACHE_MIDDLEWARE_KEY_PREFIX

默认值: '' (空的字符串)

cache 中间件使用的cache key 前缀. 参阅 cache docs.

DATABASE_ENGINE

默认值: 'postgresql'

后端使用的数据库引擎: 'postgresql', 'mysql', 'sqlite3' 或 'ado_mssql' 中的任意一个.

DATABASE_HOST

默认值: '' (空的字符串)

数据库所在的主机. 空的字符串意味着 localhost. SQLite 不需要该项. 如果你使用 MySQL 并且该选项的值以一个斜线 ('/') 开始, MySQL 则通过一个 Unix socket 连接到指定的 socket. 比如:

DATABASE_HOST = '/var/run/mysql'

如果你使用 MySQL 并且该选项的值不是以斜线开始, 那么该选项的值就是主机的名字.

DATABASE_NAME

默认值: '' (空的字符串)

要使用的数据库名字. 对 SQLite, 它必须是一个数据库文件的全路径名字.

DATABASE_PASSWORD

默认值: '' (空的字符串)

连接数据库需要的密码. SQLite 不需要该项.

DATABASE_PORT

默认值: '' (空的字符串)

连接数据库所需的数据库端口. 空的字符串表示默认端口. SQLite 不需要该项.

DATABASE_USER

默认值: '' (空的字符串)

连接数据库时所需要的用户名. SQLite 不需要该项.

DATE_FORMAT

默认值: 'N j, Y' (举例来说 Feb. 4, 2003)

在 Django admin change-list 页对日期字段使用的默认日期格式, 系统中的其它部分也可能使用该格式. 参阅 allowed date format strings.

参阅 DATETIME_FORMAT 和 TIME_FORMAT.

DATETIME_FORMAT

默认值: 'N j, Y, P' (举例来说 Feb. 4, 2003, 4 p.m.)

在 Django admin change-list 页对日期时间字段使用的默认日期时间格式, 系统中的其它部分也可能使用该格式. 参阅 allowed date format strings.

参阅 DATE_FORMAT 和 TIME_FORMAT.

DEBUG

默认值: False

一个开关调试模式的逻辑值

DEFAULT_CHARSET

默认值: 'utf-8'

如果一个 MIME 类型没有人为指定, 对所有 HttpResponse 对象将应用该默认字符集. 使用 DEFAULT_CONTENT_TYPE 来构建 Content-Type 头.

DEFAULT_CONTENT_TYPE

默认值: 'text/html'

如果一个 MIME 类型没有人为指定, 对所有 HttpResponse 对象将应用该默认 content type. 使用 DEFAULT_CHARSET 来构建 Content-Type 头.

DEFAULT_FROM_EMAIL

默认值: 'webmaster@localhost'

用于发送(站点自动生成的)管理邮件的默认 e-mail 邮箱.

DISALLOWED_USER_AGENTS

默认值: () (空的 tuple)

一个编译的正则表达式对象列表,用于表示一些用户代理字符串.这些用户代理将被禁止访问系统中的任何页面. 使用这个对付页面机器人或网络爬虫.只有安装 CommonMiddleware 后这个选项才有用(参阅 middleware 文档).

EMAIL_HOST

默认值: 'localhost'

用来发送 e-mail 的主机. 参阅 EMAIL_PORT.

EMAIL_HOST_PASSWORD

默认值: '' (空的字符串)

EMAIL_HOST 中定义的 SMTP 服务器使用的密码. 如果为空, Django 不会尝试进行认证.

参阅 EMAIL_HOST_USER.

EMAIL_HOST_USER

默认值: '' (空的字符串)

EMAIL_HOST 中定义的 SMTP 服务器使用的用户名. 如果为空, Django 不会尝试进行认证.

参阅 EMAIL_HOST_PASSWORD.

EMAIL_PORT

默认值: 25

EMAIL_HOST 中指定的SMTP 服务器所使用的端口号.

EMAIL_SUBJECT_PREFIX

默认值: '[Django] '

django.core.mail.mail_admins 或 django.core.mail.mail_managers 发送的邮件的主题前缀.

ENABLE_PSYCO

默认值: False

如果允许 Psyco, 将使用Pscyo优化 Python 代码. 需要 Psyco 模块.

IGNORABLE_404_ENDS

默认值: ('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')

参阅 IGNORABLE_404_STARTS.

IGNORABLE_404_STARTS

默认值: ('/cgi-bin/', '/_vti_bin', '/_vti_inf')

一个字符串 tuple . 以该tuple中元素为开头的 URL 应该被 404 e-mailer 忽略. 参阅 SEND_BROKEN_LINK_EMAILS 和 IGNORABLE_404_ENDS.

INSTALLED_APPS

默认值: () (空的 tuple)

一个字符串tuple ,内容是本 Django 安装中的所有应用. 每个字符串应该是一个包含Django应用程序的Python包的路径全称, django-admin.py startapp 会自动往其中添加内容.

INTERNAL_IPS

默认值: () (空的 tuple)

一个 ip 地址的 tuple(字符串形式), 它:

当 DEBUG 为 True 时,参阅调试务注解

接收 X 头(若 XViewMiddleware 已安装), (参阅 middleware 文档)

JING_PATH

默认值: '/usr/bin/jing'

"Jing" 执行文件路径全名. Jing 是一个 RELAX NG 校验器, Django 使用它对你的 model 的 XMLField 进行验证. 参阅 http://www.thaiopensource.com/relaxng/jing.html .

LANGUAGE_CODE

默认值: 'en-us'

表示默认语言的一个字符串. 必须是标准语言格式. 举例来说, U.S. English 就是 "en-us". 参阅 internationalization docs.

LANGUAGES

默认值: 一个 tuple (内容为所有可用语言). 目前它的值是:

LANGUAGES = (
    ('bn', _('Bengali')),
    ('cs', _('Czech')),
    ('cy', _('Welsh')),
    ('da', _('Danish')),
    ('de', _('German')),
    ('en', _('English')),
    ('es', _('Spanish')),
    ('fr', _('French')),
    ('gl', _('Galician')),
    ('is', _('Icelandic')),
    ('it', _('Italian')),
    ('no', _('Norwegian')),
    ('pt-br', _('Brazilian')),
    ('ro', _('Romanian')),
    ('ru', _('Russian')),
    ('sk', _('Slovak')),
    ('sr', _('Serbian')),
    ('sv', _('Swedish')),
    ('zh-cn', _('Simplified Chinese')),
)

一个2-元素tuple<格式为 (语言代码, 语言名称)>的 tuple. 该设置用于选择可用语言.参阅 internationalization docs 了解细节.

通常这个默认值就足够了.除非你打算减少提供的语言数目,否则没必要修改这个设置.

MANAGERS

默认值: ADMINS (不论 ADMINS 是否已经设置)

一个和 ADMINS 同样格式的 tuple , 当 SEND_BROKEN_LINK_EMAILS=True 时, 这些人有权接收死链接通知信息.

MEDIA_ROOT

默认值: '' (空的字符串)

一个绝对路径, 用于保存媒体文件. 例子: "/home/media/media.lawrence.com/" 参阅 MEDIA_URL.

MEDIA_URL

默认值: '' (空的字符串)

处理媒体服务的URL(媒体文件来自 MEDIA_ROOT). 如: "http://media.lawrence.com"

MIDDLEWARE_CLASSES

默认值:

("django.contrib.sessions.middleware.SessionMiddleware",
 "django.contrib.auth.middleware.AuthenticationMiddleware",
 "django.middleware.common.CommonMiddleware",
 "django.middleware.doc.XViewMiddleware")

一个django 用到的中间件 class 名称的 tuple. 参阅 middleware 文档.

PREPEND_WWW

默认值: False

是否为没有 "www." 前缀的域名添加 "www." 前缀. 当且仅当安装有 CommonMiddleware 后该选项才有效. (参阅 middleware 文档).参阅 APPEND_SLASH.

ROOT_URLCONF

默认值: Not defined

一个字符串,表示你的根 URLconf 的模块名. 举例来说:"mydjangoapps.urls". 参阅 Django如何处理一个请求.

SECRET_KEY

默认值: '' (空的字符串)

一个密码. 用于为密码哈希算法提供一个种子.将其设置为一个随机字符串 -- 越长越好. django-admin.py startproject 会自动给你创建一个.

SEND_BROKEN_LINK_EMAILS

默认值: False

当有人从一个有效Django-powered页面访问另一个Django-powered页面时发现404错误(也就是发现一个死链接)时, 是否发送一封邮件给 MANAGERS. 当且仅当安装有 CommonMiddleware 时该选项才有效(参阅`middleware 文档`_). 参阅 IGNORABLE_404_STARTS `` 和 IGNORABLE_404_ENDS``.

SERVER_EMAIL

默认值: 'root@localhost'

用来发送错误信息的邮件地址, 比如发送给 ADMINS 和 MANAGERS 的邮件.

SESSION_COOKIE_AGE

默认值: 1209600 (2周, 以秒计)

session cookies 的生命周期, 以秒计. 参阅 session docs.

SESSION_COOKIE_DOMAIN

默认值: None

session cookies 有效的域. 将其值设置为类似 ".lawrence.com" 这样 cookie 就可以跨域生效, 或者使用 None 作为一个标准的域 cookie. 参阅 session docs.

SESSION_COOKIE_NAME

默认值: 'sessionid'

session 使用的cookie 名字. 参阅 session docs.

SESSION_SAVE_EVERY_REQUEST

默认值: False

是否每次请求都保存session. 参阅 session docs.

SITE_ID

默认值: Not defined

是一个整数, 表示 django_site 表中的当前站点. 当一个数据包含多个站点数据时，你的程序可以据此 ID 访问特定站点的数据．

TEMPLATE_CONTEXT_PROCESSORS

默认值:

("django.core.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n")

A tuple of callables that are used to populate the context in RequestContext. These callables take a request object as their argument and return a dictionary of items to be merged into the context.

TEMPLATE_DEBUG

默认值: False

一个布尔值,用来开关模板调试模式.若设置为 True, 如果有任何 TemplateSyntaxError,一个详细的错误报告信息页将被显示给你.这个报告包括有关的模板片断,相应的行会自动高亮.

注意 Django 仅在 DEBUG 为 True 时显示这个信息页面.

参阅 DEBUG.

TEMPLATE_DIRS

默认值: () (空的 tuple)

模板源文件目录列表,按搜索顺序. 注意要使用 Unix-风格的前置斜线(即'/'), 即便是在 Windows 上.

参阅 template documentation.

TEMPLATE_LOADERS

默认值: ('django.template.loaders.filesystem.load_template_source',)

一个元素为可调用对象(字符串形式的)的 tuple. 这些对象知道如何导入 templates 从各种源中. 参阅 template documentation.

TEMPLATE_STRING_IF_INVALID

默认值: '' (空的字符串)

输出文本, 作为一个字符串. 模板系统将会在出错 (比如说拼错了) 时使用该变量. 参阅 How invalid variables are handled.

TIME_FORMAT

默认值: 'P' (举例来说 4 p.m.)

Django admin change-list 使用的默认时间格式. 有可能系统的其它部分也使用该格式. 参阅 allowed date format strings.

参阅 DATE_FORMAT 和 DATETIME_FORMAT.

TIME_ZONE

默认值: 'America/Chicago' (我们可以用 'Asia/Shanghai PRC' )

一个表示当前时区的字符串. 参阅选择项列表.

Django 据此设置转换所有的日期/时间 -- 并不考虑服务器的时区设置. 举例来说, 一台服务器可以服务多个 Django-powered 站点,每个站点使用一个独立的时区设置.

USE_ETAGS

默认值: False

一个布尔值.指定是否输出 "Etag" 头. 这个选项可以节省网络带宽,但损失性能. 只有安装 CommonMiddleware 后这个选项才有用(参阅 middleware 文档)

创建你自己的 settings

你可以为自己的Django 应用程序创建自定义 settings. 只需要你遵守以下惯例:

设置名称全部大写.

如果某项设置是一个序列,优先使用 tuple.这完全是基于性能考虑.

不要为已经存的一个设置重新发明一个名字.

官方文档：https://docs.djangoproject.com/en/dev/ref/settings/

Settings

Warning

Be careful when you override settings, especially when the default value is a non-empty tuple or dictionary, such as MIDDLEWARE_CLASSES and TEMPLATE_CONTEXT_PROCESSORS. Make sure you keep the components required by the features of Django you wish to use.

Core settings

Here’s a list of settings available in Django core and their default values. Settings provided by contrib apps are listed below, followed by a topical index of the core settings.

ABSOLUTE_URL_OVERRIDES

Default: {} (Empty dictionary)

A dictionary mapping "app_label.model_name" strings to functions that take a model object and return its URL. This is a way of overriding get_absolute_url() methods on a per-installation basis. Example:

ABSOLUTE_URL_OVERRIDES = {
    'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
    'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

Note that the model name used in this setting should be all lower-case, regardless of the case of the actual model class name.

ADMINS

Default: () (Empty tuple)

A tuple that lists people who get code error notifications. When DEBUG=False and a view raises an exception, Django will email these people with the full exception information. Each member of the tuple should be a tuple of (Full name, email address). Example:

(('John', 'john@example.com'), ('Mary', 'mary@example.com'))

Note that Django will email all of these people whenever an error happens. See Error reporting for more information.

ALLOWED_HOSTS

Default: [] (Empty list)

A list of strings representing the host/domain names that this Django site can serve. This is a security measure to prevent an attacker from poisoning caches and password reset emails with links to malicious hosts by submitting requests with a fake HTTP Host header, which is possible even under many seemingly-safe web server configurations.

Values in this list can be fully qualified names (e.g. 'www.example.com'), in which case they will be matched against the request’sHost header exactly (case-insensitive, not including port). A value beginning with a period can be used as a subdomain wildcard: '.example.com' will match example.com, www.example.com, and any other subdomain of example.com. A value of '*' will match anything; in this case you are responsible to provide your own validation of the Host header (perhaps in a middleware; if so this middleware must be listed first in MIDDLEWARE_CLASSES).

Note

If you want to also allow the fully qualified domain name (FQDN), which some browsers can send in the Host header, you must explicitly add another ALLOWED_HOSTS entry that includes a trailing period. This entry can also be a subdomain wildcard:

ALLOWED_HOSTS = [
    '.example.com', # Allow domain and subdomains
    '.example.com.', # Also allow FQDN and subdomains
]

If the Host header (or X-Forwarded-Host if USE_X_FORWARDED_HOST is enabled) does not match any value in this list, thedjango.http.HttpRequest.get_host() method will raise SuspiciousOperation.

When DEBUG is True or when running tests, host validation is disabled; any host will be accepted. Thus it’s usually only necessary to set it in production.

This validation only applies via get_host(); if your code accesses the Host header directly from request.META you are bypassing this security protection.

ALLOWED_INCLUDE_ROOTS

Default: () (Empty tuple)

A tuple of strings representing allowed prefixes for the {% ssi %} template tag. This is a security measure, so that template authors can’t access files that they shouldn’t be accessing.

For example, if ALLOWED_INCLUDE_ROOTS is ('/home/html', '/var/www'), then {% ssi /home/html/foo.txt %} would work, but{% ssi /etc/passwd %} wouldn’t.

APPEND_SLASH

Default: True

When set to True, if the request URL does not match any of the patterns in the URLconf and it doesn’t end in a slash, an HTTP redirect is issued to the same URL with a slash appended. Note that the redirect may cause any data submitted in a POST request to be lost.

The APPEND_SLASH setting is only used if CommonMiddleware is installed (see Middleware). See also PREPEND_WWW.

CACHES

Default:

{
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
    }
}

A dictionary containing the settings for all caches to be used with Django. It is a nested dictionary whose contents maps cache aliases to a dictionary containing the options for an individual cache.

The CACHES setting must configure a default cache; any number of additional caches may also be specified. If you are using a cache backend other than the local memory cache, or you need to define multiple caches, other options will be required. The following cache options are available.

BACKEND

Default: '' (Empty string)

The cache backend to use. The built-in cache backends are:

'django.core.cache.backends.db.DatabaseCache'
'django.core.cache.backends.dummy.DummyCache'
'django.core.cache.backends.filebased.FileBasedCache'
'django.core.cache.backends.locmem.LocMemCache'
'django.core.cache.backends.memcached.MemcachedCache'
'django.core.cache.backends.memcached.PyLibMCCache'

You can use a cache backend that doesn’t ship with Django by setting BACKEND to a fully-qualified path of a cache backend class (i.e. mypackage.backends.whatever.WhateverCache). Writing a whole new cache backend from scratch is left as an exercise to the reader; see the other backends for examples.

KEY_FUNCTION

A string containing a dotted path to a function that defines how to compose a prefix, version and key into a final cache key. The default implementation is equivalent to the function:

def make_key(key, key_prefix, version):
    return ':'.join([key_prefix, str(version), key])

You may use any key function you want, as long as it has the same argument signature.

See the cache documentation for more information.

KEY_PREFIX

Default: '' (Empty string)

A string that will be automatically included (prepended by default) to all cache keys used by the Django server.

See the cache documentation for more information.

LOCATION

Default: '' (Empty string)

The location of the cache to use. This might be the directory for a file system cache, a host and port for a memcache server, or simply an identifying name for a local memory cache. e.g.:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/django_cache',
    }
}

OPTIONS

Default: None

Extra parameters to pass to the cache backend. Available parameters vary depending on your cache backend.

Some information on available parameters can be found in the Cache Backends documentation. For more information, consult your backend module’s own documentation.

TIMEOUT

Default: 300

The number of seconds before a cache entry is considered stale.

VERSION

Default: 1

The default version number for cache keys generated by the Django server.

See the cache documentation for more information.

CACHE_MIDDLEWARE_ALIAS

Default: default

The cache connection to use for the cache middleware.

CACHE_MIDDLEWARE_ANONYMOUS_ONLY

Default: False

Deprecated in Django 1.6:

Deprecated since version 1.6: This setting was largely ineffective because of using cookies for sessions and CSRF. See theDjango 1.6 release notes for more information.

If the value of this setting is True, only anonymous requests (i.e., not those made by a logged-in user) will be cached. Otherwise, the middleware caches every page that doesn’t have GET or POST parameters.

If you set the value of this setting to True, you should make sure you’ve activated AuthenticationMiddleware.

CACHE_MIDDLEWARE_KEY_PREFIX

Default: '' (Empty string)

The cache key prefix that the cache middleware should use.

See Django’s cache framework.

CACHE_MIDDLEWARE_SECONDS

Default: 600

The default number of seconds to cache a page when the caching middleware or cache_page() decorator is used.

See Django’s cache framework.

CSRF_FAILURE_VIEW

Default: 'django.views.csrf.csrf_failure'

A dotted path to the view function to be used when an incoming request is rejected by the CSRF protection. The function should have this signature:

def csrf_failure(request, reason="")

where reason is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. See Cross Site Request Forgery protection.

DATABASES

Default: {} (Empty dictionary)

A dictionary containing the settings for all databases to be used with Django. It is a nested dictionary whose contents maps database aliases to a dictionary containing the options for an individual database.

The DATABASES setting must configure a default database; any number of additional databases may also be specified.

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'
    }
}

For other database backends, or more complex SQLite configurations, other options will be required. The following inner options are available.

ATOMIC_REQUESTS

New in Django Development version.

Default: False

Set this to True to wrap each HTTP request in a transaction on this database. See Tying transactions to HTTP requests.

AUTOCOMMIT

New in Django Development version.

Default: True

Set this to False if you want to disable Django’s transaction management and implement your own.

ENGINE

Default: '' (Empty string)

The database backend to use. The built-in database backends are:

'django.db.backends.postgresql_psycopg2'
'django.db.backends.mysql'
'django.db.backends.sqlite3'
'django.db.backends.oracle'

You can use a database backend that doesn’t ship with Django by setting ENGINE to a fully-qualified path (i.e.mypackage.backends.whatever). Writing a whole new database backend from scratch is left as an exercise to the reader; see the other backends for examples.

HOST

Default: '' (Empty string)

Which host to use when connecting to the database. An empty string means localhost. Not used with SQLite.

If this value starts with a forward slash ('/') and you’re using MySQL, MySQL will connect via a Unix socket to the specified socket. For example:

"HOST": '/var/run/mysql'

If you’re using MySQL and this value doesn’t start with a forward slash, then this value is assumed to be the host.

If you’re using PostgreSQL, by default (empty HOST), the connection to the database is done through UNIX domain sockets (‘local’ lines in pg_hba.conf). If you want to connect through TCP sockets, set HOST to ‘localhost’ or ‘127.0.0.1’ (‘host’ lines inpg_hba.conf). On Windows, you should always define HOST, as UNIX domain sockets are not available.

NAME

Default: '' (Empty string)

The name of the database to use. For SQLite, it’s the full path to the database file. When specifying the path, always use forward slashes, even on Windows (e.g. C:/homes/user/mysite/sqlite3.db).

CONN_MAX_AGE

New in Django Development version.

Default: 0

The lifetime of a database connection, in seconds. Use 0 to close database connections at the end of each request — Django’s historical behavior — and None for unlimited persistent connections.

OPTIONS

Default: {} (Empty dictionary)

Extra parameters to use when connecting to the database. Available parameters vary depending on your database backend.

Some information on available parameters can be found in the Database Backends documentation. For more information, consult your backend module’s own documentation.

PASSWORD

Default: '' (Empty string)

The password to use when connecting to the database. Not used with SQLite.

PORT

Default: '' (Empty string)

The port to use when connecting to the database. An empty string means the default port. Not used with SQLite.

USER

Default: '' (Empty string)

The username to use when connecting to the database. Not used with SQLite.

TEST_CHARSET

Default: None

The character set encoding used to create the test database. The value of this string is passed directly through to the database, so its format is backend-specific.

Supported for the PostgreSQL (postgresql_psycopg2) and MySQL (mysql) backends.

TEST_COLLATION

Default: None

The collation order to use when creating the test database. This value is passed directly to the backend, so its format is backend-specific.

Only supported for the mysql backend (see the MySQL manual for details).

TEST_DEPENDENCIES

Default: ['default'], for all databases other than default, which has no dependencies.

The creation-order dependencies of the database. See the documentation on controlling the creation order of test databasesfor details.

TEST_MIRROR

Default: None

The alias of the database that this database should mirror during testing.

This setting exists to allow for testing of master/slave configurations of multiple databases. See the documentation ontesting master/slave configurations for details.

TEST_NAME

Default: None

The name of database to use when running the test suite.

If the default value (None) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name 'test_' + DATABASE_NAME.

See The test database.