Initial upgrade guide for v0.XX to v1

docs/index.rst

@@ -65,5 +65,6 @@ Contents
    testing_plugins
    internals
    events
+   upgrade_guide_v1
    contributing
    changelog

docs/internals.rst

@@ -516,6 +516,128 @@ Returns the specified database object. Raises a ``KeyError`` if the database doe
 
 Returns a database object for reading and writing to the private :ref:`internal database <internals_internal>`.
 
+
+.. _datasette_get_instance_metadata:
+
+await .get_instance_metadata(self)
+----------------------------------
+
+Returns metadata keys and values for the entire Datasette instance as a dictionary.
+Internally queries the ``datasette_metadata_instance_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+.. _datasette_get_database_metadata:
+
+await .get_database_metadata(self, database_name)
+------------------------------------------------------
+
+``database_name`` - string
+    The name of the database to query.
+
+Returns metadata keys and values for the specified database as a dictionary.
+Internally queries the ``datasette_metadata_database_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+.. _datasette_get_resource_metadata:
+
+await .get_resource_metadata(self, database_name, resource_name)
+--------------------------------------------------------------------------
+
+``database_name`` - string
+    The name of the database to query.
+``resource_name`` - string
+    The name of the resource (table, view, or canned query) inside ``database_name`` to query.
+
+Returns metadata keys and values for the specified "resource" as a dictionary.
+A "resource" in this context can be a table, view, or canned query.
+Internally queries the ``datasette_metadata_resource_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+.. _datasette_get_column_metadata:
+
+await .get_column_metadata(self, database_name, resource_name, column_name)
+------------------------------------------------------------------------------------------
+
+``database_name`` - string
+    The name of the database to query.
+``resource_name`` - string
+    The name of the resource (table, view, or canned query) inside ``database_name`` to query.
+``column_name`` - string
+    The name of the column inside ``resource_name`` to query.
+
+
+Returns metadata keys and values for the specified column, resource, and table as a dictionary.
+Internally queries the ``datasette_metadata_column_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+.. _datasette_set_instance_metadata:
+
+await .set_instance_metadata(self, key, value)
+--------------------------------------------------------
+
+``key`` - string
+    The metadata entry key to insert (ex ``title``, ``description``, etc.)
+``value`` - string
+    The value of the metadata entry to insert.
+
+Adds a new metadata entry for the entire Datasette instance.
+Any previous instance-level metadata entry with the same ``key`` will be overwritten.
+Internally upserts the value into the  the ``datasette_metadata_instance_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+.. _datasette_set_database_metadata:
+
+await .set_database_metadata(self, database_name, key, value)
+----------------------------------------------------------------------------
+
+``database_name`` - string
+    The database the metadata entry belongs to.
+``key`` - string
+    The metadata entry key to insert (ex ``title``, ``description``, etc.)
+``value`` - string
+    The value of the metadata entry to insert.
+
+Adds a new metadata entry for the specified database.
+Any previous database-level metadata entry with the same ``key`` will be overwritten.
+Internally upserts the value into the  the ``datasette_metadata_database_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+
+.. _datasette_set_resource_metadata:
+
+await .set_resource_metadata(self, database_name, resource_name, key, value)
+------------------------------------------------------------------------------------------------
+
+``database_name`` - string
+    The database the metadata entry belongs to.
+``resource_name`` - string
+    The resource (table, view, or canned query) the metadata entry belongs to.
+``key`` - string
+    The metadata entry key to insert (ex ``title``, ``description``, etc.)
+``value`` - string
+    The value of the metadata entry to insert.
+
+Adds a new metadata entry for the specified "resource".
+Any previous resource-level metadata entry with the same ``key`` will be overwritten.
+Internally upserts the value into the  the ``datasette_metadata_resource_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+
+.. _datasette_set_column_metadata:
+
+await .set_column_metadata(self, database_name, resource_name, column_name, key, value)
+------------------------------------------------------------------------------------------------------------------
+
+``database_name`` - string
+    The database the metadata entry belongs to.
+``resource_name`` - string
+    The resource (table, view, or canned query) the metadata entry belongs to.
+``column-name`` - string
+    The column the metadata entry belongs to.
+``key`` - string
+    The metadata entry key to insert (ex ``title``, ``description``, etc.)
+``value`` - string
+    The value of the metadata entry to insert.
+
+Adds a new metadata entry for the specified column.
+Any previous column-level metadata entry with the same ``key`` will be overwritten.
+Internally upserts the value into the  the ``datasette_metadata_column_entries`` table inside the :ref:`internal database <internals_internal>`.
+
+
+
 .. _datasette_add_database:
 
 .add_database(db, name=None, route=None)

docs/upgrade_guide_v1.rst

@@ -0,0 +1,91 @@
+.. upgrade_guide_v1:
+
+====================================
+ Datasette 0.X -> 1.0 Upgrade Guide
+====================================
+
+
+This document specifically reviews what breaking changes Datasette ``1.0`` has when upgrading from a ``0.XX`` version.
+For new features that ``1.0`` offers, see the [Changelog](https://docs.datasette.io/en/latest/changelog.html).
+
+
+Metadata changes
+================
+
+Metadata in Datasette.10 was completely revamped.
+There are a number of related breaking changes, from the ``metadata.yaml`` file to Python APIs that you'll need to consider when upgrading.
+
+``metadata.yaml`` split into ``datasette.yaml``
+-----------------------------------------------
+
+Before Datasette 1.0, the ``metadata.yaml`` file became a kitchen sink if a mix of metadata, configuration, and settings.
+Now ``metadata.yaml`` is strictly for metaata (ex title and descriptions of database and tables, licensing info, etc).
+
+
+Metadata "fallback" has been removed
+------------------------------------
+
+Certain keys in metadata like ``license`` used to "fallback" up the chain of ownership.
+For example, if you set an ``MIT`` to a database and a table within that database did not have a specified license,
+then that table would inherit an ``MIT`` license.
+
+This behavior has been removed in Datasette 1.0. Now license fields must be placed on all items, including individual databases and tables.
+
+The ``get_metadata()`` Plugin hook has been removed
+---------------------------------------------------
+
+As of Datasette ``1.0a14`` (2024-XX-XX), the ``get_metadata()`` hook has been deprecated.
+
+.. code-block:: python
+
+    # ❌ DEPRECATED in Datasette 1.0
+    @hookimpl
+    def get_metadata(datasette, key, database, table):
+        pass
+
+Instead, one should use the following methods on a Datasette class:
+
+- :ref:`get_instance_metadata() <datasette_get_instance_metadata>` and  :ref:`set_instance_metadata() <datasette_set_instance_metadata>`
+- :ref:`get_database_metadata() <datasette_get_database_metadata>` and  :ref:`set_database_metadata() <datasette_set_database_metadata>`
+- :ref:`get_resource_metadata() <datasette_get_resource_metadata>` and  :ref:`set_resource_metadata() <datasette_set_resource_metadata>`
+- :ref:`get_column_metadata() <datasette_get_column_metadata>` and  :ref:`set_column_metadata() <datasette_set_column_metadata>`
+
+The ``/metadata.json`` endpoint has been removed
+------------------------------------------------
+
+As of Datasette `1.0a14`, the root level ``/metadata.json`` endpoint has been removed.
+
+The ``metadata()`` method on the Datasette class has been removed
+-----------------------------------------------------------------
+
+As of Datasette ``1.0a14``, the ``.metadata()`` method on the Datasette Python API has been removed.
+
+Instead, one should use the following methods on a Datasette class:
+
+
+- :ref:`get_instance_metadata() <datasette_get_instance_metadata>`
+- :ref:`get_database_metadata() <datasette_get_database_metadata>`
+- :ref:`get_resource_metadata() <datasette_get_resource_metadata>`
+- :ref:`get_column_metadata() <datasette_get_column_metadata>`
+
+
+New endpoint for SQL queries
+============================
+
+Previously, if you wanted to run SQL code using the Datasette HTTP API, you could call an endpoint that looked like:
+
+::
+
+    # DEPRECATED: Older endpoint for Datasette 0.XX
+    curl http://localhost:8001/_memory?sql=select+123
+
+However, in Datasette 1.0, the endpoint was slightly changed to:
+
+::
+
+    # ✅ Datasette 1.0 and beyond
+    curl http://localhost:8001/_memory/-/query?sql=select+123
+
+Specifically, now there's a ``/-/query`` "action" that should be used.
+
+**This isn't a breaking change.** API calls to the older ``/database?sql=...`` endpoint will redirect to the new ``database/-/query?sql=...`` endpoint. However, documentations and example will use the new query endpoint, so it is recommended to use that instead.