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

> Learn to add a new database plugin to Chat2DB by implementing the IPlugin SPI. This guide covers DBConfig, Metadata, and DBManager implementation for seamless integration.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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.

```xml
<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.

```java
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:

```java
@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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/pom.xml) located at [`chat2db-community-server/chat2db-community-plugins/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-plugins/pom.xml):

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

```

Ensure your module's [`pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/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:

```java
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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-plugins/chat2db-community-xugudb/src/main/java/ai/chat2db/plugin/xugudb/XUGUDBSyntaxPlugin.java).

## Code Examples

### Complete Plugin Skeleton

```java
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
<?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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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.