Improved docs for user-facing SQL query pages

- /database-name/-/execute-write
- /-/queries

docs/authentication.rst

@@ -1413,7 +1413,7 @@ Actor is allowed to drop a database table.
 execute-sql
 -----------
 
-Actor is allowed to run arbitrary read-only SQL queries against a specific database, e.g. https://latest.datasette.io/fixtures/-/query?sql=select+100
+Actor is allowed to run arbitrary read-only SQL queries against a specific database using the :ref:`custom SQL query page <pages_custom_sql_queries>`, e.g. https://latest.datasette.io/fixtures/-/query?sql=select+100
 
 ``resource`` - ``datasette.resources.DatabaseResource(database)``
     ``database`` is the name of the database (string)
@@ -1425,7 +1425,7 @@ See also :ref:`the default_allow_sql setting <setting_default_allow_sql>`.
 execute-write-sql
 -----------------
 
-Actor is allowed to run arbitrary writable SQL queries against a specific database, subject to table-level write permissions such as ``insert-row``, ``update-row`` and ``delete-row``. SQL functions are allowed and are not separately restricted by Datasette permissions.
+Actor is allowed to run arbitrary writable SQL queries against a specific database using the :ref:`write SQL queries page <pages_execute_write>`, subject to table-level write permissions such as ``insert-row``, ``update-row`` and ``delete-row``. SQL functions are allowed and are not separately restricted by Datasette permissions.
 
 ``resource`` - ``datasette.resources.DatabaseResource(database)``
     ``database`` is the name of the database (string)

docs/pages.rst

@@ -62,6 +62,11 @@ The following tables are hidden by default:
 Queries
 =======
 
+.. _pages_custom_sql_queries:
+
+Custom SQL queries
+------------------
+
 The ``/database-name/-/query`` page can be used to execute an arbitrary SQL query against that database, if the :ref:`actions_execute_sql` permission is enabled. This query is passed as the ``?sql=`` query string parameter.
 
 This means you can link directly to a query by constructing the following URL:
@@ -72,6 +77,28 @@ Each configured :ref:`stored query <stored_queries>` has its own page, at ``/dat
 
 In both cases adding a ``.json`` extension to the URL will return the results as JSON.
 
+.. _pages_execute_write:
+
+Write SQL queries
+-----------------
+
+The ``/database-name/-/execute-write`` page can be used to execute SQL statements that write to a mutable database, if the :ref:`actions_execute_write_sql` permission is enabled.
+
+This page extracts named parameters from the SQL, shows the tables that will be affected and lists the permissions required before the query can be executed. It also includes templates for common ``INSERT``, ``UPDATE`` and ``DELETE`` statements.
+
+Datasette checks additional permissions based on the operations in the SQL. Row changes require the relevant table-level permissions such as :ref:`actions_insert_row`, :ref:`actions_update_row` and :ref:`actions_delete_row`; reads from source tables require :ref:`actions_view_table`; and schema changes require permissions such as :ref:`actions_create_table`, :ref:`actions_alter_table` or :ref:`actions_drop_table`.
+
+Use the :ref:`ExecuteWriteView` JSON API to execute writable SQL programmatically.
+
+.. _pages_stored_query_browser:
+
+Stored query browsers
+---------------------
+
+The ``/-/queries`` page lists stored queries across every database visible to the current actor. The ``/database-name/-/queries`` page lists stored queries for a single database.
+
+These pages support search, pagination and filters for read-only or writable queries and private or public queries. Adding a ``.json`` extension to either URL returns the same list as JSON.
+
 .. _TableView:
 
 Table

docs/sql_queries.rst

@@ -7,6 +7,8 @@ Datasette treats SQLite database files as read-only and immutable. This means it
 
 The easiest way to execute custom SQL against Datasette is through the web UI. The database index page includes a SQL editor that lets you run any SELECT query you like. You can also construct queries using the filter interface on the tables page, then click "View and edit SQL" to open that query in the custom SQL editor.
 
+For mutable databases, actors with the appropriate permissions can use the :ref:`write SQL page <pages_execute_write>` to execute SQL statements that insert, update or delete rows.
+
 Note that this interface is only available if the :ref:`actions_execute_sql` permission is allowed. See :ref:`authentication_permissions_execute_sql`.
 
 Any Datasette SQL query is reflected in the URL of the page, allowing you to bookmark them, share them with others and navigate through previous queries using your browser back button.