remote/datasette
1
0
Fork 0
mirror of https://github.com/simonw/datasette.git synced 2026-09-11 19:14:07 +02:00
Code Issues Projects Releases Packages Wiki Activity
datasette/docs/events.md
Alex Garcia c6bbcc3298 Add add-database and remove-database lifecycle events 
Fire plugin-visible events from Datasette.add_database() and
.remove_database() so plugins can react to databases being attached or
detached at runtime. Dispatch is best-effort fire-and-forget: events only
fire when startup has completed and an event loop is running, and
remove-database fires after close() so queued writes are flushed before
listeners run.

Motivating consumer is datasette-litestream, which needs to register newly
attached databases with its replication daemon.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-04 14:43:20 -07:00

1.6 KiB
Raw Permalink Blame History

(events)=

Events

Datasette includes a mechanism for tracking events that occur while the software is running. This is primarily intended to be used by plugins, which can both trigger events and listen for events.

The core Datasette application triggers events when certain things happen. This page describes those events.

Note that these events will not fire for changes made to a SQLite database by a process other than Datasette itself.

Plugins can listen for events using the {ref}plugin_hook_track_event plugin hook, which will be called with instances of the following classes - or additional classes {ref}registered by other plugins <plugin_hook_register_events>.

Delivery guarantees for database lifecycle events

The add-database and remove-database events have some specific delivery characteristics:

  • Delivery is asynchronous. Listeners run shortly after the change, not before the triggering add_database() or remove_database() call returns.
  • These events fire only for changes made at runtime - while an event loop is running, after Datasette's startup has completed. Databases attached while the instance is starting up do not produce events: plugins that need to see those should iterate over datasette.databases in their own {ref}plugin_hook_startup hook.
  • Rapid successive changes involving the same database name may reach listeners interleaved. Listeners should tolerate events arriving out of order.
  • event.actor is None for programmatic calls made by Datasette itself or by plugins.
.. automodule:: datasette.events
    :members:
    :exclude-members: Event