Skip to main content
The SQL plugin provides a sophisticated dynamic migration system that automatically manages database schemas for plugins. This guide covers how the system works and how to define schemas for your plugins.

Dynamic Migration System

The SQL plugin uses a dynamic migration service that automatically creates and updates database tables based on plugin schemas. This eliminates the need for traditional migration files.

How It Works

  1. Plugin Registration - Plugins export their schema definitions
  2. Schema Discovery - The migration service discovers all plugin schemas at startup
  3. Schema Introspection - The system analyzes existing database tables
  4. Dynamic Migration - Tables are created or updated as needed
  5. Dependency Resolution - Tables are created in the correct order based on foreign key dependencies

Key Components

Defining Plugin Schemas

To enable automatic schema management, plugins must export their Drizzle schema definitions:

Plugin Structure

Core Schema Tables

The SQL plugin provides these core tables that all agents use:

Agent Tables

  • agents - Core agent identity
  • memories - Agent memory storage
  • entities - People, objects, and concepts
  • relationships - Connections between entities

Communication Tables

  • rooms - Conversation contexts
  • participants - Room membership
  • messages - Message history

System Tables

  • logs - System event logging
  • cache - Key-value cache with composite primary key
  • tasks - Background task management
  • embeddings - Vector embeddings for similarity search

Schema Introspection

The system uses DrizzleSchemaIntrospector to analyze database schemas:

Migration Process

The dynamic migrator handles various scenarios:

Table Creation

Column Addition

Index Management

Foreign Key Constraints

Best Practices

1. Schema Design

  • Use UUIDs for primary keys
  • Include timestamps (created_at, updated_at)
  • Use JSONB for flexible metadata
  • Define proper indexes for query performance

2. Foreign Keys

  • Always reference existing tables
  • Consider cascade options carefully
  • Be aware of circular dependencies

3. Composite Keys

4. Plugin Schema Organization

Error Handling

The migration system includes robust error handling:
  • Duplicate Tables - Silently skipped
  • Missing Dependencies - Tables created in dependency order
  • Failed Migrations - Detailed error logging with rollback
  • Schema Conflicts - Clear error messages for debugging

Limitations and Considerations

  1. No Downgrades - The system only adds, never removes
  2. Column Type Changes - Not automatically handled
  3. Data Migrations - Must be handled separately
  4. Production Use - Test thoroughly before deploying schema changes

Example: Complete Plugin Schema

This schema will be automatically created when the agent starts, with all tables, columns, indexes, and foreign keys properly configured.