2023-08-23 01:26:11 +00:00
.. _configuration:
Configuration
2023-09-13 21:06:25 +00:00
=============
2023-08-23 01:26:11 +00:00
2023-09-13 21:06:25 +00:00
Datasette offers several ways to configure your Datasette instances: server settings, plugin configuration, authentication, and more.
2023-08-23 01:26:11 +00:00
2024-02-05 21:43:50 +00:00
Most configuration can be handled using a `` datasette.yaml `` configuration file, passed to datasette using the `` -c/--config `` flag:
2023-09-13 21:06:25 +00:00
.. code-block :: bash
2023-08-23 01:26:11 +00:00
datasette mydatabase.db --config datasette.yaml
2023-09-13 21:06:25 +00:00
2024-02-01 04:03:19 +00:00
This file can also use JSON, as `` datasette.json `` . YAML is recommended over JSON due to its support for comments and multi-line strings.
2024-02-05 21:43:50 +00:00
.. _configuration_cli:
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:
.. code-block :: bash
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 <https://datasette.io/plugins/datasette-cluster-map> `_ :
.. code-block :: bash
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 <https://datasette.io/plugins/datasette-proxy-url> `_ :
.. code-block :: bash
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:
.. [[[cog
from metadata_doc import config_example
import textwrap
config_example(cog, textwrap.dedent(
"""
plugins:
datasette-proxy-url:
paths:
- path: /proxy
backend: http://example.com/
""").strip()
)
.. ]]]
.. tab :: datasette.yaml
.. code-block :: yaml
plugins:
datasette-proxy-url:
paths:
- path: /proxy
backend: http://example.com/
.. tab :: datasette.json
.. code-block :: json
{
"plugins": {
"datasette-proxy-url": {
"paths": [
{
"path": "/proxy",
"backend": "http://example.com/"
}
]
}
}
}
.. [[[end]]]
2023-09-13 21:06:25 +00:00
.. _configuration_reference:
2024-02-01 04:03:19 +00:00
`` datasette.yaml `` reference
2023-09-13 21:06:25 +00:00
----------------------------
2024-02-05 21:43:50 +00:00
The following example shows some of the valid configuration options that can exist inside `` datasette.yaml `` .
2023-09-13 21:06:25 +00:00
2023-09-13 21:15:32 +00:00
.. [[[cog
2023-10-12 16:16:37 +00:00
from metadata_doc import config_example
2023-09-13 21:15:32 +00:00
import textwrap
2023-10-12 16:16:37 +00:00
config_example(cog, textwrap.dedent(
2023-09-13 21:15:32 +00:00
"""
# 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:
2024-02-01 04:03:19 +00:00
allow:
# Only the root user can access this table
id: root
2023-09-13 21:15:32 +00:00
# plugin configuration for the your_table_name table
# inside your_db_name database
plugins:
datasette-my-plugin:
key: valueB
""")
)
.. ]]]
2023-10-12 16:16:37 +00:00
.. tab :: datasette.yaml
2023-09-13 21:06:25 +00:00
.. code-block :: yaml
2023-10-12 16:16:37 +00:00
2023-09-13 21:06:25 +00:00
# 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:
2024-02-01 04:03:19 +00:00
allow:
# Only the root user can access this table
id: root
2023-09-13 21:06:25 +00:00
# plugin configuration for the your_table_name table
# inside your_db_name database
plugins:
datasette-my-plugin:
key: valueB
2023-10-12 16:16:37 +00:00
.. tab :: datasette.json
2023-09-13 21:15:32 +00:00
.. code-block :: json
{
"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": {
2024-02-01 04:03:19 +00:00
"allow": {
"id": "root"
},
2023-09-13 21:15:32 +00:00
"plugins": {
"datasette-my-plugin": {
"key": "valueB"
}
}
}
}
}
}
}
.. [[[end]]]
2023-09-13 21:06:25 +00:00
.. _configuration_reference_settings:
2024-02-01 04:03:19 +00:00
Settings
~~~~~~~~
:ref: `settings` can be configured in `` datasette.yaml `` with the `` settings `` key:
2023-09-13 21:06:25 +00:00
2023-09-13 21:15:32 +00:00
.. [[[cog
2023-10-12 16:16:37 +00:00
from metadata_doc import config_example
2023-09-13 21:15:32 +00:00
import textwrap
2023-10-12 16:16:37 +00:00
config_example(cog, textwrap.dedent(
2023-09-13 21:15:32 +00:00
"""
# inside datasette.yaml
settings:
2024-02-05 18:34:10 +00:00
default_allow_sql: off
default_page_size: 50
2023-09-13 21:15:32 +00:00
""").strip()
)
.. ]]]
2023-10-12 16:16:37 +00:00
.. tab :: datasette.yaml
2023-09-13 21:06:25 +00:00
.. code-block :: yaml
# inside datasette.yaml
settings:
2024-02-05 18:34:10 +00:00
default_allow_sql: off
default_page_size: 50
2023-09-13 21:06:25 +00:00
2023-10-12 16:16:37 +00:00
.. tab :: datasette.json
2023-09-13 21:15:32 +00:00
.. code-block :: json
{
"settings": {
"default_allow_sql": "off",
"default_page_size": 50
}
}
.. [[[end]]]
2023-09-13 21:06:25 +00:00
2024-02-01 04:03:19 +00:00
The full list of settings is available in the :ref: `settings documentation <settings>` . Settings can also be passed to Datasette using one or more `` --setting name value `` command line options.`
2023-09-13 21:06:25 +00:00
.. _configuration_reference_plugins:
2024-02-01 04:03:19 +00:00
2023-09-13 21:06:25 +00:00
Plugin configuration
~~~~~~~~~~~~~~~~~~~~
2024-02-01 04:03:19 +00:00
:ref: `Datasette plugins <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:
2023-09-13 21:06:25 +00:00
2023-09-13 21:15:32 +00:00
.. [[[cog
2023-10-12 16:16:37 +00:00
from metadata_doc import config_example
2023-09-13 21:15:32 +00:00
import textwrap
2023-10-12 16:16:37 +00:00
config_example(cog, textwrap.dedent(
2023-09-13 21:15:32 +00:00
"""
# inside datasette.yaml
plugins:
datasette-my-plugin:
key: my_value
""").strip()
)
.. ]]]
2023-10-12 16:16:37 +00:00
.. tab :: datasette.yaml
2023-09-13 21:06:25 +00:00
.. code-block :: yaml
# inside datasette.yaml
plugins:
datasette-my-plugin:
key: my_value
2023-10-12 16:16:37 +00:00
.. tab :: datasette.json
2023-09-13 21:15:32 +00:00
.. code-block :: json
{
"plugins": {
"datasette-my-plugin": {
"key": "my_value"
}
}
}
.. [[[end]]]
2024-02-01 04:03:19 +00:00
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:
2023-09-13 21:06:25 +00:00
2023-09-13 21:15:32 +00:00
.. [[[cog
2023-10-12 16:16:37 +00:00
from metadata_doc import config_example
2023-09-13 21:15:32 +00:00
import textwrap
2023-10-12 16:16:37 +00:00
config_example(cog, textwrap.dedent(
2023-09-13 21:15:32 +00:00
"""
# 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
""").strip()
)
.. ]]]
2023-10-12 16:16:37 +00:00
.. tab :: datasette.yaml
2023-09-13 21:06:25 +00:00
.. code-block :: yaml
# 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
2023-09-13 21:15:32 +00:00
2023-10-12 16:16:37 +00:00
.. tab :: datasette.json
2023-09-13 21:15:32 +00:00
.. code-block :: json
{
"databases": {
"my_database": {
"plugins": {
"datasette-my-plugin": {
"key": "my_value"
}
}
},
"my_other_database": {
"tables": {
"my_table": {
"plugins": {
"datasette-my-plugin": {
"key": "my_value"
}
}
}
}
}
}
}
2023-10-12 16:16:37 +00:00
.. [[[end]]]
.. _configuration_reference_permissions:
2024-02-01 04:03:19 +00:00
2023-10-12 22:05:02 +00:00
Permissions configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
2023-10-12 16:16:37 +00:00
2024-02-01 04:03:19 +00:00
Datasette's :ref: `authentication and permissions <authentication>` system can also be configured using `` datasette.yaml `` .
Here is a simple example:
.. [[[cog
from metadata_doc import config_example
import textwrap
config_example(cog, textwrap.dedent(
"""
# 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
""").strip()
)
.. ]]]
.. tab :: datasette.yaml
.. code-block :: yaml
# 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
.. tab :: datasette.json
.. code-block :: json
{
"allow": {
"id": [
"sharon",
"percy"
]
},
"databases": {
"accounting": {
"allow": {
"id": "percy"
}
}
}
}
.. [[[end]]]
:ref: `authentication_permissions_config` has the full details.
2023-10-12 16:16:37 +00:00
.. _configuration_reference_canned_queries:
2024-02-01 04:03:19 +00:00
2023-10-12 22:05:02 +00:00
Canned queries configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2023-10-12 16:16:37 +00:00
2024-02-01 04:03:19 +00:00
:ref: `Canned queries <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:
.. [[[cog
from metadata_doc import config_example, config_example
config_example(cog, {
"databases": {
"sf-trees": {
"queries": {
"just_species": {
"sql": "select qSpecies from Street_Tree_List"
}
}
}
}
})
.. ]]]
.. tab :: datasette.yaml
.. code-block :: yaml
databases:
sf-trees:
queries:
just_species:
sql: select qSpecies from Street_Tree_List
.. tab :: datasette.json
.. code-block :: json
{
"databases": {
"sf-trees": {
"queries": {
"just_species": {
"sql": "select qSpecies from Street_Tree_List"
}
}
}
}
}
.. [[[end]]]
See the :ref: `canned queries documentation <canned_queries>` for more, including how to configure :ref: `writable canned queries <canned_queries_writable>` .
2023-10-12 16:16:37 +00:00
.. _configuration_reference_css_js:
2024-02-01 04:03:19 +00:00
Custom CSS and JavaScript
~~~~~~~~~~~~~~~~~~~~~~~~~
Datasette can load additional CSS and JavaScript files, configured in `` datasette.yaml `` like this:
.. [[[cog
from metadata_doc import config_example
config_example(cog, """
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
""")
.. ]]]
.. tab :: datasette.yaml
.. code-block :: yaml
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
.. tab :: datasette.json
.. code-block :: json
{
"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"
]
}
.. [[[end]]]
The extra CSS and JavaScript files will be linked in the `` <head> `` of every page:
.. code-block :: html
<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:
.. [[[cog
config_example(cog, """
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=
""")
.. ]]]
.. tab :: datasette.yaml
.. code-block :: yaml
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=
.. tab :: datasette.json
.. code-block :: json
{
"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="
}
]
}
.. [[[end]]]
This will produce:
.. code-block :: html
<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 <https://www.srihash.org/> `_
Items in `` "extra_js_urls" `` can specify `` "module": true `` if they reference JavaScript that uses `JavaScript modules <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules> `__ . This configuration:
.. [[[cog
config_example(cog, """
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
""")
.. ]]]
.. tab :: datasette.yaml
.. code-block :: yaml
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
.. tab :: datasette.json
.. code-block :: json
{
"extra_js_urls": [
{
"url": "https://example.datasette.io/module.js",
"module": true
}
]
}
.. [[[end]]]
Will produce this HTML:
.. code-block :: html
<script type="module" src="https://example.datasette.io/module.js"></script>