How to Add a New Database Plugin to Chat2DB: A Complete SPI Implementation Guide

To add a new database plugin to Chat2DB, implement the IPlugin Service Provider Interface (SPI), provide concrete implementations for DBConfig, Metadata, and DBManager, and register your plugin class in META-INF/services/ai.chat2db.spi.IPlugin so the framework can auto-load it at runtime.

Chat2DB uses a modular SPI architecture located in the OtterMind/Chat2DB repository to support multiple databases without hard-coding driver-specific logic into the core application. By following the standard Java ServiceLoader pattern, you can extend Chat2DB to support any JDBC-compatible database by creating a standalone Maven module and registering it via the plugin discovery mechanism.

Step-by-Step Guide to Adding a Database Plugin

1. Create the Maven Module Structure

Create a new Maven module under chat2db-community-server/chat2db-community-plugins. Name it following the convention chat2db-community-{dbname} (for example, chat2db-community-mydb). This module must depend on the chat2db-community-spi artifact to access the required interfaces.

<dependency>
    <groupId>ai.chat2db</groupId>
    <artifactId>chat2db-community-spi</artifactId>
    <version>${project.version}</version>
</dependency>

2. Implement the IPlugin Interface

Create a class that implements ai.chat2db.spi.IPlugin. This class serves as the entry point for Chat2DB to retrieve database-specific configurations and managers.

package ai.chat2db.plugin.mydb;

import ai.chat2db.spi.IPlugin;
import ai.chat2db.spi.DBConfig;
import ai.chat2db.spi.Metadata;
import ai.chat2db.spi.DBManager;

public class MyDBPlugin implements IPlugin {

    @Override
    public DBConfig getDBConfig() {
        return new DBConfig()
                .setDbType("MYDB")
                .setName("MyCustomDB")
                .setJdbcDriver("com.mydb.jdbc.Driver")
                .setDefaultPort(5432);
    }

    @Override
    public Metadata getMetaData() {
        return new MyDBMetadata();
    }

    @Override
    public DBManager getDBManager() {
        return new MyDBManager();
    }
}

3. Provide Database-Specific Services

You must implement three core SPI contracts to handle connection metadata, schema extraction, and SQL execution:

• DBConfig: Defines JDBC URLs, default ports, supported features, and driver class names.
• Metadata: Implements schema introspection methods (tables, columns, indexes) via ai.chat2db.spi.Metadata.
• DBManager: Handles DDL/DML execution and connection management via ai.chat2db.spi.DBManager.

Optionally, if your database uses non-standard SQL syntax, implement ISqlSyntaxPlugin to provide custom parsing and building logic:

@Override
public ISqlSyntaxPlugin getSqlSyntaxPlugin() {
    return new MyDBSyntaxPlugin(); // implements ai.chat2db.spi.ISqlSyntaxPlugin
}

4. Register the Plugin via SPI

In src/main/resources/Meta-INF/services/ai.chat2db.spi.IPlugin, add the fully-qualified class name of your IPlugin implementation:

ai.chat2db.plugin.mydb.MyDBPlugin

The Chat2DBContext class scans these registration files at startup to build the plugin map. According to the source code in chat2db-community-server/chat2db-community-spi/src/main/java/ai/chat2db/spi/Chat2DBContext.java, the framework uses the Java ServiceLoader to instantiate registered plugins and maps them by the DBConfig.getDbType() value.

5. Wire the Module into the Reactor Build

Add your new module to the parent pom.xml located at chat2db-community-server/chat2db-community-plugins/pom.xml:

<modules>
    <module>chat2db-community-mysql</module>
    <module>chat2db-community-postgresql</module>
    <module>chat2db-community-mydb</module>
</modules>

Ensure your module's pom.xml inherits from the chat2db-community parent to maintain consistent versioning and dependency management.

6. Verify with Unit Tests

Write tests to verify that Chat2DB correctly loads your plugin. Test the registration by querying the context:

import ai.chat2db.spi.Chat2DBContext;
import ai.chat2db.spi.IPlugin;
import static org.junit.Assert.*;

public class MyDBPluginTest {

    @Test
    public void shouldRegisterInContext() {
        IPlugin plugin = Chat2DBContext.getPlugin("MYDB");
        assertNotNull("Plugin should be loaded by SPI", plugin);
        assertEquals("MYDB", plugin.getDBConfig().getDbType());
    }
}

Key Interfaces and Classes

Understanding these core files in the Chat2DB source code ensures your implementation aligns with the framework's expectations:

• IPlugin: The primary SPI entry point located at chat2db-community-server/chat2db-community-spi/src/main/java/ai/chat2db/spi/IPlugin.java.
• Chat2DBContext: The runtime registry that loads plugins via ServiceLoader, found at chat2db-community-server/chat2db-community-spi/src/main/java/ai/chat2db/spi/Chat2DBContext.java.
• Example Implementation: The XUGUDBPlugin class demonstrates a complete working plugin at chat2db-community-server/chat2db-community-plugins/chat2db-community-xugudb/src/main/java/ai/chat2db/plugin/xugudb/XUGUDBPlugin.java.
• Syntax Plugin Example: XUGUDBSyntaxPlugin shows optional SQL syntax customization at chat2db-community-server/chat2db-community-plugins/chat2db-community-xugudb/src/main/java/ai/chat2db/plugin/xugudb/XUGUDBSyntaxPlugin.java.

Code Examples

Complete Plugin Skeleton

package ai.chat2db.plugin.mydb;

import ai.chat2db.spi.*;

public class MyDBPlugin implements IPlugin {

    @Override
    public DBConfig getDBConfig() {
        return new DBConfig()
                .setDbType("MYDB")
                .setJdbcDriver("com.mydb.Driver")
                .setDefaultPort(1234)
                .setSupportSchema(true);
    }

    @Override
    public Metadata getMetaData() {
        return new MyDBMetadata();
    }

    @Override
    public DBManager getDBManager() {
        return new MyDBManager();
    }

    @Override
    public ISqlSyntaxPlugin getSqlSyntaxPlugin() {
        return new MyDBSyntaxPlugin();
    }
}

SPI Registration File

Create src/main/resources/META-INF/services/ai.chat2db.spi.IPlugin:

ai.chat2db.plugin.mydb.MyDBPlugin

Module POM Configuration

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>ai.chat2db</groupId>
        <artifactId>chat2db-community</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <relativePath>../../pom.xml</relativePath>
    </parent>
    
    <artifactId>chat2db-community-mydb</artifactId>
    <packaging>jar</packaging>
    <name>Chat2DB MyDB Plugin</name>
    
    <dependencies>
        <dependency>
            <groupId>ai.chat2db</groupId>
            <artifactId>chat2db-community-spi</artifactId>
        </dependency>
        <dependency>
            <groupId>com.mydb</groupId>
            <artifactId>mydb-jdbc-driver</artifactId>
            <version>1.0</version>
        </dependency>
    </dependencies>
</project>

Summary

• Implement IPlugin to define your database type, configuration, and core services.
• Provide concrete classes for DBConfig, Metadata, and DBManager to handle connections, schema introspection, and SQL execution.
• Register via SPI by adding your fully-qualified class name to META-INF/services/ai.chat2db.spi.IPlugin.
• Add your module to chat2db-community-plugins/pom.xml to include it in the build.
• Reference existing plugins like XUGUDBPlugin for implementation patterns and file structure.

Frequently Asked Questions

What is the Chat2DB SPI and how does it load plugins?

The Service Provider Interface (SPI) is a Java standard that allows Chat2DB to discover database implementations at runtime without compile-time dependencies. The Chat2DBContext class uses ServiceLoader.load(IPlugin.class) to scan the classpath for files named META-INF/services/ai.chat2db.spi.IPlugin, instantiates each listed class, and registers them in an internal map keyed by database type.

Do I need to modify core Chat2DB code to add a database?

No. You only need to create a new Maven module implementing the required interfaces and register it via the SPI file. The core application in chat2db-community-server automatically picks up new plugins from the classpath at startup, provided they are included in the final assembly or classpath.

Can I add a plugin for a non-JDBC database?

While the Chat2DB SPI architecture is designed around JDBC-compatible databases, you can technically implement the DBManager and Metadata interfaces to wrap any data source. However, you must still provide a DBConfig with a JDBC-style configuration, and the UI may expect standard JDBC metadata patterns. For true non-JDBC sources, you may need to implement custom proxy classes within your plugin.

How do I troubleshoot if my plugin is not detected?

First, verify that your JAR contains the file META-INF/services/ai.chat2db.spi.IPlugin with the correct fully-qualified class name. Second, ensure your module is listed in chat2db-community-plugins/pom.xml and that the built JAR is present in the runtime classpath. Finally, check logs for ServiceLoader errors or verify programmatically by calling Chat2DBContext.getPlugin("YOUR_DB_TYPE") to see if it returns null.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}