SPI overview

Trino uses a plugin architecture to extend its capabilities and integrate with various data sources and other systems. Plugins must implement the interfaces and override methods defined by the Service Provider Interface (SPI).

General user information about plugins is available in the Plugin documentation, and specific details are documented in dedicated pages about each plugin.

This section details plugin development including specific pages for capabilities of different plugins. A custom plugin enables you to add further features to Trino, such as a connector for another data source.

Code

The SPI source can be found in the core/trino-spi directory in the Trino source tree.

Plugin metadata

Each plugin identifies an entry point: an implementation of the Plugin interface. This class name is provided to Trino via the standard Java ServiceLoader interface: the classpath contains a resource file named io.trino.spi.Plugin in the META-INF/services directory. The content of this file is a single line listing the name of the plugin class:

com.example.plugin.ExamplePlugin

For a built-in plugin that is included in the Trino source code, this resource file is created whenever the pom.xml file of a plugin contains the following line:

<packaging>trino-plugin</packaging>

Plugin

The Plugin interface is a good starting place for developers looking to understand the Trino SPI. It contains access methods to retrieve various classes that a Plugin can provide. For example, the getConnectorFactories() method is a top-level function that Trino calls to retrieve a ConnectorFactory when Trino is ready to create an instance of a connector to back a catalog. There are similar methods for Type, ParametricType, Function, SystemAccessControl, and EventListenerFactory objects.

Building plugins via Maven

Plugins depend on the SPI from Trino:

<dependency>
    <groupId>io.trino</groupId>
    <artifactId>trino-spi</artifactId>
    <scope>provided</scope>
</dependency>

The plugin uses the Maven provided scope because Trino provides the classes from the SPI at runtime and thus the plugin should not include them in the plugin assembly.

There are a few other dependencies that are provided by Trino, including Slice and Jackson annotations. In particular, Jackson is used for serializing connector handles and thus plugins must use the annotations version provided by Trino.

All other dependencies are based on what the plugin needs for its own implementation. Plugins are loaded in a separate class loader to provide isolation and to allow plugins to use a different version of a library that Trino uses internally.

For an example pom.xml file, see the example HTTP connector in the plugin/trino-example-http directory in the Trino source tree.

Deploying a custom plugin

Trino plugins must use the trino-plugin Maven packaging type provided by the trino-maven-plugin. Building a plugin generates the required service descriptor and invokes Provisio to create a ZIP file in the target directory. The file contains the plugin JAR and all its dependencies as JAR files, and is suitable for plugin installation.

Compatibility

Successful download, installation, and use of a plugin depends on compatibility of the plugin with the target Trino cluster. Full compatibility is only guaranteed when using the same Trino version used for the plugin build and the deployment, and therefore using the same version is recommended.

For example, a Trino plugin compiled for Trino 470 may not work with older or newer versions of Trino such as Trino 430 or Trino 490. This is specifically important when installing plugins from other projects, vendors, or your custom development.

Trino plugins implement the SPI, which may change with every Trino release. There are no runtime checks for SPI compatibility by default, and it is up to the plugin author to verify compatibility using runtime testing.

If the source code of a plugin is available, you can confirm the Trino version by inspecting the pom.xml. A plugin must declare a dependency to the SPI, and therefore compatibility with the Trino release specified in the version tag:

<dependency>
    <groupId>io.trino</groupId>
    <artifactId>trino-spi</artifactId>
    <version>470</version>
    <scope>provided</scope>
</dependency>

A good practice for plugins is to use a property for the version value, which is then declared elsewhere in the pom.xml:

...
<dep.trino.version>470</dep.trino.version>
...
<dependency>
    <groupId>io.trino</groupId>
    <artifactId>trino-spi</artifactId>
    <version>${dep.trino.version}</version>
    <scope>provided</scope>
</dependency>