# Understanding the Chat2DB Plugin Architecture and SPI: A Complete Guide

> Explore the Chat2DB plugin architecture and SPI. Discover how Java's SPI enables database support extensions without core code changes. Learn to integrate new databases easily.

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

---

**Chat2DB uses a modular Plugin Architecture based on Java's Service Provider Interface (SPI) that allows developers to add support for new databases without modifying the core codebase.**

The OtterMind/Chat2DB repository implements a contract‑first extensibility model where database‑specific logic is encapsulated in separate Maven modules. By leveraging Java's `ServiceLoader` mechanism and Spring dependency injection, the platform dynamically discovers and registers plugins at runtime, enabling plug‑and‑play support for diverse SQL and NoSQL systems.

## Core Components of the Chat2DB Plugin Architecture

### The SPI Module and Contract Interfaces

The **SPI module** (`chat2db-community-server/chat2db-community-spi`) defines the contracts that every database plugin must implement. These Java interfaces establish extension points for SQL syntax handling, metadata access, and execution services.

The two fundamental contracts are:

- **`IPlugin`** – The base interface that every plugin must implement. It declares the database name, version, and references to dialect‑specific services.
- **`ISqlSyntaxPlugin`** – Defines methods for SQL parsing, formatting, and auto‑completion specific to the target database grammar.

Additional granular interfaces like `IDbWorkspaceDataSourceService`, `IDbSqlExecutionService`, and `IDbMetaDataService` allow plugins to expose only the capabilities supported by their underlying database.

### ServiceLoader Discovery Mechanism

Chat2DB relies on Java’s built‑in **`ServiceLoader`** class to discover implementations at runtime. Each plugin module ships a service provider configuration file located at:

```

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

```

This file contains the fully‑qualified class name of the plugin implementation, enabling the JVM to locate and instantiate the plugin without explicit class loading code.

### Plugin Module Structure

Database plugins reside as separate Maven modules under `chat2db-community-plugins/`. Each module follows a consistent structure:

- **Plugin Class** – Implements `IPlugin` (e.g., `TiDBPlugin`, `MongoDBPlugin`, `XUGUDBPlugin`).
- **Syntax Plugin** – Implements `ISqlSyntaxPlugin` for dialect‑specific SQL operations.
- **Supporting Classes** – Parser, builder, metadata, and manager classes tailored to the specific database.

For example, the XuguDB plugin implementation lives 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), while the TiDB equivalent is located in the `chat2db-community-tidb` module.

## How the Chat2DB SPI Works: Step-by-Step

The plugin lifecycle follows a strict registration pattern managed by the Spring context:

1. **Define Contracts** – The SPI module declares interfaces in `chat2db-community-spi/src/main/java/ai/chat2db/spi/` that specify expected behavior for SQL syntax, metadata extraction, and query execution.

2. **Implement the Plugin** – Developers create a new Maven module under `chat2db-community-plugins` and implement `IPlugin` along with relevant service interfaces.

3. **Register via ServiceLoader** – The plugin JAR includes a `META-INF/services/ai.chat2db.spi.IPlugin` file listing the implementation class, allowing automatic discovery.

4. **Spring Wiring** – During application startup, Chat2DB scans the classpath for `IPlugin` services and registers each instance into a `PluginRegistry` (located in `chat2db-community-start`). The registry injects the appropriate beans into core domain services.

5. **Runtime Delegation** – When a user selects a datasource, the system looks up the corresponding plugin by dialect name and delegates all database‑specific operations—such as SQL building, metadata extraction, and DDL generation—to that plugin’s implementations.

## Implementing a Custom Database Plugin

Below is a complete skeleton demonstrating how to add support for a hypothetical **MyAwesomeDB** database.

First, create the main plugin class that implements `IPlugin`:

```java
package ai.chat2db.plugin.myawesome;

import ai.chat2db.spi.IPlugin;
import org.springframework.stereotype.Component;

@Component
public class MyAwesomeDBPlugin implements IPlugin {
    @Override
    public String getName() {
        return "myawesome";
    }

    @Override
    public String getVersion() {
        return "1.0.0";
    }
    
    // Optional: expose syntax plugin class
    // @Override
    // public Class<? extends ISqlSyntaxPlugin> getSyntaxPluginClass() { ... }
}

```

Next, implement the SQL syntax contract for parsing and completion:

```java
package ai.chat2db.plugin.myawesome;

import ai.chat2db.spi.ISqlSyntaxPlugin;
import org.springframework.stereotype.Component;

@Component
public class MyAwesomeSQLSyntaxPlugin implements ISqlSyntaxPlugin {
    // Implement parse, complete, format methods here
}

```

Create the ServiceLoader registration file at `src/main/resources/META-INF/services/ai.chat2db.spi.IPlugin`:

```text
ai.chat2db.plugin.myawesome.MyAwesomeDBPlugin

```

Finally, register the module in the parent POM at [`chat2db-community-plugins/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-plugins/pom.xml):

```xml
<module>chat2db-community-myawesomedb</module>

```

When the application restarts, `MyAwesomeDBPlugin` will be discovered automatically and integrated into the core workflow.

## Key Extension Points and Services

The SPI defines numerous granular interfaces that plugins can implement based on target database capabilities:

- **`IDbMetaDataService`** – For schema introspection and table metadata retrieval.
- **`IDbSqlExecutionService`** – For executing queries and managing result sets.
- **`IDbWorkspaceDataSourceService`** – For connection pooling and workspace‑level datasource management.

Notable reference implementations include:

- **`XUGUDBPlugin`** ([`chat2db-community-xugudb/src/main/java/ai/chat2db/plugin/xugudb/XUGUDBPlugin.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-xugudb/src/main/java/ai/chat2db/plugin/xugudb/XUGUDBPlugin.java)) – Demonstrates traditional relational database integration.
- **`MongoDBPlugin`** ([`chat2db-community-mongodb/src/main/java/ai/chat2db/plugin/mongodb/MongodbPlugin.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-mongodb/src/main/java/ai/chat2db/plugin/mongodb/MongodbPlugin.java)) – Shows NoSQL document store adaptation.
- **`TiDBPlugin`** ([`chat2db-community-tidb/src/main/java/ai/chat2db/plugin/tidb/TidbPlugin.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-tidb/src/main/java/ai/chat2db/plugin/tidb/TidbPlugin.java)) – Illustrates distributed SQL engine support.

## Summary

- Chat2DB implements a **Java SPI‑based plugin architecture** that separates database‑specific logic from the core application.
- The **`IPlugin`** and **`ISqlSyntaxPlugin`** interfaces in `chat2db-community-spi` define the mandatory contracts for all plugins.
- **ServiceLoader** discovers plugins via `META-INF/services/ai.chat2db.spi.IPlugin` metadata files inside each plugin JAR.
- Plugins reside as independent Maven modules under `chat2db-community-plugins`, with each module encapsulating one database dialect.
- The **`PluginRegistry`** in `chat2db-community-start` handles Spring wiring and lifecycle management during application startup.

## Frequently Asked Questions

### What is the difference between Chat2DB's SPI and a traditional API?

The **SPI (Service Provider Interface)** is designed for extensibility by third‑party developers, whereas a traditional API is consumed by client code. In Chat2DB, the SPI defines contracts in the `chat2db-community-spi` module that plugin authors implement, while the core application acts as the consumer of those implementations. This inversion of control allows new databases to be added without modifying the core codebase.

### How does Chat2DB discover plugins at runtime?

Chat2DB uses Java’s **`ServiceLoader`** mechanism. When the application starts, the `PluginRegistry` scans the classpath for JARs containing a file at `META-INF/services/ai.chat2db.spi.IPlugin`. This file lists the fully‑qualified class name of the plugin implementation, which Spring then instantiates and registers as a bean.

### Can I extend Chat2DB to support a proprietary or internal database?

Yes. By creating a new Maven module under `chat2db-community-plugins` and implementing the `IPlugin` interface and relevant service contracts (such as `ISqlSyntaxPlugin` or `IDbMetaDataService`), you can integrate any JDBC‑compatible database. The modular design ensures your proprietary logic remains isolated while inheriting Chat2DB’s core UI and connection management features.

### What files must be present in a Chat2DB plugin JAR for successful registration?

A valid plugin JAR must contain:
1. An implementation class of `ai.chat2db.spi.IPlugin` (annotated with `@Component`).
2. A service declaration file at `META-INF/services/ai.chat2db.spi.IPlugin` containing the implementation’s fully‑qualified class name.
3. Spring‑managed components that implement the required SPI interfaces for your target database’s capabilities.