mirror of
https://github.com/simonw/datasette.git
synced 2026-09-28 04:44:21 +02:00
Renamed canned queries to queries / stored queries in docs
And a few renames in code and YAML as well.
This commit is contained in:
Simon Willison
parent
56b14f37d5
commit
02a1468f1b
17 changed files with 115 additions and 605 deletions
|
|
@ -121,7 +121,7 @@ This configuration will deny access to everyone except the user with ``id`` of `
|
|||
How permissions are resolved
|
||||
----------------------------
|
||||
|
||||
Datasette performs permission checks using the internal :ref:`datasette_allowed`, method which accepts keyword arguments for ``action``, ``resource`` and an optional ``actor``.
|
||||
Datasette performs permission checks using the internal :ref:`datasette_allowed`, method which accepts keyword arguments for ``action``, ``resource`` and an optional ``actor``.
|
||||
|
||||
``resource`` should be an instance of the appropriate ``Resource`` subclass from :mod:`datasette.resources`—for example ``InstanceResource()``, ``DatabaseResource(database="...``)`` or ``TableResource(database="...", table="...")``. This defaults to ``InstanceResource()`` if not specified.
|
||||
|
||||
|
|
@ -468,7 +468,7 @@ You can control the following:
|
|||
* Access to the entire Datasette instance
|
||||
* Access to specific databases
|
||||
* Access to specific tables and views
|
||||
* Access to specific :ref:`queries <canned_queries>`
|
||||
* Access to specific :ref:`queries <queries>`
|
||||
|
||||
If a user has permission to view a table they will be able to view that table, independent of if they have permission to view the database or instance that the table exists within.
|
||||
|
||||
|
|
@ -496,7 +496,7 @@ Here's how to restrict access to your entire Datasette instance to just the ``"i
|
|||
title: My private Datasette instance
|
||||
allow:
|
||||
id: root
|
||||
|
||||
|
||||
|
||||
.. tab:: datasette.json
|
||||
|
||||
|
|
@ -644,7 +644,7 @@ This works for SQL views as well - you can list their names in the ``"tables"``
|
|||
Access to specific queries
|
||||
--------------------------
|
||||
|
||||
:ref:`Queries <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.
|
||||
:ref:`Queries <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`` query in your ``dogs.db`` database to just the :ref:`root user<authentication_root>`:
|
||||
|
||||
|
|
@ -1020,7 +1020,7 @@ You can also restrict permissions such that they can only be used within specifi
|
|||
|
||||
The resulting token will only be able to insert rows, and only to tables in the ``mydatabase`` database.
|
||||
|
||||
Finally, you can restrict permissions to individual resources - tables, SQL views and :ref:`named queries <canned_queries>` - within a specific database::
|
||||
Finally, you can restrict permissions to individual resources - tables, SQL views and :ref:`named queries <queries>` - within a specific database::
|
||||
|
||||
datasette create-token root --resource mydatabase mytable insert-row
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,8 @@ Unreleased
|
|||
|
||||
- Fixed a bug where visiting ``/<database>/-/query`` without a ``?sql=`` parameter returned a 500 error. (:issue:`2743`)
|
||||
- The ``top_canned_query()`` plugin hook has been renamed to :ref:`top_stored_query() <plugin_hook_top_stored_query>`. (:issue:`2747`)
|
||||
- The ``canned_queries()`` plugin hook has been removed. Plugins can use the new ``datasette.add_query()``, ``datasette.update_query()`` and ``datasette.remove_query()`` methods to managed stored queries instead.
|
||||
- The ``canned_queries()`` plugin hook has been removed. Plugins can use the new ``datasette.add_query()``, ``datasette.update_query()`` and ``datasette.remove_query()`` methods to manage stored queries instead.
|
||||
- The ``datasette.get_canned_query()`` and ``datasette.get_canned_queries()`` methods have been removed. Plugins can use ``datasette.get_query()`` and ``datasette.list_queries()`` instead.
|
||||
|
||||
.. _v1_0_a30:
|
||||
|
||||
|
|
@ -658,7 +659,7 @@ For more information and workarounds, read `the security advisory <https://githu
|
|||
Also in this alpha:
|
||||
|
||||
- The new ``datasette plugins --requirements`` option outputs a list of currently installed plugins in Python ``requirements.txt`` format, useful for duplicating that installation elsewhere. (:issue:`2133`)
|
||||
- :ref:`canned_queries_writable` can now define a ``on_success_message_sql`` field in their configuration, containing a SQL query that should be executed upon successful completion of the write operation in order to generate a message to be shown to the user. (:issue:`2138`)
|
||||
- :ref:`queries_writable` can now define a ``on_success_message_sql`` field in their configuration, containing a SQL query that should be executed upon successful completion of the write operation in order to generate a message to be shown to the user. (:issue:`2138`)
|
||||
- The automatically generated border color for a database is now shown in more places around the application. (:issue:`2119`)
|
||||
- Every instance of example shell script code in the documentation should now include a working copy button, free from additional syntax. (:issue:`2140`)
|
||||
|
||||
|
|
@ -1052,7 +1053,7 @@ Other small fixes
|
|||
- The ``base.html`` template now wraps everything other than the ``<footer>`` in a ``<div class="not-footer">`` element, to help with advanced CSS customization. (:issue:`1446`)
|
||||
- The :ref:`render_cell() <plugin_hook_render_cell>` plugin hook can now return an awaitable function. This means the hook can execute SQL queries. (:issue:`1425`)
|
||||
- :ref:`plugin_register_routes` plugin hook now accepts an optional ``datasette`` argument. (:issue:`1404`)
|
||||
- New ``hide_sql`` canned query option for defaulting to hiding the SQL query used by a canned query, see :ref:`canned_queries_options`. (:issue:`1422`)
|
||||
- New ``hide_sql`` canned query option for defaulting to hiding the SQL query used by a canned query, see :ref:`queries_options`. (:issue:`1422`)
|
||||
- New ``--cpu`` option for :ref:`datasette publish cloudrun <publish_cloud_run>`. (:issue:`1420`)
|
||||
- If `Rich <https://github.com/willmcgugan/rich>`__ is installed in the same virtual environment as Datasette, it will be used to provide enhanced display of error tracebacks on the console. (:issue:`1416`)
|
||||
- ``datasette.utils`` :ref:`internals_utils_parse_metadata` function, used by the new `datasette-remote-metadata plugin <https://datasette.io/plugins/datasette-remote-metadata>`__, is now a documented API. (:issue:`1405`)
|
||||
|
|
@ -1426,7 +1427,7 @@ See also `Datasette 0.50: The annotated release notes <https://simonwillison.net
|
|||
|
||||
See also `Datasette 0.49: The annotated release notes <https://simonwillison.net/2020/Sep/15/datasette-0-49/>`__.
|
||||
|
||||
- Writable canned queries now expose a JSON API, see :ref:`canned_queries_json_api`. (:issue:`880`)
|
||||
- Writable canned queries now expose a JSON API, see :ref:`queries_json_api`. (:issue:`880`)
|
||||
- New mechanism for defining page templates with custom path parameters - a template file called ``pages/about/{slug}.html`` will be used to render any requests to ``/about/something``. See :ref:`custom_pages_parameters`. (:issue:`944`)
|
||||
- ``register_output_renderer()`` render functions can now return a ``Response``. (:issue:`953`)
|
||||
- New ``--upgrade`` option for ``datasette install``. (:issue:`945`)
|
||||
|
|
@ -1518,7 +1519,7 @@ Magic parameters for canned queries, a log out feature, improved plugin document
|
|||
Magic parameters for canned queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Canned queries now support :ref:`canned_queries_magic_parameters`, which can be used to insert or select automatically generated values. For example::
|
||||
Canned queries now support :ref:`queries_magic_parameters`, which can be used to insert or select automatically generated values. For example::
|
||||
|
||||
insert into logs
|
||||
(user_id, timestamp)
|
||||
|
|
@ -1549,7 +1550,7 @@ New plugin hooks
|
|||
|
||||
- :ref:`plugin_hook_register_magic_parameters` can be used to define new types of magic canned query parameters.
|
||||
- :ref:`plugin_hook_startup` can run custom code when Datasette first starts up. `datasette-init <https://github.com/simonw/datasette-init>`__ is a new plugin that uses this hook to create database tables and views on startup if they have not yet been created. (:issue:`834`)
|
||||
- :ref:`plugin_hook_canned_queries` lets plugins provide additional canned queries beyond those defined in Datasette's metadata. See `datasette-saved-queries <https://github.com/simonw/datasette-saved-queries>`__ for an example of this hook in action. (:issue:`852`)
|
||||
- ``canned_queries()`` lets plugins provide additional canned queries beyond those defined in Datasette's metadata. See `datasette-saved-queries <https://github.com/simonw/datasette-saved-queries>`__ for an example of this hook in action. (:issue:`852`)
|
||||
- :ref:`plugin_hook_forbidden` is a hook for customizing how Datasette responds to 403 forbidden errors. (:issue:`812`)
|
||||
|
||||
Smaller changes
|
||||
|
|
@ -1624,7 +1625,7 @@ A new debug page at ``/-/permissions`` shows recent permission checks, to help a
|
|||
Writable canned queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Datasette's :ref:`canned_queries` feature lets you define SQL queries in ``metadata.json`` which can then be executed by users visiting a specific URL. https://latest.datasette.io/fixtures/neighborhood_search for example.
|
||||
Datasette's :ref:`queries` feature lets you define SQL queries in ``metadata.json`` which can then be executed by users visiting a specific URL. https://latest.datasette.io/fixtures/neighborhood_search for example.
|
||||
|
||||
Canned queries were previously restricted to ``SELECT``, but Datasette 0.44 introduces the ability for canned queries to execute ``INSERT`` or ``UPDATE`` queries as well, using the new ``"write": true`` property (:issue:`800`):
|
||||
|
||||
|
|
@ -1643,7 +1644,7 @@ Canned queries were previously restricted to ``SELECT``, but Datasette 0.44 intr
|
|||
}
|
||||
}
|
||||
|
||||
See :ref:`canned_queries_writable` for more details.
|
||||
See :ref:`queries_writable` for more details.
|
||||
|
||||
Flash messages
|
||||
~~~~~~~~~~~~~~
|
||||
|
|
@ -1698,7 +1699,7 @@ Smaller changes
|
|||
- New ``request.cookies`` property.
|
||||
- ``/-/plugins`` endpoint now shows a list of hooks implemented by each plugin, e.g. https://latest.datasette.io/-/plugins?all=1
|
||||
- ``request.post_vars()`` method no longer discards empty values.
|
||||
- New "params" canned query key for explicitly setting named parameters, see :ref:`canned_queries_named_parameters`. (:issue:`797`)
|
||||
- New "params" canned query key for explicitly setting named parameters, see :ref:`queries_named_parameters`. (:issue:`797`)
|
||||
- ``request.args`` is now a :ref:`MultiParams <internals_multiparams>` object.
|
||||
- Fixed a bug with the ``datasette plugins`` command. (:issue:`802`)
|
||||
- Nicer pattern for using ``make_app_client()`` in tests. (:issue:`395`)
|
||||
|
|
@ -1732,7 +1733,7 @@ The main focus of this release is a major upgrade to the :ref:`plugin_register_o
|
|||
* Visually distinguish float and integer columns - useful for figuring out why order-by-column might be returning unexpected results. (:issue:`729`)
|
||||
* The :ref:`internals_request`, which is passed to several plugin hooks, is now documented. (:issue:`706`)
|
||||
* New ``metadata.json`` option for setting a custom default page size for specific tables and views, see :ref:`table_configuration_size`. (:issue:`751`)
|
||||
* Canned queries can now be configured with a default URL fragment hash, useful when working with plugins such as `datasette-vega <https://github.com/simonw/datasette-vega>`__, see :ref:`canned_queries_options`. (:issue:`706`)
|
||||
* Canned queries can now be configured with a default URL fragment hash, useful when working with plugins such as `datasette-vega <https://github.com/simonw/datasette-vega>`__, see :ref:`queries_options`. (:issue:`706`)
|
||||
* Fixed a bug in ``datasette publish`` when running on operating systems where the ``/tmp`` directory lives in a different volume, using a backport of the Python 3.8 ``shutil.copytree()`` function. (:issue:`744`)
|
||||
* Every plugin hook is now covered by the unit tests, and a new unit test checks that each plugin hook has at least one corresponding test. (:issue:`771`, :issue:`773`)
|
||||
|
||||
|
|
@ -2249,7 +2250,7 @@ A number of small new features:
|
|||
- Documentation for :ref:`datasette publish and datasette package <publishing>`, closes `#337 <https://github.com/simonw/datasette/issues/337>`_
|
||||
- Fixed compatibility with Python 3.7
|
||||
- ``datasette publish heroku`` now supports app names via the ``-n`` option, which can also be used to overwrite an existing application [Russ Garrett]
|
||||
- Title and description metadata can now be set for :ref:`canned SQL queries <canned_queries>`, closes `#342 <https://github.com/simonw/datasette/issues/342>`_
|
||||
- Title and description metadata can now be set for :ref:`canned SQL queries <queries>`, closes `#342 <https://github.com/simonw/datasette/issues/342>`_
|
||||
- New ``force_https_on`` config option, fixes ``https://`` API URLs when deploying to Zeit Now - closes `#333 <https://github.com/simonw/datasette/issues/333>`_
|
||||
- ``?_json_infinity=1`` query string argument for handling Infinity/-Infinity values in JSON, closes `#332 <https://github.com/simonw/datasette/issues/332>`_
|
||||
- URLs displayed in the results of custom SQL queries are now URLified, closes `#298 <https://github.com/simonw/datasette/issues/298>`_
|
||||
|
|
|
|||
|
|
@ -434,12 +434,12 @@ Here is a simple example:
|
|||
|
||||
:ref:`authentication_permissions_config` has the full details.
|
||||
|
||||
.. _configuration_reference_canned_queries:
|
||||
.. _configuration_reference_queries:
|
||||
|
||||
Queries configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:ref:`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:
|
||||
:ref:`Queries <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
|
||||
|
|
@ -484,7 +484,7 @@ Queries configuration
|
|||
}
|
||||
.. [[[end]]]
|
||||
|
||||
See the :ref:`queries documentation <canned_queries>` for more, including how to configure :ref:`writable queries <canned_queries_writable>`.
|
||||
See the :ref:`queries documentation <queries>` for more, including how to configure :ref:`writable queries <queries_writable>`.
|
||||
|
||||
.. _configuration_reference_css_js:
|
||||
|
||||
|
|
|
|||
|
|
@ -1207,16 +1207,6 @@ Potential use-cases:
|
|||
|
||||
Examples: `datasette-saved-queries <https://datasette.io/plugins/datasette-saved-queries>`__, `datasette-init <https://datasette.io/plugins/datasette-init>`__
|
||||
|
||||
.. _plugin_hook_canned_queries:
|
||||
|
||||
canned_queries(datasette, database, actor)
|
||||
------------------------------------------
|
||||
|
||||
This hook has been removed. Plugins that need to add stored queries should use
|
||||
the :ref:`plugin_hook_startup` hook and call ``await datasette.add_query(...)``.
|
||||
|
||||
Example: `datasette-saved-queries <https://datasette.io/plugins/datasette-saved-queries>`__
|
||||
|
||||
.. _plugin_hook_actor_from_request:
|
||||
|
||||
actor_from_request(datasette, request)
|
||||
|
|
@ -1635,7 +1625,7 @@ register_magic_parameters(datasette)
|
|||
``datasette`` - :ref:`internals_datasette`
|
||||
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``.
|
||||
|
||||
:ref:`canned_queries_magic_parameters` can be used to add automatic parameters to :ref:`configured queries <canned_queries>`. This plugin hook allows additional magic parameters to be defined by plugins.
|
||||
:ref:`queries_magic_parameters` can be used to add automatic parameters to :ref:`configured queries <queries>`. This plugin hook allows additional magic parameters to be defined by plugins.
|
||||
|
||||
Magic parameters all take this format: ``_prefix_rest_of_parameter``. The prefix indicates which magic parameter function should be called - the rest of the parameter is passed as an argument to that function.
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ Warning
|
|||
The following steps are recommended:
|
||||
|
||||
- Disable arbitrary SQL queries by untrusted users. See :ref:`authentication_permissions_execute_sql` for ways to do this. The easiest is to start Datasette with the ``datasette --setting default_allow_sql off`` option.
|
||||
- Define :ref:`queries <canned_queries>` with the SQL queries that use SpatiaLite functions that you want people to be able to execute.
|
||||
- Define :ref:`queries <queries>` with the SQL queries that use SpatiaLite functions that you want people to be able to execute.
|
||||
|
||||
The `Datasette SpatiaLite tutorial <https://datasette.io/tutorials/spatialite>`__ includes detailed instructions for running SpatiaLite safely using these techniques
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ You can also use the `sqlite-utils <https://sqlite-utils.datasette.io/>`__ tool
|
|||
|
||||
sqlite-utils create-view sf-trees.db demo_view "select qSpecies from Street_Tree_List"
|
||||
|
||||
.. _canned_queries:
|
||||
.. _queries:
|
||||
|
||||
Queries
|
||||
-------
|
||||
|
|
@ -173,7 +173,7 @@ You can opt out of this behavior for a configured query using ``is_trusted: fals
|
|||
sql: select * from report
|
||||
is_trusted: false
|
||||
|
||||
.. _canned_queries_named_parameters:
|
||||
.. _queries_named_parameters:
|
||||
|
||||
Query parameters
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
|
@ -313,7 +313,7 @@ You can alternatively provide an explicit list of named parameters using the ``"
|
|||
}
|
||||
.. [[[end]]]
|
||||
|
||||
.. _canned_queries_options:
|
||||
.. _queries_options:
|
||||
|
||||
Additional query options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -389,7 +389,7 @@ This example demonstrates both ``fragment`` and ``hide_sql``:
|
|||
|
||||
`See here <https://latest.datasette.io/fixtures#queries>`__ for a demo of this in action.
|
||||
|
||||
.. _canned_queries_writable:
|
||||
.. _queries_writable:
|
||||
|
||||
Writable queries
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
|
@ -524,7 +524,7 @@ You can pre-populate form fields when the page first loads using a query string,
|
|||
|
||||
If you specify a query in ``"on_success_message_sql"``, that query will be executed after the main query. The first column of the first row return by that query will be displayed as a success message. Named parameters from the main query will be made available to the success message query as well.
|
||||
|
||||
.. _canned_queries_magic_parameters:
|
||||
.. _queries_magic_parameters:
|
||||
|
||||
Magic parameters
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
|
@ -621,7 +621,7 @@ The form presented at ``/mydatabase/add_message`` will have just a field for ``m
|
|||
|
||||
Additional custom magic parameters can be added by plugins using the :ref:`plugin_hook_register_magic_parameters` hook.
|
||||
|
||||
.. _canned_queries_json_api:
|
||||
.. _queries_json_api:
|
||||
|
||||
JSON API for writable queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ except (KeyError, TypeError):
|
|||
New code:
|
||||
```python
|
||||
try:
|
||||
query_info = await datasette.get_canned_query(database, query_name, request.actor)
|
||||
query_info = await datasette.get_query(database, query_name)
|
||||
if query_info and "title" in query_info:
|
||||
title = query_info["title"]
|
||||
except (KeyError, TypeError):
|
||||
|
|
@ -253,7 +253,7 @@ except (KeyError, TypeError):
|
|||
|
||||
### Update render functions to async
|
||||
|
||||
If your plugin's render function needs to call `datasette.get_canned_query()` or other async Datasette methods, it must be declared as async:
|
||||
If your plugin's render function needs to call `datasette.get_query()` or other async Datasette methods, it must be declared as async:
|
||||
|
||||
Old code:
|
||||
```python
|
||||
|
|
@ -268,7 +268,7 @@ New code:
|
|||
async def render_atom(datasette, request, sql, columns, rows, database, table, query_name, view_name, data):
|
||||
# ...
|
||||
if query_name:
|
||||
query_info = await datasette.get_canned_query(database, query_name, request.actor)
|
||||
query_info = await datasette.get_query(database, query_name)
|
||||
if query_info and "title" in query_info:
|
||||
title = query_info["title"]
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue