数据库配置 | Linch

类型定义

interface DatabaseConfig {
  /**
   * 数据库文件名（默认 'app.db'）
   */
  name?: string;

  /**
   * 应用迁移（会在基座迁移之后执行）
   */
  migrations?: Migration[];
}

interface Migration {
  /**
   * 版本号（必须递增）
   */
  version: number;

  /**
   * 迁移名称
   */
  name: string;

  /**
   * 升级 SQL
   */
  up: string;

  /**
   * 降级 SQL（可选）
   */
  down?: string;
}

默认值

配置项	默认值
`name`	`'app.db'`
`migrations`	`[]`

基本配置

database: {
  name: 'myapp.db',
  migrations: [],
},

基座内置表

基座自动创建以下表：

settings 表

存储应用设置（键值对）：

CREATE TABLE settings (
  key TEXT PRIMARY KEY,
  value TEXT,
  updated_at INTEGER
);

app_state 表

存储 UI 状态：

CREATE TABLE app_state (
  key TEXT PRIMARY KEY,
  value TEXT,
  updated_at INTEGER
);

_migrations 表

记录已执行的迁移：

CREATE TABLE _migrations (
  version INTEGER PRIMARY KEY,
  name TEXT,
  applied_at INTEGER
);

添加自定义迁移

创建自定义表或修改数据结构：

database: {
  migrations: [
    {
      version: 1,
      name: 'create_users_table',
      up: `
        CREATE TABLE users (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          name TEXT NOT NULL,
          email TEXT UNIQUE,
          created_at INTEGER DEFAULT (strftime('%s', 'now'))
        );
      `,
      down: 'DROP TABLE users;',
    },
    {
      version: 2,
      name: 'add_avatar_to_users',
      up: 'ALTER TABLE users ADD COLUMN avatar TEXT;',
      down: 'ALTER TABLE users DROP COLUMN avatar;',
    },
  ],
},

迁移规则

迁移版本号必须递增，不能跳跃或重复。

版本号从 1 开始递增
每次应用启动时自动执行未应用的迁移
迁移一旦执行，不应修改（应添加新迁移）
down 是可选的，用于回滚

使用数据库

查询数据

import { query, execute, transaction } from '@linch-tech/desktop-core';

// 查询
const users = await query<User[]>('SELECT * FROM users WHERE id = ?', [1]);

// 执行（插入、更新、删除）
await execute('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);

// 事务
await transaction(async () => {
  await execute('INSERT INTO users (name) VALUES (?)', ['Alice']);
  await execute('INSERT INTO users (name) VALUES (?)', ['Bob']);
});

使用内置设置

import { getSetting, setSetting, deleteSetting } from '@linch-tech/desktop-core';

// 读取设置
const theme = await getSetting<string>('theme');

// 保存设置
await setSetting('theme', 'dark');

// 删除设置
await deleteSetting('theme');

使用 Hooks

import { useSetting, useAppState } from '@linch-tech/desktop-core';

function SettingsPage() {
  // 读写设置
  const [theme, setTheme] = useSetting<string>('theme', 'light');

  // 读写 UI 状态
  const [sidebarOpen, setSidebarOpen] = useAppState('sidebarOpen', true);

  return (
    <div>
      <select value={theme} onChange={(e) => setTheme(e.target.value)}>
        <option value="light">浅色</option>
        <option value="dark">深色</option>
      </select>
    </div>
  );
}

数据库文件位置

数据库文件存储在应用数据目录：

平台	路径
Windows	`%APPDATA%\{identifier}\{name}`
macOS	`~/Library/Application Support/{identifier}/{name}`
Linux	`~/.local/share/{identifier}/{name}`

其中 {identifier} 是 tauri.conf.json 中的 identifier，{name} 是数据库名。

完整示例

export const config = {
  database: {
    name: 'myapp.db',
    migrations: [
      {
        version: 1,
        name: 'create_projects_table',
        up: `
          CREATE TABLE projects (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            description TEXT,
            status TEXT DEFAULT 'active',
            created_at INTEGER DEFAULT (strftime('%s', 'now')),
            updated_at INTEGER DEFAULT (strftime('%s', 'now'))
          );
          CREATE INDEX idx_projects_status ON projects(status);
        `,
        down: 'DROP TABLE projects;',
      },
      {
        version: 2,
        name: 'create_tasks_table',
        up: `
          CREATE TABLE tasks (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            project_id INTEGER NOT NULL,
            title TEXT NOT NULL,
            completed INTEGER DEFAULT 0,
            created_at INTEGER DEFAULT (strftime('%s', 'now')),
            FOREIGN KEY (project_id) REFERENCES projects(id)
          );
          CREATE INDEX idx_tasks_project ON tasks(project_id);
        `,
        down: 'DROP TABLE tasks;',
      },
    ],
  },
};

注意事项

数据库功能需要 features.database 为 true（默认已启用）。

SQLite 不支持某些 ALTER TABLE 操作（如删除列、修改列类型）。对于这些变更，需要创建新表并迁移数据。