From 169ee5d710b58d0d53a0c14486a2c1c4c8987e86 Mon Sep 17 00:00:00 2001 From: Alex Garcia Date: Mon, 5 Aug 2024 10:35:38 -0700 Subject: [PATCH] Initial upgrade guide for v0.XX to v1 --- docs/index.rst | 1 + docs/internals.rst | 122 ++++++++++++++++++++++++++++++++++++++ docs/upgrade_guide_v1.rst | 91 ++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+) create mode 100644 docs/upgrade_guide_v1.rst diff --git a/docs/index.rst b/docs/index.rst index e3036618..bf1bc085 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,5 +65,6 @@ Contents testing_plugins internals events + upgrade_guide_v1 contributing changelog diff --git a/docs/internals.rst b/docs/internals.rst index 38e66a57..0eb95e89 100644 --- a/docs/internals.rst +++ b/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 `. + +.. _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 `. + +.. _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 `. + +.. _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 `. + +.. _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 `. + +.. _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 `. + +.. _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 `. + + +.. _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 `. + + +.. _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 `. + + + .. _datasette_add_database: .add_database(db, name=None, route=None) diff --git a/docs/upgrade_guide_v1.rst b/docs/upgrade_guide_v1.rst new file mode 100644 index 00000000..90024ff5 --- /dev/null +++ b/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() ` and :ref:`set_instance_metadata() ` +- :ref:`get_database_metadata() ` and :ref:`set_database_metadata() ` +- :ref:`get_resource_metadata() ` and :ref:`set_resource_metadata() ` +- :ref:`get_column_metadata() ` and :ref:`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() ` +- :ref:`get_database_metadata() ` +- :ref:`get_resource_metadata() ` +- :ref:`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.