.. _configuration:

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:

.. code-block:: bash

    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_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]]]

.. _configuration_reference:

``datasette.yaml`` reference
----------------------------

The following example shows some of the valid configuration options that can exist inside ``datasette.yaml``.

.. [[[cog
    from metadata_doc import config_example
    import textwrap
    config_example(cog, textwrap.dedent(
      """
        # 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
        """)
      )
.. ]]]

.. tab:: datasette.yaml

    .. code-block:: 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


.. tab:: datasette.json

    .. 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": {
                  "allow": {
                    "id": "root"
                  },
                  "plugins": {
                    "datasette-my-plugin": {
                      "key": "valueB"
                    }
                  }
                }
              }
            }
          }
        }
.. [[[end]]]

.. _configuration_reference_settings:

Settings
~~~~~~~~

:ref:`settings` can be configured in ``datasette.yaml`` with the ``settings`` key:

.. [[[cog
    from metadata_doc import config_example
    import textwrap
    config_example(cog, textwrap.dedent(
      """
        # inside datasette.yaml
        settings:
          default_allow_sql: off
          default_page_size: 50
        """).strip()
      )
.. ]]]

.. tab:: datasette.yaml

    .. code-block:: yaml

        # inside datasette.yaml
        settings:
          default_allow_sql: off
          default_page_size: 50

.. tab:: datasette.json

    .. code-block:: json

        {
          "settings": {
            "default_allow_sql": "off",
            "default_page_size": 50
          }
        }
.. [[[end]]]

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.`

.. _configuration_reference_plugins:

Plugin configuration
~~~~~~~~~~~~~~~~~~~~

: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:

.. [[[cog
    from metadata_doc import config_example
    import textwrap
    config_example(cog, textwrap.dedent(
      """
        # inside datasette.yaml
        plugins:
          datasette-my-plugin:
            key: my_value
        """).strip()
      )
.. ]]]

.. tab:: datasette.yaml

    .. code-block:: yaml

        # inside datasette.yaml
        plugins:
          datasette-my-plugin:
            key: my_value

.. tab:: datasette.json

    .. code-block:: json

        {
          "plugins": {
            "datasette-my-plugin": {
              "key": "my_value"
            }
          }
        }
.. [[[end]]]

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:

.. [[[cog
    from metadata_doc import config_example
    import textwrap
    config_example(cog, textwrap.dedent(
      """
        # 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()
      )
.. ]]]

.. tab:: datasette.yaml

    .. 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

.. tab:: datasette.json

    .. 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"
                    }
                  }
                }
              }
            }
          }
        }
.. [[[end]]]


.. _configuration_reference_permissions:

Permissions configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

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.

.. _configuration_reference_canned_queries:

Canned queries configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

: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>`.

.. _configuration_reference_css_js:

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>