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>