Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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-tils` 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!"