Configuration#
Datasette offers several ways to configure your Datasette instances: server settings, plugin configuration, authentication, and more.
Most configuration can be handled using a datasette.yaml configuration file, passed to datasette using the -c/--config flag:
datasette mydatabase.db --config datasette.yaml
This file can also use JSON, as datasette.json. YAML is recommended over JSON due to its support for comments and multi-line strings.
Configuration via the command-line#
The recommended way to configure Datasette is using a datasette.yaml file passed to -c/--config. You can also pass individual settings to Datasette using the -s/--setting option, which can be used multiple times:
datasette mydatabase.db \
--setting settings.default_page_size 50 \
--setting settings.sql_time_limit_ms 3500
This option takes dotted-notation for the first argument and a value for the second argument. This means you can use it to set any configuration value that would be valid in a datasette.yaml file.
It also works for plugin configuration, for example for datasette-cluster-map:
datasette mydatabase.db \
--setting plugins.datasette-cluster-map.latitude_column xlat \
--setting plugins.datasette-cluster-map.longitude_column xlon
If the value you provide is a valid JSON object or list it will be treated as nested data, allowing you to configure plugins that accept lists such as datasette-proxy-url:
datasette mydatabase.db \
-s plugins.datasette-proxy-url.paths '[{"path": "/proxy", "backend": "http://example.com/"}]'
This is equivalent to a datasette.yaml file containing the following:
plugins:
datasette-proxy-url:
paths:
- path: /proxy
backend: http://example.com/
{
"plugins": {
"datasette-proxy-url": {
"paths": [
{
"path": "/proxy",
"backend": "http://example.com/"
}
]
}
}
}
datasette.yaml reference#
The following example shows some of the valid configuration options that can exist inside datasette.yaml.
# Datasette settings block
settings:
default_page_size: 50
sql_time_limit_ms: 3500
max_returned_rows: 2000
# top-level plugin configuration
plugins:
datasette-my-plugin:
key: valueA
# Database and table-level configuration
databases:
your_db_name:
# plugin configuration for the your_db_name database
plugins:
datasette-my-plugin:
key: valueA
tables:
your_table_name:
allow:
# Only the root user can access this table
id: root
# plugin configuration for the your_table_name table
# inside your_db_name database
plugins:
datasette-my-plugin:
key: valueB
{
"settings": {
"default_page_size": 50,
"sql_time_limit_ms": 3500,
"max_returned_rows": 2000
},
"plugins": {
"datasette-my-plugin": {
"key": "valueA"
}
},
"databases": {
"your_db_name": {
"plugins": {
"datasette-my-plugin": {
"key": "valueA"
}
},
"tables": {
"your_table_name": {
"allow": {
"id": "root"
},
"plugins": {
"datasette-my-plugin": {
"key": "valueB"
}
}
}
}
}
}
}
Settings#
Settings can be configured in datasette.yaml with the settings key:
# inside datasette.yaml
settings:
default_allow_sql: off
default_page_size: 50
{
"settings": {
"default_allow_sql": "off",
"default_page_size": 50
}
}
The full list of settings is available in the settings documentation. Settings can also be passed to Datasette using one or more --setting name value command line options.`
Plugin configuration#
Datasette plugins often require configuration. This plugin configuration should be placed in plugins keys inside datasette.yaml.
Most plugins are configured at the top-level of the file, using the plugins key:
# inside datasette.yaml
plugins:
datasette-my-plugin:
key: my_value
{
"plugins": {
"datasette-my-plugin": {
"key": "my_value"
}
}
}
Some plugins can be configured at the database or table level. These should use a plugins key nested under the appropriate place within the databases object:
# inside datasette.yaml
databases:
my_database:
# plugin configuration for the my_database database
plugins:
datasette-my-plugin:
key: my_value
my_other_database:
tables:
my_table:
# plugin configuration for the my_table table inside the my_other_database database
plugins:
datasette-my-plugin:
key: my_value
{
"databases": {
"my_database": {
"plugins": {
"datasette-my-plugin": {
"key": "my_value"
}
}
},
"my_other_database": {
"tables": {
"my_table": {
"plugins": {
"datasette-my-plugin": {
"key": "my_value"
}
}
}
}
}
}
}
Permissions configuration#
Datasette's authentication and permissions system can also be configured using datasette.yaml.
Here is a simple example:
# Instance is only available to users 'sharon' and 'percy':
allow:
id:
- sharon
- percy
# Only 'percy' is allowed access to the accounting database:
databases:
accounting:
allow:
id: percy
{
"allow": {
"id": [
"sharon",
"percy"
]
},
"databases": {
"accounting": {
"allow": {
"id": "percy"
}
}
}
}
Access permissions in datasette.yaml has the full details.
Canned queries configuration#
Canned queries are named SQL queries that appear in the Datasette interface. They can be configured in datasette.yaml using the queries key at the database level:
databases:
sf-trees:
queries:
just_species:
sql: select qSpecies from Street_Tree_List
{
"databases": {
"sf-trees": {
"queries": {
"just_species": {
"sql": "select qSpecies from Street_Tree_List"
}
}
}
}
}
See the canned queries documentation for more, including how to configure writable canned queries.
Custom CSS and JavaScript#
Datasette can load additional CSS and JavaScript files, configured in datasette.yaml like this:
extra_css_urls:
- https://simonwillison.net/static/css/all.bf8cd891642c.css
extra_js_urls:
- https://code.jquery.com/jquery-3.2.1.slim.min.js
{
"extra_css_urls": [
"https://simonwillison.net/static/css/all.bf8cd891642c.css"
],
"extra_js_urls": [
"https://code.jquery.com/jquery-3.2.1.slim.min.js"
]
}
The extra CSS and JavaScript files will be linked in the <head> of every page:
<link rel="stylesheet" href="https://simonwillison.net/static/css/all.bf8cd891642c.css">
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
You can also specify a SRI (subresource integrity hash) for these assets:
extra_css_urls:
- url: https://simonwillison.net/static/css/all.bf8cd891642c.css
sri: sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI
extra_js_urls:
- url: https://code.jquery.com/jquery-3.2.1.slim.min.js
sri: sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g=
{
"extra_css_urls": [
{
"url": "https://simonwillison.net/static/css/all.bf8cd891642c.css",
"sri": "sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI"
}
],
"extra_js_urls": [
{
"url": "https://code.jquery.com/jquery-3.2.1.slim.min.js",
"sri": "sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g="
}
]
}
This will produce:
<link rel="stylesheet" href="https://simonwillison.net/static/css/all.bf8cd891642c.css"
integrity="sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI"
crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"
integrity="sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g="
crossorigin="anonymous"></script>
Modern browsers will only execute the stylesheet or JavaScript if the SRI hash matches the content served. You can generate hashes using www.srihash.org
Items in "extra_js_urls" can specify "module": true if they reference JavaScript that uses JavaScript modules. This configuration:
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
{
"extra_js_urls": [
{
"url": "https://example.datasette.io/module.js",
"module": true
}
]
}
Will produce this HTML:
<script type="module" src="https://example.datasette.io/module.js"></script>