CrateDB implements a plugin loading infrastructure making it possible to develop plugins for CrateDB.

A plugin must at least:

  • implement the io.crate.Plugin interface
  • register its implementation at META-INF/services/io.crate.Plugin so CrateDB plugin load can find it.

See our CrateDB example plugin for details about that.

Table of Contents

Plugin CrateDB Dependency

In order to develop a plugin against a CrateDB release, a dependency to the CrateDB’s server libraries must be set up.


Define bintray (jCenter) repository:

repositories {

Add CrateDB to compile dependencies:

dependencies {
    compile 'io.crate:crate:<VERSION>'


Add bintray (jCenter) as a repository to your maven settings.xml:



Add CrateDB as a dependency:


Plugin Loading

Loading of plugins is done by CrateDB for searching all class path element resources for a META-INF/services/io.crate.Plugin file.

Inside this file just one line is allowed defining the full qualified class name which is implementing the Plugin interface. This is almost the same like you may know from Java’s ServiceLoader.

Constructor with Settings argument

CrateDB passes a Settings instance to the plugin implementation constructor if such a constructor exists. Otherwise an empty constructor is used. By using the Settings instance, a plugin can process existing settings and/or implement it’s own custom setting entries.

The CrateDB example plugin makes use of that to implement a custom setting.

Plugin Interface

CrateDB uses Guice module binding concept and so does a plugin. As described at the io.crate.Plugin interface, a plugin can load serveral module types by implementing relevant methods:

  • lifecycle services
  • node level modules
  • index level modules
  • shard level modules

Besides of implementing own modules, a plugin can also listen to other’s module bindings. For example, as our CrateDB example plugin does, to the binding of the ScalarFunctionModule in order to register scalar functions. This can be achieved by implementing a related onModule(AnyModule module) method:

public void onModule(ScalarFunctionModule module) {

Again, checkout the CrateDB example plugin to see this in action.

AbstractPlugin Class

A good start for developing an own plugin is to extend the implementation from io.crate.plugin.AbstractPlugin, which already implements all methods required by the Plugin interface. So one must just overwrite the relevant ones:

public class MyAwesomePlugin extends AbstractPlugin {

    public String name() {
        return "myawesome-plugin";

    public String description() {
        return "A really awesome CrateDB plugin";

    public Settings additionalSettings() {
        Settings.Builder builder = Settings.builder();
        // This plugin enables ``stats`` by default
        builder.put("stats.enabled", true);

Methods name and description must be always implemented, anything else is already implemented by the abstract plugin class.

Installing a Plugin

Installing a plugin is simply done by copying the plugin’s JAR file(s) somewhere into the class path or to one of the following places:

  • <CRATE_HOME>/plugins/
  • <CRATE_HOME>/plugins/<SOME_PLUGIN_NAME>/lib/