Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(migrations): 补齐 Lite 模式缺失的 SQLite 版本化迁移

icatwb888172dce46
diff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.go
new file mode 100644
index 000000000..3e6f40d0d
--- /dev/null
+++ b/internal/database/migration_sqlite_versioned_schema_test.go
@@ -0,0 +1,184 @@
+package database
+
+import (
+ "database/sql"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+// versionedSQLiteTables is the set of tables that SQLite migrations must
+// create to stay in sync with the versioned (PostgreSQL) migrations:
+// 000041 task queue, 000053 system settings, 000055 processing spans,
+// 000063 knowledge multi-tags.
+var versionedSQLiteTables = []string{
+ "task_pending_ops",
+ "task_dead_letters",
+ "system_settings",
+ "knowledge_processing_spans",
+ "knowledge_tag_relations",
+}
+
+// versionedSQLiteColumns maps each existing table to the columns that the
+// versioned migrations add and the SQLite baseline was missing.
+var versionedSQLiteColumns = map[string][]string{
+ "tenants": {"api_principal_config"}, // 000064
+ "users": {"is_system_admin"}, // 000053
+ "knowledges": {"pending_subtasks_count"}, // 000056
+ "messages": {"attachments"}, // 000034
+ "tenant_invitations": {"token", "accepted_count"}, // 000054
+ "embed_channels": {"allow_memory"}, // 000060
+ "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064
+}
+
+const expectedSQLiteMigrationVersion = 11
+
+func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {
+ repoRoot := sqliteRepoRoot(t)
+ chdirAndRestore(t, repoRoot)
+
+ dbPath := filepath.Join(t.TempDir(), "fresh.db")
+ require.NoError(t, RunMigrationsWithOptions("sqlite3://unused", MigrationOptions{SQLiteDBPath: dbPath}))
+
+ db := openSQLiteDB(t, dbPath)
+ version, dirty := sqliteMigrationState(t, db)
+ require.Equal(t, expectedSQLiteMigrationVersion, version)
+ require.False(t, dirty)
+
+ for _, table := range versionedSQLiteTables {
+ require.Truef(t, sqliteTableExists(t, db, table), "SQLite migrations must create table %s", table)
+ }
+ for table, columns := range versionedSQLiteColumns {
+ for _, column := range columns {
+ require.Truef(
+ t,
+ sqliteColumnExists(t, db, table, column),
+ "SQLite migrations must add column %s.%s",
+ table,
+ column,
+ )
+ }
+ }
+}
+
+func TestSQLiteMigrationsUpgradeV4PreservesData(t *testing.T) {
+ repoRoot := sqliteRepoRoot(t)
+
+ // Build a legacy v4 migration root (000000_init .. 000004_memory) so we
+ // can prove the new migrations upgrade an existing Lite database without
+ // replaying the baseline.
+ legacyRoot := copySQLiteMigrationsV4(t, repoRoot)
+ chdirAndRestore(t, legacyRoot)
+
+ dbPath := filepath.Join(t.TempDir(), "upgrade.db")
+ require.NoError(t, RunMigrationsWithOptions("sqlite3://unused", MigrationOptions{SQLiteDBPath: dbPath}))
+
+ db := openSQLiteDB(t, dbPath)
+ versionBefore, dirtyBefore := sqliteMigrationState(t, db)
+ require.Equal(t, 4, versionBefore)
+ require.False(t, dirtyBefore)
+ _, err := db.Exec("INSERT INTO tenants (name, business) VALUES (?, ?)", "upgrade-sentinel", "migration-test")
+ require.NoError(t, err)
+
+ // Run the full migration set from the repo root.
+ chdirAndRestore(t, repoRoot)
+ require.NoError(t, RunMigrationsWithOptions("sqlite3://unused", MigrationOptions{SQLiteDBPath: dbPath}))
+
+ db = openSQLiteDB(t, dbPath)
+ versionAfter, dirtyAfter := sqliteMigrationState(t, db)
+ require.Equal(t, expectedSQLiteMigrationVersion, versionAfter)
+ require.False(t, dirtyAfter)
+
+ for _, table := range versionedSQLiteTables {
+ require.Truef(t, sqliteTableExists(t, db, table), "upgraded SQLite DB must have table %s", table)
+ }
+ for table, columns := range versionedSQLiteColumns {
+ for _, column := range columns {
+ require.Truef(
+ t,
+ sqliteColumnExists(t, db, table, column),
+ "upgraded SQLite DB must have column %s.%s",
+ table,
+ column,
+ )
+ }
+ }
+
+ var sentinelName string
+ require.NoError(t, db.QueryRow("SELECT name FROM tenants WHERE business = ?", "migration-test").Scan(&sentinelName))
+ require.Equal(t, "upgrade-sentinel", sentinelName)
+}
+
+func sqliteRepoRoot(t *testing.T) string {
+ t.Helper()
+ repoRoot, err := filepath.Abs(filepath.Join("..", ".."))
+ require.NoError(t, err)
+ return repoRoot
+}
+
+func chdirAndRestore(t *testing.T, dir string) {
+ t.Helper()
+ previousDir, err := os.Getwd()
+ require.NoError(t, err)
+ require.NoError(t, os.Chdir(dir))
+ t.Cleanup(func() { _ = os.Chdir(previousDir) })
+}
+
+func openSQLiteDB(t *testing.T, dbPath string) *sql.DB {
+ t.Helper()
+ db, err := sql.Open("sqlite3", dbPath)
+ require.NoError(t, err)
+ t.Cleanup(func() { _ = db.Close() })
+ return db
+}
+
+func sqliteMigrationState(t *testing.T, db *sql.DB) (version int, dirty bool) {
+ t.Helper()
+ require.NoError(t, db.QueryRow("SELECT version, dirty FROM schema_migrations").Scan(&version, &dirty))
+ return version, dirty
+}
+
+func sqliteTableExists(t *testing.T, db *sql.DB, table string) bool {
+ t.Helper()
+ var n int
+ require.NoError(t, db.QueryRow(
+ "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = ?",
+ table,
+ ).Scan(&n))
+ return n == 1
+}
+
+func sqliteColumnExists(t *testing.T, db *sql.DB, table, column string) bool {
+ t.Helper()
+ var n int
+ require.NoError(t, db.QueryRow(
+ "SELECT COUNT(*) FROM pragma_table_info(?) WHERE name = ?",
+ table,
+ column,
+ ).Scan(&n))
+ return n == 1
+}
+
+func copySQLiteMigrationsV4(t *testing.T, repoRoot string) string {
+ t.Helper()
+ dest := t.TempDir()
+ srcDir := filepath.Join(repoRoot, "migrations", "sqlite")
+ destDir := filepath.Join(dest, "migrations", "sqlite")
+ require.NoError(t, os.MkdirAll(destDir, 0o755))
+
+ legacy := []string{
+ "000000_init.up.sql",
+ "000001_remove_wiki_log.up.sql",
+ "000002_knowledge_folder_path.up.sql",
+ "000003_knowledge_base_auto_tag_config.up.sql",
+ "000004_memory.up.sql",
+ }
+ for _, name := range legacy {
+ data, err := os.ReadFile(filepath.Join(srcDir, name))
+ require.NoError(t, err)
+ require.NoError(t, os.WriteFile(filepath.Join(destDir, name), data, 0o600))
+ }
+ return dest
+}
diff --git a/migrations/sqlite/000005_messages_attachments_and_invitation_fields.down.sql b/migrations/sqlite/000005_messages_attachments_and_invitation_fields.down.sql
new file mode 100644
index 000000000..391ad2e34
--- /dev/null
+++ b/migrations/sqlite/000005_messages_attachments_and_invitation_fields.down.sql
@@ -0,0 +1,3 @@
+ALTER TABLE tenant_invitations DROP COLUMN accepted_count;
+ALTER TABLE tenant_invitations DROP COLUMN token;
+ALTER TABLE messages DROP COLUMN attachments;
diff --git a/migrations/sqlite/000005_messages_attachments_and_invitation_fields.up.sql b/migrations/sqlite/000005_messages_attachments_and_invitation_fields.up.sql
new file mode 100644
index 000000000..4b8bbad40
--- /dev/null
+++ b/migrations/sqlite/000005_messages_attachments_and_invitation_fields.up.sql
@@ -0,0 +1,8 @@
+-- Mirrors versioned migrations:
+-- 000034_add_attachments messages.attachments
+-- 000054_invitation_tokens tenant_invitations.token / accepted_count
+
+ALTER TABLE messages ADD COLUMN attachments TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE tenant_invitations ADD COLUMN token VARCHAR(64) NOT NULL DEFAULT '';
+ALTER TABLE tenant_invitations ADD COLUMN accepted_count INTEGER NOT NULL DEFAULT 0;
diff --git a/migrations/sqlite/000006_task_queue_and_dead_letters.down.sql b/migrations/sqlite/000006_task_queue_and_dead_letters.down.sql
new file mode 100644
index 000000000..360a70124
--- /dev/null
+++ b/migrations/sqlite/000006_task_queue_and_dead_letters.down.sql
@@ -0,0 +1,8 @@
+DROP INDEX IF EXISTS idx_task_dead_letters_task_type;
+DROP INDEX IF EXISTS idx_task_dead_letters_tenant;
+DROP INDEX IF EXISTS idx_task_dead_letters_scope;
+DROP INDEX IF EXISTS idx_task_pending_ops_tenant;
+DROP INDEX IF EXISTS idx_task_pending_ops_scope;
+
+DROP TABLE IF EXISTS task_dead_letters;
+DROP TABLE IF EXISTS task_pending_ops;
diff --git a/migrations/sqlite/000006_task_queue_and_dead_letters.up.sql b/migrations/sqlite/000006_task_queue_and_dead_letters.up.sql
new file mode 100644
index 000000000..84393d392
--- /dev/null
+++ b/migrations/sqlite/000006_task_queue_and_dead_letters.up.sql
@@ -0,0 +1,44 @@
+-- Mirrors versioned migration 000041_task_queue_and_wiki_indexes:
+-- durable pending-op queue and dead-letter archive for SQLite.
+
+CREATE TABLE IF NOT EXISTS task_pending_ops (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ tenant_id INTEGER NOT NULL,
+ task_type VARCHAR(64) NOT NULL,
+ scope VARCHAR(32) NOT NULL,
+ scope_id VARCHAR(64) NOT NULL,
+ op VARCHAR(32) NOT NULL,
+ dedup_key VARCHAR(128) NOT NULL DEFAULT '',
+ payload TEXT NOT NULL DEFAULT '{}',
+ fail_count INTEGER NOT NULL DEFAULT 0,
+ enqueued_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ claimed_at DATETIME
+);
+
+CREATE INDEX IF NOT EXISTS idx_task_pending_ops_scope
+ ON task_pending_ops (task_type, scope, scope_id, id);
+
+CREATE INDEX IF NOT EXISTS idx_task_pending_ops_tenant
+ ON task_pending_ops (tenant_id);
+
+CREATE TABLE IF NOT EXISTS task_dead_letters (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ tenant_id INTEGER NOT NULL,
+ task_type VARCHAR(64) NOT NULL,
+ scope VARCHAR(32) NOT NULL,
+ scope_id VARCHAR(64) NOT NULL,
+ related_id VARCHAR(64) NOT NULL DEFAULT '',
+ payload TEXT NOT NULL,
+ last_error TEXT NOT NULL DEFAULT '',
+ fail_count INTEGER NOT NULL,
+ failed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_task_dead_letters_scope
+ ON task_dead_letters (scope, scope_id, failed_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_task_dead_letters_tenant
+ ON task_dead_letters (tenant_id, failed_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_task_dead_letters_task_type
+ ON task_dead_letters (task_type, failed_at DESC);
diff --git a/migrations/sqlite/000007_system_admin_and_settings.down.sql b/migrations/sqlite/000007_system_admin_and_settings.down.sql
new file mode 100644
index 000000000..3d1d8f45f
--- /dev/null
+++ b/migrations/sqlite/000007_system_admin_and_settings.down.sql
@@ -0,0 +1,4 @@
+DROP INDEX IF EXISTS idx_system_settings_category;
+DROP TABLE IF EXISTS system_settings;
+DROP INDEX IF EXISTS idx_users_is_system_admin;
+ALTER TABLE users DROP COLUMN is_system_admin;
diff --git a/migrations/sqlite/000007_system_admin_and_settings.up.sql b/migrations/sqlite/000007_system_admin_and_settings.up.sql
new file mode 100644
index 000000000..f002f787c
--- /dev/null
+++ b/migrations/sqlite/000007_system_admin_and_settings.up.sql
@@ -0,0 +1,22 @@
+-- Mirrors versioned migration 000053_system_admin_and_settings:
+-- users.is_system_admin + system_settings table.
+
+ALTER TABLE users ADD COLUMN is_system_admin BOOLEAN NOT NULL DEFAULT 0;
+CREATE INDEX IF NOT EXISTS idx_users_is_system_admin ON users (is_system_admin);
+
+CREATE TABLE IF NOT EXISTS system_settings (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ key VARCHAR(128) NOT NULL UNIQUE,
+ value TEXT NOT NULL,
+ value_type VARCHAR(16) NOT NULL,
+ category VARCHAR(32) NOT NULL,
+ description TEXT NOT NULL DEFAULT '',
+ is_secret BOOLEAN NOT NULL DEFAULT 0,
+ requires_restart BOOLEAN NOT NULL DEFAULT 0,
+ last_modified_by VARCHAR(36) NOT NULL DEFAULT '',
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_system_settings_category
+ ON system_settings (category);
diff --git a/migrations/sqlite/000008_processing_spans_and_pending_subtasks.down.sql b/migrations/sqlite/000008_processing_spans_and_pending_subtasks.down.sql
new file mode 100644
index 000000000..e9f804ecc
--- /dev/null
+++ b/migrations/sqlite/000008_processing_spans_and_pending_subtasks.down.sql
@@ -0,0 +1,6 @@
+ALTER TABLE knowledges DROP COLUMN pending_subtasks_count;
+
+DROP INDEX IF EXISTS idx_kpspan_parent;
+DROP INDEX IF EXISTS idx_kpspan_status_started;
+DROP INDEX IF EXISTS idx_kpspan_knowledge_attempt;
+DROP TABLE IF EXISTS knowledge_processing_spans;
diff --git a/migrations/sqlite/000008_processing_spans_and_pending_subtasks.up.sql b/migrations/sqlite/000008_processing_spans_and_pending_subtasks.up.sql
new file mode 100644
index 000000000..30888e16d
--- /dev/null
+++ b/migrations/sqlite/000008_processing_spans_and_pending_subtasks.up.sql
@@ -0,0 +1,38 @@
+-- Mirrors versioned migrations:
+-- 000055_knowledge_processing_spans knowledge_processing_spans table
+-- 000056_knowledge_pending_subtasks knowledges.pending_subtasks_count
+
+CREATE TABLE IF NOT EXISTS knowledge_processing_spans (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ knowledge_id VARCHAR(64) NOT NULL,
+ attempt INTEGER NOT NULL DEFAULT 1,
+ span_id VARCHAR(64) NOT NULL,
+ parent_span_id VARCHAR(64),
+ name VARCHAR(64) NOT NULL,
+ kind VARCHAR(16) NOT NULL,
+ status VARCHAR(16) NOT NULL,
+ input TEXT,
+ output TEXT,
+ metadata TEXT,
+ error_code VARCHAR(64),
+ error_message TEXT,
+ error_detail TEXT,
+ started_at DATETIME,
+ finished_at DATETIME,
+ duration_ms INTEGER,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ CONSTRAINT uq_kpspan_attempt_span UNIQUE (knowledge_id, attempt, span_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_kpspan_knowledge_attempt
+ ON knowledge_processing_spans (knowledge_id, attempt);
+
+CREATE INDEX IF NOT EXISTS idx_kpspan_status_started
+ ON knowledge_processing_spans (status, started_at);
+
+CREATE INDEX IF NOT EXISTS idx_kpspan_parent
+ ON knowledge_processing_spans (parent_span_id)
+ WHERE parent_span_id IS NOT NULL;
+
+ALTER TABLE knowledges ADD COLUMN pending_subtasks_count INTEGER NOT NULL DEFAULT 0;
diff --git a/migrations/sqlite/000009_embed_channel_memory_flag.down.sql b/migrations/sqlite/000009_embed_channel_memory_flag.down.sql
new file mode 100644
index 000000000..b61abf1d4
--- /dev/null
+++ b/migrations/sqlite/000009_embed_channel_memory_flag.down.sql
@@ -0,0 +1 @@
+ALTER TABLE embed_channels DROP COLUMN allow_memory;
diff --git a/migrations/sqlite/000009_embed_channel_memory_flag.up.sql b/migrations/sqlite/000009_embed_channel_memory_flag.up.sql
new file mode 100644
index 000000000..91941659d
--- /dev/null
+++ b/migrations/sqlite/000009_embed_channel_memory_flag.up.sql
@@ -0,0 +1,3 @@
+-- Mirrors versioned migration 000060_embed_channels: embed_channels.allow_memory.
+
+ALTER TABLE embed_channels ADD COLUMN allow_memory BOOLEAN NOT NULL DEFAULT 0;
diff --git a/migrations/sqlite/000010_knowledge_multi_tags.down.sql b/migrations/sqlite/000010_knowledge_multi_tags.down.sql
new file mode 100644
index 000000000..6591c127e
--- /dev/null
+++ b/migrations/sqlite/000010_knowledge_multi_tags.down.sql
@@ -0,0 +1,3 @@
+DROP INDEX IF EXISTS idx_ktr_tag;
+DROP INDEX IF EXISTS idx_ktr_knowledge;
+DROP TABLE IF EXISTS knowledge_tag_relations;
diff --git a/migrations/sqlite/000010_knowledge_multi_tags.up.sql b/migrations/sqlite/000010_knowledge_multi_tags.up.sql
new file mode 100644
index 000000000..1bc15f3d9
--- /dev/null
+++ b/migrations/sqlite/000010_knowledge_multi_tags.up.sql
@@ -0,0 +1,15 @@
+-- Mirrors versioned migration 000063_knowledge_multi_tags:
+-- many-to-many join table between knowledges and knowledge_tags.
+
+CREATE TABLE IF NOT EXISTS knowledge_tag_relations (
+ knowledge_id VARCHAR(36) NOT NULL,
+ tag_id VARCHAR(36) NOT NULL,
+ created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+ PRIMARY KEY (knowledge_id, tag_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ktr_knowledge
+ ON knowledge_tag_relations (knowledge_id);
+
+CREATE INDEX IF NOT EXISTS idx_ktr_tag
+ ON knowledge_tag_relations (tag_id);
diff --git a/migrations/sqlite/000011_principal_model.down.sql b/migrations/sqlite/000011_principal_model.down.sql
new file mode 100644
index 000000000..b0943e4c0
--- /dev/null
+++ b/migrations/sqlite/000011_principal_model.down.sql
@@ -0,0 +1,3 @@
+ALTER TABLE mcp_oauth_tokens DROP COLUMN principal_id;
+ALTER TABLE mcp_oauth_tokens DROP COLUMN principal_type;
+ALTER TABLE tenants DROP COLUMN api_principal_config;
diff --git a/migrations/sqlite/000011_principal_model.up.sql b/migrations/sqlite/000011_principal_model.up.sql
new file mode 100644
index 000000000..e8abaa516
--- /dev/null
+++ b/migrations/sqlite/000011_principal_model.up.sql
@@ -0,0 +1,7 @@
+-- Mirrors versioned migration 000064_principal_model:
+-- principal identity for MCP OAuth tokens and tenant API config.
+
+ALTER TABLE tenants ADD COLUMN api_principal_config TEXT;
+
+ALTER TABLE mcp_oauth_tokens ADD COLUMN principal_type VARCHAR(32);
+ALTER TABLE mcp_oauth_tokens ADD COLUMN principal_id VARCHAR(512);