JDBC

The legacy modules agentscope-extensions-mysql, agentscope-extensions-postgresql, agentscope-extensions-skill-mysql-repository, and agentscope-extensions-skill-postgresql-repository are deprecated and replaced by this module. See migration below.

​

Dependency

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-jdbc</artifactId>
    <version>${agentscope.version}</version>
</dependency>

​

One-Line Setup

import io.agentscope.extensions.jdbc.JdbcDistributedStore;

DataSource dataSource = ...;  // HikariCP, Druid, etc.
DistributedStore store = JdbcDistributedStore.create(dataSource);

HarnessAgent agent = HarnessAgent.builder()
    .distributedStore(store)
    .filesystem(new RemoteFilesystemSpec()
            .isolationScope(IsolationScope.USER))
    .build();

AbstractJdbcDialect dialect = AbstractJdbcDialect.from(dataSource)
    .tablePrefix("myapp_")            // default: agentscope_
    .build();

DistributedStore store = JdbcDistributedStore.create(dataSource, dialect);

AbstractJdbcDialect dialect = AbstractJdbcDialect.from(dataSource)
    .enableBaseTables(true)      // default: on — store, sessions, snapshots
    .enableSkillTables(true)     // default: off — opt in to add the skill tables
    .build();                    // creates agentscope_skills / agentscope_skill_resources

​

Components Provided

​

1. JdbcAgentStateStore

import io.agentscope.extensions.jdbc.dialect.AbstractJdbcDialect;
import io.agentscope.extensions.jdbc.state.JdbcAgentStateStore;

AbstractJdbcDialect dialect = AbstractJdbcDialect.from(dataSource).build();  // schema creation + validation happen here

AgentStateStore store = new JdbcAgentStateStore(dataSource, dialect);

​

2. JdbcStore (BaseStore)

import io.agentscope.extensions.jdbc.store.JdbcStore;

BaseStore store = JdbcStore.builder(dataSource)
    .dialect(dialect)
    .build();

​

3. JdbcSnapshotSpec

import io.agentscope.extensions.jdbc.snapshot.JdbcSnapshotSpec;

SandboxSnapshotSpec spec = new JdbcSnapshotSpec(dataSource, dialect);

​

4. JdbcSandboxExecutionGuard

• MySQL: native GET_LOCK() / RELEASE_LOCK(). The lock is tied to the JDBC connection and auto-released on connection close; lock names longer than 64 characters are hashed automatically.
• PostgreSQL / H2 / SQLite: a portable lock on the agentscope_distributed_locks table, with no database-specific syntax.

import io.agentscope.extensions.jdbc.sandbox.JdbcSandboxExecutionGuard;

SandboxExecutionGuard guard = JdbcSandboxExecutionGuard.builder(dialect)
    .keyPrefix("myapp:lock:")
    .lockTimeout(Duration.ofMinutes(30))
    .build();

Note: MySQL named locks are server-level, not database-level. Use a unique keyPrefix when sharing a MySQL instance.

​

5. JdbcAgentSkillRepository

import io.agentscope.core.skill.repository.AgentSkillRepository;
import io.agentscope.extensions.jdbc.skill.JdbcAgentSkillRepository;

AbstractJdbcDialect dialect = AbstractJdbcDialect.from(dataSource)
    .enableSkillTables(true)
    .build();

AgentSkillRepository repo = new JdbcAgentSkillRepository(dataSource, dialect);

• metadata_json is a required column. A table from before the column existed fails startup validation with the reference DDL; add the column as the error suggests and restart — the framework never alters existing tables.
• delete removes a skill’s resources explicitly before the row itself, so it behaves the same on SQLite, where the cascade only fires with PRAGMA foreign_keys on. Resource paths must be relative without .. — anything escaping the skill directory is rejected on save, and rows read back from the table are validated the same way.

​

Migrating from Legacy Modules

• Tables created by the current legacy modules already include metadata_json and work as-is; older tables need the column added first — the startup error carries the reference DDL.
• One caveat to “work as-is”: the legacy modules never rejected absolute or .. resource paths, and the new implementation validates rows on read — getSkill refuses such a row; getAllSkills / getAllSkillNames skip it with a warning. A row whose name fails validation cannot be deleted either — clearAllSkills or direct SQL is the only remedy. Audit resource_path and skill names before migrating; those values were never safely consumable downstream.
• The old modules implicitly created an agentscope database (MySQL) or schema (PostgreSQL). The new repository puts its tables wherever the connection points — aim the DataSource at the existing tables.
• databaseName / schemaName have no equivalent — the tables live in whatever database the DataSource points to, same as the base tables. Table names can be overridden via skillTableName / skillResourcesTableName. Correspondingly, getSource() changes from mysql_<databaseName>_<table> / postgresql_<schemaName>_<table> to jdbc_<skillTableName> — consumers keying on it (e.g. the skill staging cache namespace) get a fresh subtree after migration, and the old one is reclaimed by orphan GC.

​

When to Use