github/datasette
1
0
Fork 0
mirror of https://github.com/simonw/datasette.git synced 2025-12-10 16:51:24 +01:00
Code Issues Projects Releases Packages Wiki Activity

Move non-metadata configuration from metadata.yaml to datasette.yaml

Browse source 
* Allow and permission blocks moved to datasette.yaml
* Documentation updates, initial framework for configuration reference
This commit is contained in:
Alex Garcia 2023-10-12 09:16:37 -07:00 • committed by GitHub
commit 35deaabcb1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
22 changed files with 595 additions and 493 deletions
Download patch file Download diff file Expand all files Collapse all files

338
docs/authentication.rst
View file

@ -67,7 +67,7 @@ An **action** is a string describing the action the actor would like to perform.
A **resource** is the item the actor wishes to interact with - for example a specific database or table. Some actions, such as ``permissions-debug``, are not associated with a particular resource.
Datasette's built-in view permissions (``view-database``, ``view-table`` etc) default to *allow* - unless you :ref:`configure additional permission rules <authentication_permissions_metadata>` unauthenticated users will be allowed to access content.
Datasette's built-in view permissions (``view-database``, ``view-table`` etc) default to *allow* - unless you :ref:`configure additional permission rules <authentication_permissions_config>` unauthenticated users will be allowed to access content.
Permissions with potentially harmful effects should default to *deny*. Plugin authors should account for this when designing new plugins - for example, the `datasette-upload-csvs <https://github.com/simonw/datasette-upload-csvs>`__ plugin defaults to deny so that installations don't accidentally allow unauthenticated users to create new tables by uploading a CSV file.
@ -76,7 +76,7 @@ Permissions with potentially harmful effects should default to *deny*. Plugin au
Defining permissions with "allow" blocks
----------------------------------------
The standard way to define permissions in Datasette is to use an ``"allow"`` block. This is a JSON document describing which actors are allowed to perform a permission.
The standard way to define permissions in Datasette is to use an ``"allow"`` block :ref:`in the datasette.yaml file <authentication_permissions_config>`. This is a JSON document describing which actors are allowed to perform a permission.
The most basic form of allow block is this (`allow demo <https://latest.datasette.io/-/allow-debug?actor=%7B%22id%22%3A+%22root%22%7D&allow=%7B%0D%0A++++++++%22id%22%3A+%22root%22%0D%0A++++%7D>`__, `deny demo <https://latest.datasette.io/-/allow-debug?actor=%7B%22id%22%3A+%22trevor%22%7D&allow=%7B%0D%0A++++++++%22id%22%3A+%22root%22%0D%0A++++%7D>`__):
@ -186,18 +186,18 @@ The /-/allow-debug tool
The ``/-/allow-debug`` tool lets you try out different ``"action"`` blocks against different ``"actor"`` JSON objects. You can try that out here: https://latest.datasette.io/-/allow-debug
.. _authentication_permissions_metadata:
.. _authentication_permissions_config:
Access permissions in metadata
==============================
Access permissions in ``datasette.yaml``
========================================
There are two ways to configure permissions using ``metadata.json`` (or ``metadata.yaml``).
There are two ways to configure permissions using ``datasette.yaml`` (or ``datasette.json``).
For simple visibility permissions you can use ``"allow"`` blocks in the root, database, table and query sections.
For other permissions you can use a ``"permissions"`` block, described :ref:`in the next section <authentication_permissions_other>`.
You can limit who is allowed to view different parts of your Datasette instance using ``"allow"`` keys in your :ref:`metadata` configuration.
You can limit who is allowed to view different parts of your Datasette instance using ``"allow"`` keys in your :ref:`configuration`.
You can control the following:
@ -216,25 +216,25 @@ Access to an instance
Here's how to restrict access to your entire Datasette instance to just the ``"id": "root"`` user:
.. [[[cog
from metadata_doc import metadata_example
metadata_example(cog, {
"title": "My private Datasette instance",
"allow": {
"id": "root"
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
from metadata_doc import config_example
config_example(cog, """
title: My private Datasette instance
allow:
id: root
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
title: My private Datasette instance
allow:
id: root
.. tab:: datasette.json
.. code-block:: json
@ -249,21 +249,22 @@ Here's how to restrict access to your entire Datasette instance to just the ``"i
To deny access to all users, you can use ``"allow": false``:
.. [[[cog
metadata_example(cog, {
"title": "My entirely inaccessible instance",
"allow": False
})
config_example(cog, """
title: My entirely inaccessible instance
allow: false
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
title: My entirely inaccessible instance
allow: false
title: My entirely inaccessible instance
allow: false
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -283,28 +284,26 @@ Access to specific databases
To limit access to a specific ``private.db`` database to just authenticated users, use the ``"allow"`` block like this:
.. [[[cog
metadata_example(cog, {
"databases": {
"private": {
"allow": {
"id": "*"
}
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
databases:
private:
allow:
id: '*'
id: "*"
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
databases:
private:
allow:
id: "*"
.. tab:: datasette.json
.. code-block:: json
@ -327,34 +326,30 @@ Access to specific tables and views
To limit access to the ``users`` table in your ``bakery.db`` database:
.. [[[cog
metadata_example(cog, {
"databases": {
"bakery": {
"tables": {
"users": {
"allow": {
"id": "*"
}
}
}
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
databases:
bakery:
tables:
users:
allow:
id: '*'
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
databases:
bakery:
tables:
users:
allow:
id: '*'
.. tab:: datasette.json
.. code-block:: json
@ -385,32 +380,12 @@ This works for SQL views as well - you can list their names in the ``"tables"``
Access to specific canned queries
---------------------------------
:ref:`canned_queries` allow you to configure named SQL queries in your ``metadata.json`` that can be executed by users. These queries can be set up to both read and write to the database, so controlling who can execute them can be important.
:ref:`canned_queries` allow you to configure named SQL queries in your ``datasette.yaml`` that can be executed by users. These queries can be set up to both read and write to the database, so controlling who can execute them can be important.
To limit access to the ``add_name`` canned query in your ``dogs.db`` database to just the :ref:`root user<authentication_root>`:
.. [[[cog
metadata_example(cog, {
"databases": {
"dogs": {
"queries": {
"add_name": {
"sql": "INSERT INTO names (name) VALUES (:name)",
"write": True,
"allow": {
"id": ["root"]
}
}
}
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
databases:
dogs:
queries:
@ -420,9 +395,26 @@ To limit access to the ``add_name`` canned query in your ``dogs.db`` database to
allow:
id:
- root
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
databases:
dogs:
queries:
add_name:
sql: INSERT INTO names (name) VALUES (:name)
write: true
allow:
id:
- root
.. tab:: datasette.json
.. code-block:: json
@ -461,19 +453,20 @@ You can alternatively use an ``"allow_sql"`` block to control who is allowed to
To prevent any user from executing arbitrary SQL queries, use this:
.. [[[cog
metadata_example(cog, {
"allow_sql": False
})
config_example(cog, """
allow_sql: false
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
allow_sql: false
allow_sql: false
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -485,22 +478,22 @@ To prevent any user from executing arbitrary SQL queries, use this:
To enable just the :ref:`root user<authentication_root>` to execute SQL for all databases in your instance, use the following:
.. [[[cog
metadata_example(cog, {
"allow_sql": {
"id": "root"
}
})
config_example(cog, """
allow_sql:
id: root
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
allow_sql:
id: root
allow_sql:
id: root
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -514,28 +507,26 @@ To enable just the :ref:`root user<authentication_root>` to execute SQL for all
To limit this ability for just one specific database, use this:
.. [[[cog
metadata_example(cog, {
"databases": {
"mydatabase": {
"allow_sql": {
"id": "root"
}
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
databases:
mydatabase:
allow_sql:
id: root
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
databases:
mydatabase:
allow_sql:
id: root
.. tab:: datasette.json
.. code-block:: json
@ -552,33 +543,32 @@ To limit this ability for just one specific database, use this:
.. _authentication_permissions_other:
Other permissions in metadata
=============================
Other permissions in ``datasette.yaml``
=======================================
For all other permissions, you can use one or more ``"permissions"`` blocks in your metadata.
For all other permissions, you can use one or more ``"permissions"`` blocks in your ``datasette.yaml`` configuration file.
To grant access to the :ref:`permissions debug tool <PermissionsDebugView>` to all signed in users you can grant ``permissions-debug`` to any actor with an ``id`` matching the wildcard ``*`` by adding this a the root of your metadata:
To grant access to the :ref:`permissions debug tool <PermissionsDebugView>` to all signed in users, you can grant ``permissions-debug`` to any actor with an ``id`` matching the wildcard ``*`` by adding this a the root of your configuration:
.. [[[cog
metadata_example(cog, {
"permissions": {
"debug-menu": {
"id": "*"
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
permissions:
debug-menu:
id: '*'
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
permissions:
debug-menu:
id: '*'
.. tab:: datasette.json
.. code-block:: json
@ -594,31 +584,28 @@ To grant access to the :ref:`permissions debug tool <PermissionsDebugView>` to a
To grant ``create-table`` to the user with ``id`` of ``editor`` for the ``docs`` database:
.. [[[cog
metadata_example(cog, {
"databases": {
"docs": {
"permissions": {
"create-table": {
"id": "editor"
}
}
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
databases:
docs:
permissions:
create-table:
id: editor
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
databases:
docs:
permissions:
create-table:
id: editor
.. tab:: datasette.json
.. code-block:: json
@ -638,27 +625,7 @@ To grant ``create-table`` to the user with ``id`` of ``editor`` for the ``docs``
And for ``insert-row`` against the ``reports`` table in that ``docs`` database:
.. [[[cog
metadata_example(cog, {
"databases": {
"docs": {
"tables": {
"reports": {
"permissions": {
"insert-row": {
"id": "editor"
}
}
}
}
}
}
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
databases:
docs:
tables:
@ -666,9 +633,24 @@ And for ``insert-row`` against the ``reports`` table in that ``docs`` database:
permissions:
insert-row:
id: editor
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
databases:
docs:
tables:
reports:
permissions:
insert-row:
id: editor
.. tab:: datasette.json
.. code-block:: json

64
docs/configuration.rst
View file

@ -13,15 +13,15 @@ To facilitate this, You can provide a ``datasette.yaml`` configuration file to d
.. _configuration_reference:
``datasette.yaml`` reference
``datasette.yaml`` Reference
----------------------------
Here's a full example of all the valid configuration options that can exist inside ``datasette.yaml``.
.. [[[cog
from metadata_doc import metadata_example
from metadata_doc import config_example
import textwrap
metadata_example(cog, yaml=textwrap.dedent(
config_example(cog, textwrap.dedent(
"""
# Datasette settings block
settings:
@ -52,10 +52,11 @@ Here's a full example of all the valid configuration options that can exist insi
)
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
# Datasette settings block
settings:
default_page_size: 50
@ -82,7 +83,8 @@ Here's a full example of all the valid configuration options that can exist insi
datasette-my-plugin:
key: valueB
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -125,9 +127,9 @@ Settings configuration
:ref:`settings` can be configured in ``datasette.yaml`` with the ``settings`` key.
.. [[[cog
from metadata_doc import metadata_example
from metadata_doc import config_example
import textwrap
metadata_example(cog, yaml=textwrap.dedent(
config_example(cog, textwrap.dedent(
"""
# inside datasette.yaml
settings:
@ -137,7 +139,7 @@ Settings configuration
)
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -146,7 +148,7 @@ Settings configuration
default_allow_sql: off
default_page_size: 50
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -165,9 +167,9 @@ Plugin configuration
Configuration for plugins can be defined inside ``datasette.yaml``. For top-level plugin configuration, use the ``plugins`` key.
.. [[[cog
from metadata_doc import metadata_example
from metadata_doc import config_example
import textwrap
metadata_example(cog, yaml=textwrap.dedent(
config_example(cog, textwrap.dedent(
"""
# inside datasette.yaml
plugins:
@ -177,7 +179,7 @@ Configuration for plugins can be defined inside ``datasette.yaml``. For top-leve
)
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -186,7 +188,7 @@ Configuration for plugins can be defined inside ``datasette.yaml``. For top-leve
datasette-my-plugin:
key: my_value
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -202,9 +204,9 @@ Configuration for plugins can be defined inside ``datasette.yaml``. For top-leve
For database level or table level plugin configuration, nest it under the appropriate place under ``databases``.
.. [[[cog
from metadata_doc import metadata_example
from metadata_doc import config_example
import textwrap
metadata_example(cog, yaml=textwrap.dedent(
config_example(cog, textwrap.dedent(
"""
# inside datasette.yaml
databases:
@ -224,7 +226,7 @@ For database level or table level plugin configuration, nest it under the approp
)
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -243,7 +245,7 @@ For database level or table level plugin configuration, nest it under the approp
datasette-my-plugin:
key: my_value
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -269,4 +271,30 @@ For database level or table level plugin configuration, nest it under the approp
}
}
}
.. [[[end]]]
.. [[[end]]]
.. _configuration_reference_permissions:
Permissions Configuration
~~~~~~~~~~~~~~~~~~~~
TODO
.. _configuration_reference_authentication:
Authentication Configuration
~~~~~~~~~~~~~~~~~~~~
TODO
.. _configuration_reference_canned_queries:
Canned Queries Configuration
~~~~~~~~~~~~~~~~~~~~
TODO
.. _configuration_reference_css_js:
Extra CSS and JS Configuration
~~~~~~~~~~~~~~~~~~~~
TODO

137
docs/custom_templates.rst
View file

@ -10,35 +10,34 @@ Datasette provides a number of ways of customizing the way data is displayed.
Custom CSS and JavaScript
-------------------------
When you launch Datasette, you can specify a custom metadata file like this::
When you launch Datasette, you can specify a custom configuration file like this::
datasette mydb.db --metadata metadata.yaml
datasette mydb.db --config datasette.yaml
Your ``metadata.yaml`` file can include links that look like this:
Your ``datasette.yaml`` file can include links that look like this:
.. [[[cog
from metadata_doc import metadata_example
metadata_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:: YAML
.. code-block:: yaml
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
.. tab:: 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
.. tab:: datasette.json
.. code-block:: json
@ -62,35 +61,30 @@ The extra CSS and JavaScript files will be linked in the ``<head>`` of every pag
You can also specify a SRI (subresource integrity hash) for these assets:
.. [[[cog
metadata_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:: YAML
.. code-block:: yaml
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
.. tab:: 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=
.. tab:: datasette.json
.. code-block:: json
@ -115,7 +109,7 @@ This will produce:
.. code-block:: html
<link rel="stylesheet" href="https://simonwillison.net/static/css/all.bf8cd891642c.css"
integrity="sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI"
integrity="sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI"
crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"
integrity="sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g="
@ -127,26 +121,24 @@ matches the content served. You can generate hashes using `www.srihash.org <http
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
metadata_example(cog, {
"extra_js_urls": [
{
"url": "https://example.datasette.io/module.js",
"module": True
}
]
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
.. tab:: datasette.json
.. code-block:: json
@ -259,37 +251,36 @@ Consider the following directory structure::
You can start Datasette using ``--static assets:static-files/`` to serve those
files from the ``/assets/`` mount point::
datasette -m metadata.json --static assets:static-files/ --memory
datasette --config datasette.yaml --static assets:static-files/ --memory
The following URLs will now serve the content from those CSS and JS files::
http://localhost:8001/assets/styles.css
http://localhost:8001/assets/app.js
You can reference those files from ``metadata.json`` like so:
You can reference those files from ``datasette.yaml`` like so:
.. [[[cog
metadata_example(cog, {
"extra_css_urls": [
"/assets/styles.css"
],
"extra_js_urls": [
"/assets/app.js"
]
})
.. ]]]
.. tab:: YAML
.. code-block:: yaml
config_example(cog, """
extra_css_urls:
- /assets/styles.css
extra_js_urls:
- /assets/app.js
""")
.. ]]]
.. tab:: datasette.yaml
.. code-block:: yaml
.. tab:: JSON
extra_css_urls:
- /assets/styles.css
extra_js_urls:
- /assets/app.js
.. tab:: datasette.json
.. code-block:: json

12
docs/facets.rst
View file

@ -120,7 +120,7 @@ Here's an example that turns on faceting by default for the ``qLegalStatus`` col
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -132,7 +132,7 @@ Here's an example that turns on faceting by default for the ``qLegalStatus`` col
- qLegalStatus
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -164,7 +164,7 @@ You can specify :ref:`array <facet_by_json_array>` or :ref:`date <facet_by_date>
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -173,7 +173,7 @@ You can specify :ref:`array <facet_by_json_array>` or :ref:`date <facet_by_date>
- date: created
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -206,7 +206,7 @@ You can change the default facet size (the number of results shown for each face
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -219,7 +219,7 @@ You can change the default facet size (the number of results shown for each face
facet_size: 10
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json

4
docs/full_text_search.rst
View file

@ -81,7 +81,7 @@ Here is an example which enables full-text search (with SQLite advanced search o
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -94,7 +94,7 @@ Here is an example which enables full-text search (with SQLite advanced search o
searchmode: raw
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json

2
docs/internals.rst
View file

@ -364,7 +364,7 @@ await .permission_allowed(actor, action, resource=None, default=...)
Check if the given actor has :ref:`permission <authentication_permissions>` to perform the given action on the given resource.
Some permission checks are carried out against :ref:`rules defined in metadata.json <authentication_permissions_metadata>`, while other custom permissions may be decided by plugins that implement the :ref:`plugin_hook_permission_allowed` plugin hook.
Some permission checks are carried out against :ref:`rules defined in datasette.yaml <authentication_permissions_config>`, while other custom permissions may be decided by plugins that implement the :ref:`plugin_hook_permission_allowed` plugin hook.
If neither ``metadata.json`` nor any of the plugins provide an answer to the permission query the ``default`` argument will be returned.

126
docs/metadata.rst
View file

@ -26,7 +26,7 @@ Your ``metadata.yaml`` file can look something like this:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -38,7 +38,7 @@ Your ``metadata.yaml`` file can look something like this:
source_url: http://example.com/
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -90,7 +90,7 @@ You can also provide metadata at the per-database or per-table level, like this:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -105,7 +105,7 @@ You can also provide metadata at the per-database or per-table level, like this:
license_url: https://creativecommons.org/licenses/by/3.0/us/
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -168,7 +168,7 @@ You can include descriptions for your columns by adding a ``"columns": {"name-of
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -181,7 +181,7 @@ You can include descriptions for your columns by adding a ``"columns": {"name-of
column2: Description of column 2
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -230,7 +230,7 @@ Column units are configured in the metadata like so:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -243,7 +243,7 @@ Column units are configured in the metadata like so:
column2: Hz
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -276,7 +276,7 @@ registered with Pint:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -284,7 +284,7 @@ registered with Pint:
- decibel = [] = dB
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -320,7 +320,7 @@ By default Datasette tables are sorted by primary key. You can over-ride this de
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -331,7 +331,7 @@ By default Datasette tables are sorted by primary key. You can over-ride this de
sort: created
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -364,7 +364,7 @@ Or use ``"sort_desc"`` to sort in descending order:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -375,7 +375,7 @@ Or use ``"sort_desc"`` to sort in descending order:
sort_desc: created
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -413,7 +413,7 @@ Datasette defaults to displaying 100 rows per page, for both tables and views. Y
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -424,7 +424,7 @@ Datasette defaults to displaying 100 rows per page, for both tables and views. Y
size: 10
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -469,7 +469,7 @@ control which columns are available for sorting you can do so using the optional
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -482,7 +482,7 @@ control which columns are available for sorting you can do so using the optional
- weight
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -526,7 +526,7 @@ You can use ``sortable_columns`` to enable specific sort orders for a view calle
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -539,7 +539,7 @@ You can use ``sortable_columns`` to enable specific sort orders for a view calle
- impressions
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -586,7 +586,7 @@ used for the link label with the ``label_column`` property:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -597,7 +597,7 @@ used for the link label with the ``label_column`` property:
label_column: title
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -636,7 +636,7 @@ SpatiaLite tables are automatically hidden) using ``"hidden": true``:
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -647,7 +647,7 @@ SpatiaLite tables are automatically hidden) using ``"hidden": true``:
hidden: true
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -689,13 +689,71 @@ Here's an example of a ``metadata.yml`` file, re-using an example from :ref:`can
tables:
no_primary_key:
hidden: true
queries:
# This query provides LIKE-based search
neighborhood_search:
sql: |-
select neighborhood, facet_cities.name, state
from facetable join facet_cities on facetable.city_id = facet_cities.id
where neighborhood like '%' || :text || '%' order by neighborhood;
title: Search neighborhoods
description_html: |-
<p>This demonstrates <em>basic</em> LIKE search
.. _metadata_reference:
Metadata Reference
-----------------------
A full reference of every supported option in a ``metadata.json`` or ``metadata.yaml`` file.
Top-level Metadata
~~~~~~~~~~~~~~~~~~
"Top-level" metadata refers to fields that can be specified at the root level of a metadata file. These attributes are meant to describe the entire Datasette instance.
The following are the full list of allowed top-level metadata fields:
- ``title``
- ``description``
- ``description_html``
- ``license``
- ``license_url``
- ``source``
- ``source_url``
Database-level Metadata
~~~~~~~~~~~~~~~~~~
"Database-level" metadata refers to fields that can be specified for each database in a Datasette instance. These attributes should be listed under a database inside the `"databases"` field.
The following are the full list of allowed database-level metadata fields:
- ``source``
- ``source_url``
- ``license``
- ``license_url``
- ``about``
- ``about_url``
Table-level Metadata
~~~~~~~~~~~~~~~~~~
"Table-level" metadata refers to fields that can be specified for each table in a Datasette instance. These attributes should be listed under a specific table using the `"tables"` field.
The following are the full list of allowed table-level metadata fields:
- ``source``
- ``source_url``
- ``license``
- ``license_url``
- ``about``
- ``about_url``
- ``hidden``
- ``sort/sort_desc``
- ``size``
- ``sortable_columns``
- ``label_column``
- ``facets``
- ``fts_table``
- ``fts_pk``
- ``searchmode``
- ``columns``

21
docs/metadata_doc.py
View file

@ -16,10 +16,27 @@ def metadata_example(cog, data=None, yaml=None):
output_yaml = yaml
else:
output_yaml = safe_dump(data, sort_keys=False)
cog.out("\n.. tab:: YAML\n\n")
cog.out("\n.. tab:: metadata.yaml\n\n")
cog.out(" .. code-block:: yaml\n\n")
cog.out(textwrap.indent(output_yaml, " "))
cog.out("\n\n.. tab:: JSON\n\n")
cog.out("\n\n.. tab:: metadata.json\n\n")
cog.out(" .. code-block:: json\n\n")
cog.out(textwrap.indent(json.dumps(data, indent=2), " "))
cog.out("\n")
def config_example(cog, input):
if type(input) is str:
# round_trip_load to preserve key order:
data = round_trip_load(input)
output_yaml = input
else:
data = input
output_yaml = safe_dump(input, sort_keys=False)
cog.out("\n.. tab:: datasette.yaml\n\n")
cog.out(" .. code-block:: yaml\n\n")
cog.out(textwrap.indent(output_yaml, " "))
cog.out("\n\n.. tab:: datasette.json\n\n")
cog.out(" .. code-block:: json\n\n")
cog.out(textwrap.indent(json.dumps(data, indent=2), " "))
cog.out("\n")

30
docs/plugins.rst
View file

@ -319,13 +319,13 @@ To write that to a ``requirements.txt`` file, run this::
Plugin configuration
--------------------
Plugins can have their own configuration, embedded in a :ref:`metadata` file. Configuration options for plugins live within a ``"plugins"`` key in that file, which can be included at the root, database or table level.
Plugins can have their own configuration, embedded in a :ref:`configuration` file. Configuration options for plugins live within a ``"plugins"`` key in that file, which can be included at the root, database or table level.
Here is an example of some plugin configuration for a specific table:
.. [[[cog
from metadata_doc import metadata_example
metadata_example(cog, {
from metadata_doc import config_example
config_example(cog, {
"databases": {
"sf-trees": {
"tables": {
@ -343,7 +343,7 @@ Here is an example of some plugin configuration for a specific table:
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -357,7 +357,7 @@ Here is an example of some plugin configuration for a specific table:
longitude_column: lng
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -386,12 +386,12 @@ This tells the ``datasette-cluster-map`` column which latitude and longitude col
Secret configuration values
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Any values embedded in ``metadata.yaml`` will be visible to anyone who views the ``/-/metadata`` page of your Datasette instance. Some plugins may need configuration that should stay secret - API keys for example. There are two ways in which you can store secret configuration values.
Some plugins may need configuration that should stay secret - API keys for example. There are two ways in which you can store secret configuration values.
**As environment variables**. If your secret lives in an environment variable that is available to the Datasette process, you can indicate that the configuration value should be read from that environment variable like so:
.. [[[cog
metadata_example(cog, {
config_example(cog, {
"plugins": {
"datasette-auth-github": {
"client_secret": {
@ -402,7 +402,7 @@ Any values embedded in ``metadata.yaml`` will be visible to anyone who views the
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -412,7 +412,7 @@ Any values embedded in ``metadata.yaml`` will be visible to anyone who views the
$env: GITHUB_CLIENT_SECRET
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -430,7 +430,7 @@ Any values embedded in ``metadata.yaml`` will be visible to anyone who views the
**As values in separate files**. Your secrets can also live in files on disk. To specify a secret should be read from a file, provide the full file path like this:
.. [[[cog
metadata_example(cog, {
config_example(cog, {
"plugins": {
"datasette-auth-github": {
"client_secret": {
@ -441,7 +441,7 @@ Any values embedded in ``metadata.yaml`` will be visible to anyone who views the
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -451,7 +451,7 @@ Any values embedded in ``metadata.yaml`` will be visible to anyone who views the
$file: /secrets/client-secret
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -477,7 +477,7 @@ If you are publishing your data using the :ref:`datasette publish <cli_publish>`
This will set the necessary environment variables and add the following to the deployed ``metadata.yaml``:
.. [[[cog
metadata_example(cog, {
config_example(cog, {
"plugins": {
"datasette-auth-github": {
"client_id": {
@ -491,7 +491,7 @@ This will set the necessary environment variables and add the following to the d
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -503,7 +503,7 @@ This will set the necessary environment variables and add the following to the d
$env: DATASETTE_AUTH_GITHUB_CLIENT_SECRET
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json

5
docs/settings.rst
View file

@ -33,6 +33,7 @@ As an alternative to this, you can run Datasette in *configuration directory* mo
# In a directory called my-app:
my-app/one.db
my-app/two.db
my-app/datasette.yaml
my-app/metadata.json
my-app/templates/index.html
my-app/plugins/my_plugin.py
@ -47,7 +48,7 @@ Datasette will detect the files in that directory and automatically configure it
The files that can be included in this directory are as follows. All are optional.
* ``*.db`` (or ``*.sqlite3`` or ``*.sqlite``) - SQLite database files that will be served by Datasette
* ``datasette.json`` - :ref:`configuration` for the Datasette instance
* ``datasette.yaml`` - :ref:`configuration` for the Datasette instance
* ``metadata.json`` - :ref:`metadata` for those databases - ``metadata.yaml`` or ``metadata.yml`` can be used as well
* ``inspect-data.json`` - the result of running ``datasette inspect *.db --inspect-file=inspect-data.json`` from the configuration directory - any database files listed here will be treated as immutable, so they should not be changed while Datasette is running
* ``templates/`` - a directory containing :ref:`customization_custom_templates`
@ -72,7 +73,7 @@ Setting this to ``off`` causes permission checks for :ref:`permissions_execute_s
datasette mydatabase.db --setting default_allow_sql off
There are two ways to achieve this: the other is to add ``"allow_sql": false`` to your ``metadata.json`` file, as described in :ref:`authentication_permissions_execute_sql`. This setting offers a more convenient way to do this.
Another way to achieve this is to add ``"allow_sql": false`` to your ``datasette.yaml`` file, as described in :ref:`authentication_permissions_execute_sql`. This setting offers a more convenient way to do this.
.. _setting_default_page_size:

56
docs/sql_queries.rst
View file

@ -71,11 +71,11 @@ You can also use the `sqlite-utils <https://sqlite-utils.datasette.io/>`__ tool
Canned queries
--------------
As an alternative to adding views to your database, you can define canned queries inside your ``metadata.yaml`` file. Here's an example:
As an alternative to adding views to your database, you can define canned queries inside your ``datasette.yaml`` file. Here's an example:
.. [[[cog
from metadata_doc import metadata_example
metadata_example(cog, {
from metadata_doc import config_example, config_example
config_example(cog, {
"databases": {
"sf-trees": {
"queries": {
@ -88,7 +88,7 @@ As an alternative to adding views to your database, you can define canned querie
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -99,7 +99,7 @@ As an alternative to adding views to your database, you can define canned querie
sql: select qSpecies from Street_Tree_List
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -147,11 +147,11 @@ Here's an example of a canned query with a named parameter:
where neighborhood like '%' || :text || '%'
order by neighborhood;
In the canned query metadata looks like this:
In the canned query configuration looks like this:
.. [[[cog
metadata_example(cog, yaml="""
config_example(cog, """
databases:
fixtures:
queries:
@ -166,10 +166,11 @@ In the canned query metadata looks like this:
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
databases:
fixtures:
queries:
@ -182,7 +183,8 @@ In the canned query metadata looks like this:
where neighborhood like '%' || :text || '%'
order by neighborhood
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -210,7 +212,7 @@ In this example the ``:text`` named parameter is automatically extracted from th
You can alternatively provide an explicit list of named parameters using the ``"params"`` key, like this:
.. [[[cog
metadata_example(cog, yaml="""
config_example(cog, """
databases:
fixtures:
queries:
@ -227,10 +229,11 @@ You can alternatively provide an explicit list of named parameters using the ``"
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
databases:
fixtures:
queries:
@ -245,7 +248,8 @@ You can alternatively provide an explicit list of named parameters using the ``"
where neighborhood like '%' || :text || '%'
order by neighborhood
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -290,7 +294,7 @@ You can set a default fragment hash that will be included in the link to the can
This example demonstrates both ``fragment`` and ``hide_sql``:
.. [[[cog
metadata_example(cog, yaml="""
config_example(cog, """
databases:
fixtures:
queries:
@ -304,10 +308,11 @@ This example demonstrates both ``fragment`` and ``hide_sql``:
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
databases:
fixtures:
queries:
@ -319,7 +324,8 @@ This example demonstrates both ``fragment`` and ``hide_sql``:
from facetable join facet_cities on facetable.city_id = facet_cities.id
where neighborhood like '%' || :text || '%' order by neighborhood;
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -350,7 +356,7 @@ Canned queries by default are read-only. You can use the ``"write": true`` key t
See :ref:`authentication_permissions_query` for details on how to add permission checks to canned queries, using the ``"allow"`` key.
.. [[[cog
metadata_example(cog, {
config_example(cog, {
"databases": {
"mydatabase": {
"queries": {
@ -364,7 +370,7 @@ See :ref:`authentication_permissions_query` for details on how to add permission
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -376,7 +382,7 @@ See :ref:`authentication_permissions_query` for details on how to add permission
write: true
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -407,7 +413,7 @@ You can customize how Datasette represents success and errors using the followin
For example:
.. [[[cog
metadata_example(cog, {
config_example(cog, {
"databases": {
"mydatabase": {
"queries": {
@ -426,7 +432,7 @@ For example:
})
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
@ -444,7 +450,7 @@ For example:
on_error_redirect: /mydatabase
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json
@ -510,7 +516,7 @@ Available magic parameters are:
Here's an example configuration that adds a message from the authenticated user, storing various pieces of additional metadata using magic parameters:
.. [[[cog
metadata_example(cog, yaml="""
config_example(cog, """
databases:
mydatabase:
queries:
@ -527,10 +533,11 @@ Here's an example configuration that adds a message from the authenticated user,
""")
.. ]]]
.. tab:: YAML
.. tab:: datasette.yaml
.. code-block:: yaml
databases:
mydatabase:
queries:
@ -545,7 +552,8 @@ Here's an example configuration that adds a message from the authenticated user,
)
write: true
.. tab:: JSON
.. tab:: datasette.json
.. code-block:: json

8
docs/writing_plugins.rst
View file

@ -202,7 +202,7 @@ If it cannot find the requested configuration at the table layer, it will fall b
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -214,7 +214,7 @@ If it cannot find the requested configuration at the table layer, it will fall b
longitude_column: xlng
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json
@ -247,7 +247,7 @@ The plugin configuration could also be set at the top level of ``datasette.yaml`
})
.. ]]]
.. tab:: YAML
.. tab:: metadata.yaml
.. code-block:: yaml
@ -257,7 +257,7 @@ The plugin configuration could also be set at the top level of ``datasette.yaml`
longitude_column: xlng
.. tab:: JSON
.. tab:: metadata.json
.. code-block:: json