@carllee1983/dbcli 1.29.0 → 1.31.0

package/dist/cli.mjs

@@ -7136,9 +7136,11 @@ async function writeV2Config(path, config) {
   DbcliConfigV2Schema.parse(config);
   const storagePath = await resolveConfigStoragePath(path);
   const configPath = join2(storagePath, "config.json");
+  const tmpPath = `${configPath}.tmp`;
   await Bun.$`mkdir -p ${storagePath}`;
   const json = JSON.stringify(config, null, 2);
-  await Bun.write(configPath, json);
+  await Bun.write(tmpPath, json);
+  await Bun.$`mv -f ${tmpPath} ${configPath}`;
 }
 async function patchConnectionSchema(dbcliPath, connectionName, schema, metadataUpdate) {
   const storagePath = await resolveConfigStoragePath(dbcliPath);
@@ -81222,7 +81224,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.29.0",
+  version: "1.31.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {

package/dist/core.d.ts

@@ -354,6 +354,40 @@ export declare class AdapterFactory {
 	static createRedisAdapter(options: ConnectionOptions, blacklistRules?: string[], maskRules?: RedisMaskRule[]): QueryableAdapter;
 	static createElasticsearchAdapter(options: ConnectionOptions): QueryableAdapter;
 }
+/**
+ * Type definitions for data modification operations
+ * Defines results and options for data modification (INSERT, UPDATE, DELETE) operations
+ */
+/**
+ * Result of a data execution operation
+ * Used to wrap the execution result and metadata of data modification operations
+ */
+export interface DataExecutionResult {
+	/** Execution status: success or error */
+	status: "success" | "error";
+	/** Type of operation executed */
+	operation: "insert" | "update" | "delete";
+	/** Number of rows affected */
+	rows_affected: number;
+	/** Execution timestamp in ISO 8601 format */
+	timestamp?: string;
+	/** Generated SQL statement (for confirmation and error messages) */
+	sql?: string;
+	/** Error message (only when status is 'error') */
+	error?: string;
+}
+/**
+ * Data execution options
+ * Controls how data modification operations are executed
+ */
+export interface DataExecutionOptions {
+	/** Dry run mode: display SQL without executing */
+	dryRun?: boolean;
+	/** Skip confirmation prompt */
+	force?: boolean;
+	/** Verbose output */
+	verbose?: boolean;
+}
 interface SqlConnectionConfig {
 	system: "postgresql" | "mysql" | "mariadb";
 	host: string | {
@@ -2544,6 +2578,82 @@ export declare class QueryExecutor {
 		limitValue?: number;
 	}): Promise<QueryResult<Record<string, unknown>>>;
 }
+/**
+ * DataExecutor class for executing INSERT, UPDATE, DELETE operations
+ */
+export declare class DataExecutor {
+	private adapter;
+	private permission;
+	private dbSystem;
+	private blacklistValidator?;
+	constructor(adapter: DatabaseAdapter, permission: Permission, dbSystem?: "postgresql" | "mysql", blacklistValidator?: BlacklistValidator | undefined);
+	/**
+	 * Build a parameterized INSERT SQL statement
+	 * Returns {sql, params} form to prevent SQL injection
+	 *
+	 * @param tableName Table name
+	 * @param data Data object to insert {column: value, ...}
+	 * @param schema Table schema
+	 * @returns Parameterized SQL and parameters array
+	 * @throws Error if a data column is not found in the table schema
+	 */
+	buildInsertSql(tableName: string, data: Record<string, unknown>, schema: TableSchema): {
+		sql: string;
+		params: (string | number | boolean | null)[];
+	};
+	/**
+	 * Execute an INSERT operation
+	 * Enforces permission check, builds SQL, shows confirmation prompt, executes
+	 *
+	 * @param tableName Table name
+	 * @param data Data object to insert
+	 * @param schema Table schema
+	 * @param options Execution options (dryRun, force, verbose)
+	 * @returns DataExecutionResult
+	 * @throws PermissionError if insufficient permissions
+	 * @throws Error if execution fails
+	 */
+	executeInsert(tableName: string, data: Record<string, unknown>, schema: TableSchema, options?: DataExecutionOptions): Promise<DataExecutionResult>;
+	/**
+	 * Execute an UPDATE operation
+	 * Enforces permission check, builds SQL, shows confirmation prompt, executes
+	 *
+	 * @param tableName Table name
+	 * @param data Updated data object
+	 * @param where WHERE clause condition object
+	 * @param schema Table schema
+	 * @param options Execution options
+	 * @returns DataExecutionResult
+	 */
+	executeUpdate(tableName: string, data: Record<string, unknown>, where: Record<string, unknown>, schema: TableSchema, options?: DataExecutionOptions): Promise<DataExecutionResult>;
+	/**
+	 * Execute a DELETE operation
+	 * Admin-only operation, requires strict permission check
+	 *
+	 * @param tableName Table name
+	 * @param where WHERE clause condition object
+	 * @param schema Table schema
+	 * @param options Execution options
+	 * @returns DataExecutionResult
+	 */
+	executeDelete(tableName: string, where: Record<string, unknown>, schema: TableSchema, options?: DataExecutionOptions): Promise<DataExecutionResult>;
+	/**
+	 * Get database system type (used to determine parameter placeholder and identifier quoting)
+	 */
+	private getSystemType;
+	/**
+	 * Get identifier quote character (for table names and column names)
+	 */
+	private getQuoteChar;
+	/**
+	 * Build a parameterized UPDATE SQL statement
+	 */
+	private buildUpdateSql;
+	/**
+	 * Build a parameterized DELETE SQL statement
+	 */
+	private buildDeleteSql;
+}
 interface SchemaIndex {
 	tables: Record<string, {
 		location: "hot" | "cold";
@@ -2769,6 +2879,12 @@ export declare function loadConnectionEnv(resolved: ResolvedConnection, basePath
  * Read and validate a v2 config from disk
  */
 export declare function readV2Config(path: string): Promise<DbcliConfigV2>;
+/**
+ * Write a v2 config to disk atomically (temp file + rename).
+ * Writing to a temp file then renaming over the target is an atomic operation
+ * on the same filesystem, so a crash mid-write can never leave a corrupt config.
+ */
+export declare function writeV2Config(path: string, config: DbcliConfigV2): Promise<void>;
 /**
  * List all connection names in a v2 config
  */
@@ -2789,7 +2905,47 @@ export declare function listConnections(config: DbcliConfigV2): Array<{
 	};
 	isDefault: boolean;
 }>;
+export type SqlSystem = "postgresql" | "mysql" | "mariadb";
+/**
+ * `$env` 變數名。per-connection 命名空間化:常駐 sidecar 共用 process.env,
+ * 且 loadEnvFile 不覆寫既有 key——若兩連線都用 DB_PASSWORD 會撞名取到對方的值。
+ */
+export declare function envVarNameFor(connName: string, field: "password"): string;
+/** 把 secret 寫進該連線的 envFile(KEY=VALUE);既有同名 key 就地覆寫,否則追加。 */
+export declare function writeConnectionSecret(projectPath: string, connName: string, field: "password", value: string): Promise<void>;
+export interface ConnectionInput {
+	name: string;
+	system: SqlSystem;
+	host: string;
+	port: number;
+	user: string;
+	database: string;
+}
+/** 刪除連線(immutable)。刪預設則改派為剩餘第一條;刪最後一條則擋下(v2 需至少一條)。 */
+export declare function removeConnection(config: DbcliConfigV2, name: string): DbcliConfigV2;
+/** 設定預設連線(immutable)。 */
+export declare function setDefaultConnection(config: DbcliConfigV2, name: string): DbcliConfigV2;
+/**
+ * v1 單連線 → v2,產生唯一 'default' 連線。沿用 v1 既有密碼慣例:legacy
+ * `.env.local` 的 `DB_PASSWORD`,故 default 連線 envFile 指向 '.env.local'、
+ * password 設 {$env:'DB_PASSWORD'},不搬動既有 secret。blacklist/audit/metadata 原樣帶過。
+ */
+export declare function migrateV1ToV2(v1: DbcliConfig$1): DbcliConfigV2;
+/** 新增或就地覆寫同名連線(immutable)。非機密欄存字面值,password 存 {$env} 參照 +
+ *  per-connection envFile。編輯時保留既有 permission;新建預設 'query-only'。 */
+export declare function upsertConnection(config: DbcliConfigV2, input: ConnectionInput): DbcliConfigV2;
+interface ProjectConfigBinding {
+	version: 3;
+	binding: {
+		type: "home-storage";
+		storagePath: string;
+		projectPath: string;
+		createdAt: string;
+	};
+}
+export declare function getProjectStoragePath(projectPath: string): string;
 export declare function resolveConfigStoragePath(path: string): Promise<string>;
+export declare function writeProjectBinding(projectPath: string, storagePath?: string): Promise<ProjectConfigBinding>;
 /**
  * Read and fully resolve a `.dbcli` project config: handles project-binding
  * indirection, v1/v2 formats, per-connection `.env` loading and `{$env}`