@axiom-lattice/pg-stores 1.0.13 → 1.0.15

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/pg-stores@1.0.13 build /home/runner/work/agentic/agentic/packages/pg-stores
+> @axiom-lattice/pg-stores@1.0.15 build /home/runner/work/agentic/agentic/packages/pg-stores
 > tsup src/index.ts --format cjs,esm --dts --sourcemap
 
 CLI Building entry: src/index.ts
@@ -8,13 +8,13 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/index.mjs     43.66 KB
-ESM dist/index.mjs.map 81.24 KB
-ESM ⚡️ Build success in 191ms
-CJS dist/index.js     45.25 KB
-CJS dist/index.js.map 82.54 KB
-CJS ⚡️ Build success in 193ms
+CJS dist/index.js     95.79 KB
+CJS dist/index.js.map 180.15 KB
+CJS ⚡️ Build success in 321ms
+ESM dist/index.mjs     93.28 KB
+ESM dist/index.mjs.map 176.85 KB
+ESM ⚡️ Build success in 322ms
 DTS Build start
-DTS ⚡️ Build success in 7129ms
-DTS dist/index.d.ts  11.40 KB
-DTS dist/index.d.mts 11.40 KB
+DTS ⚡️ Build success in 11780ms
+DTS dist/index.d.ts  26.47 KB
+DTS dist/index.d.mts 26.47 KB

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @axiom-lattice/pg-stores
 
+## 1.0.15
+
+### Patch Changes
+
+- 203d94b: update metrics middleware and tenant / user
+- Updated dependencies [203d94b]
+  - @axiom-lattice/protocols@2.1.15
+  - @axiom-lattice/core@2.1.25
+
+## 1.0.14
+
+### Patch Changes
+
+- faf1bad: update team and more
+- Updated dependencies [faf1bad]
+  - @axiom-lattice/core@2.1.24
+  - @axiom-lattice/protocols@2.1.14
+
 ## 1.0.13
 
 ### Patch Changes

package/README_DATABASE_CONFIG.md

@@ -0,0 +1,217 @@
+# DatabaseConfigStore 实现说明
+
+## 概述
+
+`DatabaseConfigStore` 是用于存储和管理数据库连接配置的持久化存储方案，支持多租户隔离和密码自动加密。
+
+## 特性
+
+- ✅ **多租户隔离**: 基于 `tenant_id` 字段实现租户级别的数据隔离
+- ✅ **密码加密存储**: 使用 AES-256-GCM 自动加密数据库密码
+- ✅ **自动解密**: 读取配置时自动解密密码，调用方透明
+- ✅ **两种存储实现**: InMemory（开发）和 PostgreSQL（生产）
+- ✅ **集成 SqlDatabaseManager**: 可直接从 Store 加载配置到连接管理器
+
+## 快速开始
+
+### 1. 使用 InMemory 存储（默认）
+
+```typescript
+import { storeLatticeManager } from '@axiom-lattice/core';
+import type { DatabaseConfig } from '@axiom-lattice/protocols';
+
+// 获取默认的 InMemory Store
+const store = await storeLatticeManager.getStoreLattice('default', 'database').store;
+
+// 创建配置
+await store.createConfig('tenant-1', 'config-1', {
+  key: 'main-db',
+  config: {
+    type: 'postgres',
+    host: 'localhost',
+    port: 5432,
+    database: 'mydb',
+    user: 'admin',
+    password: 'secret',
+  },
+  name: 'Main Database',
+});
+
+// 获取配置
+const config = await store.getConfigByKey('tenant-1', 'main-db');
+console.log(config?.config.password); // 密码已自动解密
+```
+
+### 2. 使用 PostgreSQL 存储
+
+```typescript
+import { PostgreSQLDatabaseConfigStore } from '@axiom-lattice/pg-stores';
+
+const pgStore = new PostgreSQLDatabaseConfigStore({
+  poolConfig: process.env.DATABASE_URL,
+  autoMigrate: true,
+});
+
+// 使用方式与 InMemory 相同
+await pgStore.createConfig('tenant-1', 'config-1', {
+  key: 'main-db',
+  config: { /* ... */ },
+});
+```
+
+### 3. 集成到 SqlDatabaseManager
+
+```typescript
+import { sqlDatabaseManager } from '@axiom-lattice/core';
+
+// 从 Store 加载所有配置并注册
+await sqlDatabaseManager.loadConfigsFromStore(store, 'tenant-1');
+
+// 现在可以使用注册的数据库
+const db = sqlDatabaseManager.getDatabase('main-db');
+const tables = await db.listTables();
+```
+
+## 环境变量
+
+### LATTICE_ENCRYPTION_KEY（推荐设置）
+
+用于加密敏感数据的全局密钥。
+
+```bash
+# .env 文件
+LATTICE_ENCRYPTION_KEY="your-secret-key-at-least-32-characters-long"
+```
+
+**注意**:
+- 未设置时使用默认密钥（会输出警告）
+- 生产环境**必须**设置此变量
+- 密钥丢失将导致无法解密已存储的密码
+
+## 表结构
+
+PostgreSQL 实现会创建以下表：
+
+```sql
+CREATE TABLE lattice_database_configs (
+  id VARCHAR(255) NOT NULL,
+  tenant_id VARCHAR(255) NOT NULL,
+  key VARCHAR(255) NOT NULL,
+  name VARCHAR(255),
+  description TEXT,
+  config JSONB NOT NULL,          -- 密码字段加密存储
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  
+  PRIMARY KEY (tenant_id, id),
+  CONSTRAINT uk_lattice_database_configs_tenant_key UNIQUE (tenant_id, key)
+);
+```
+
+## 核心接口
+
+### DatabaseConfigEntry
+
+```typescript
+interface DatabaseConfigEntry {
+  id: string;
+  tenantId: string;
+  key: string;
+  config: DatabaseConfig;  // 密码已解密
+  name?: string;
+  description?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### DatabaseConfigStore
+
+```typescript
+interface DatabaseConfigStore {
+  getAllConfigs(tenantId: string): Promise<DatabaseConfigEntry[]>;
+  getConfigById(tenantId: string, id: string): Promise<DatabaseConfigEntry | null>;
+  getConfigByKey(tenantId: string, key: string): Promise<DatabaseConfigEntry | null>;
+  createConfig(tenantId: string, id: string, data: CreateDatabaseConfigRequest): Promise<DatabaseConfigEntry>;
+  updateConfig(tenantId: string, id: string, updates: Partial<UpdateDatabaseConfigRequest>): Promise<DatabaseConfigEntry | null>;
+  deleteConfig(tenantId: string, id: string): Promise<boolean>;
+  hasConfig(tenantId: string, id: string): Promise<boolean>;
+}
+```
+
+## 加密方案
+
+- **算法**: AES-256-GCM
+- **密钥派生**: PBKDF2 (100,000 次迭代)
+- **存储格式**: `salt:iv:ciphertext:authTag` (Base64 编码)
+- **解密时机**: Store 层 `getConfig*()` 方法返回时自动解密
+
+## 最佳实践
+
+### 1. 生产环境配置
+
+```typescript
+// 使用 PostgreSQL Store
+const store = new PostgreSQLDatabaseConfigStore({
+  poolConfig: process.env.DATABASE_URL,
+  autoMigrate: true,
+});
+
+// 确保设置了加密密钥
+if (!process.env.LATTICE_ENCRYPTION_KEY) {
+  throw new Error('LATTICE_ENCRYPTION_KEY must be set in production');
+}
+```
+
+### 2. 应用启动时加载配置
+
+```typescript
+async function initializeApp() {
+  const store = new PostgreSQLDatabaseConfigStore({ /* ... */ });
+  
+  // 加载所有租户的数据库配置
+  const tenants = ['tenant-1', 'tenant-2'];
+  for (const tenantId of tenants) {
+    await sqlDatabaseManager.loadConfigsFromStore(store, tenantId);
+  }
+}
+```
+
+### 3. 密钥管理
+
+```bash
+# 生成安全密钥 (推荐)
+openssl rand -base64 32
+
+# 或使用 Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+## 示例代码
+
+查看完整示例：`packages/pg-stores/examples/database-config-store.example.ts`
+
+## 文件结构
+
+```
+packages/
+├── protocols/src/
+│   └── DatabaseConfigStoreProtocol.ts      # 协议接口定义
+├── core/src/
+│   ├── util/encryption.ts                  # 通用加密工具
+│   └── store_lattice/
+│       ├── StoreLatticeManager.ts          # Store 管理器（已添加 database 类型）
+│       └── InMemoryDatabaseConfigStore.ts  # InMemory 实现
+└── pg-stores/src/
+    ├── stores/
+    │   └── PostgreSQLDatabaseConfigStore.ts # PostgreSQL 实现
+    └── migrations/
+        └── database_config_migrations.ts    # 数据库迁移
+```
+
+## 注意事项
+
+1. **密码解密**: Store 层返回的配置中密码已解密，请妥善保管
+2. **多租户**: 所有操作都需要传入 `tenantId` 参数
+3. **唯一性**: `(tenant_id, key)` 组合必须唯一
+4. **加密密钥**: 生产环境务必设置 `LATTICE_ENCRYPTION_KEY`