Skip to content
Browse files

.add_database() and .remove_database() methods, refs #671

Also made a start on the Datasette class documentation, refs #576
  • Loading branch information
simonw committed Feb 14, 2020
1 parent cf5f438 commit 3ffb8f3b98252531d11897fd431711e9b8045ace
Showing with 60 additions and 6 deletions.
  1. +7 −1 datasette/
  2. +43 −0 docs/datasette.rst
  3. +1 −0 docs/index.rst
  4. +9 −5 docs/plugins.rst
@@ -180,7 +180,7 @@ def __init__(
db = Database(self, path, is_mutable=is_mutable, is_memory=is_memory)
if in self.databases:
raise Exception("Multiple files with same stem: {}".format(
self.databases[] = db
self.add_database(, db)
self.cache_headers = cache_headers
self.cors = cors
self._metadata = metadata or {}
@@ -210,6 +210,12 @@ def __init__(
# Plugin already registered

def add_database(self, name, db):
self.databases[name] = db

def remove_database(self, name):

async def run_sanity_checks(self):
# Only one check right now, for Spatialite
for database_name, database in self.databases.items():
@@ -0,0 +1,43 @@
.. _datasette:

Datasette class

Many of Datasette's :ref:`plugin_hooks` pass a ``datasette`` object to the plugin as an argument.

This object is an instance of the ``Datasette`` class. That class currently has a large number of methods on it, but it should not be considered stable (at least until Datasette 1.0) with the exception of the methods that are documented on this page.

.add_database(name, db)

The ``datasette.add_database(name, db)`` method lets you add a new database to the current Datasette instance. This database will then be served at URL path that matches the ``name`` parameter, e.g. ``/mynewdb/``.

The ``db`` parameter should be an instance of the ``datasette.database.Database`` class. For example:

.. code-block:: python
from datasette.database import Database
datasette.add_database("my-new-database", Database(
This will add a mutable database from the provided file path.

The ``Database()`` constructor takes four arguments: the first is the ``datasette`` instance you are attaching to, the second is a ``path=``, then ``is_mutable`` and ``is_memory`` are both optional arguments.

Use ``is_mutable`` if it is possible that updates will be made to that database - otherwise Datasette will open it in immutable mode and any changes could cause undesired behavior.

Use ``is_memory`` if the connection is to an in-memory SQLite database.


This removes a database that has been previously added. ``name=`` is the unique name of that database, also used in the URL for it.

.plugin_config(plugin_name, database=None, table=None)

This method lets you read plugin configuration values that were set in ``metadata.json``. See :ref:`plugins_plugin_config` for full details.
@@ -34,6 +34,7 @@ Contents

@@ -278,6 +278,8 @@ If you are publishing your data using the :ref:`datasette publish <cli_publish>`
--plugin-secret datasette-auth-github client_id your_client_id \
--plugin-secret datasette-auth-github client_secret your_client_secret

.. _plugins_plugin_config:

Writing plugins that accept configuration

@@ -320,6 +322,8 @@ The plugin configuration could also be set at the top level of ``metadata.json``

Now that ``datasette-cluster-map`` plugin configuration will apply to every table in every database.

.. _plugin_hooks:

Plugin hooks

@@ -399,7 +403,7 @@ extra_css_urls(template, database, table, datasette)
``table`` - string or None
The name of the table

``datasette`` - Datasette instance
``datasette`` - :ref:`datasette`
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``

Return a list of extra CSS URLs that should be included on the page. These can
@@ -535,7 +539,7 @@ Lets you customize the display of values within table cells in the HTML table vi
``database`` - string
The name of the database

``datasette`` - Datasette instance
``datasette`` - :ref:`datasette`
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``

If your hook returns ``None``, it will be ignored. Use this to indicate that your hook is not able to custom render this particular value.
@@ -605,7 +609,7 @@ Extra JavaScript to be added to a ``<script>`` block at the end of the ``<body>`
``view_name`` - string
The name of the view being displayed. (`index`, `database`, `table`, and `row` are the most important ones.)

``datasette`` - Datasette instance
``datasette`` - :ref:`datasette`
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``

The ``template``, ``database`` and ``table`` options can be used to return different code depending on which template is being rendered and which database or table are being processed.
@@ -637,7 +641,7 @@ Extra template variables that should be made available in the rendered template
``request`` - object
The current HTTP request object. ``request.scope`` provides access to the ASGI scope.

``datasette`` - Datasette instance
``datasette`` - :ref:`datasette`
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``

This hook can return one of three different types:
@@ -682,7 +686,7 @@ You can then use the new function in a template like so::

``datasette`` - Datasette instance
``datasette`` - :ref:`datasette`
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``

Allows the plugin to register a new output renderer, to output data in a custom format. The hook function should return a dictionary, or a list of dictionaries, which contain the file extension you want to handle and a callback function:

0 comments on commit 3ffb8f3

Please sign in to comment.
You can’t perform that action at this time.