Plugins

sqlite-utils supports plugins, which can be used to add extra features to the software.

Plugins can add new commands, for example sqlite-utils some-command ...

Plugins can be installed using the sqlite-utils install command:

sqlite-utils install sqlite-utils-name-of-plugin

You can see a JSON list of plugins that have been installed by running this:

sqlite-utils plugins

Plugin hooks such as prepare_connection(conn) affect each instance of the Database class. You can opt-out of these plugins by creating that class instance like so:

db = Database(memory=True, execute_plugins=False)

Building a plugin

Plugins are created in a directory named after the plugin. To create a “hello world” plugin, first create a hello-world directory:

mkdir hello-world
cd hello-world

In that folder create two files. The first is a pyproject.toml file describing the plugin:

[project]
name = "sqlite-utils-hello-world"
version = "0.1"

[project.entry-points.sqlite_utils]
hello_world = "sqlite_utils_hello_world"

The [project.entry-points.sqlite_utils] section tells sqlite-utils which module to load when executing the plugin.

Then create sqlite_utils_hello_world.py with the following content:

import click
import sqlite_utils

@sqlite_utils.hookimpl
def register_commands(cli):
    @cli.command()
    def hello_world():
        "Say hello world"
        click.echo("Hello world!")

Install the plugin in “editable” mode - so you can make changes to the code and have them picked up instantly by sqlite-utils - like this:

sqlite-utils install -e .

Or pass the path to your plugin directory:

sqlite-utils install -e /dev/sqlite-utils-hello-world

Now, running this should execute your new command:

sqlite-utils hello-world

Your command will also be listed in the output of sqlite-utils --help.

See the LLM plugin documentation for tips on distributing your plugin.

Plugin hooks

Plugin hooks allow sqlite-utils to be customized.

register_commands(cli)

This hook can be used to register additional commands with the sqlite-utils CLI. It is called with the cli object, which is a click.Group instance.

Example implementation:

import click
import sqlite_utils

@sqlite_utils.hookimpl
def register_commands(cli):
    @cli.command()
    def hello_world():
        "Say hello world"
        click.echo("Hello world!")

prepare_connection(conn)

This hook is called when a new SQLite database connection is created. You can use it to register custom SQL functions, aggregates and collations. For example:

import sqlite_utils

@sqlite_utils.hookimpl
def prepare_connection(conn):
    conn.create_function(
        "hello", 1, lambda name: f"Hello, {name}!"
    )

This registers a SQL function called hello which takes a single argument and can be called like this:

select hello("world"); -- "Hello, world!"