@carllee1983/dbcli 1.56.0 → 1.58.0

package/dist/core.d.ts

@@ -410,8 +410,17 @@ export declare class AdapterFactory {
  * Used to wrap the execution result and metadata of data modification operations
  */
 export interface DataExecutionResult {
-	/** Execution status: success or error */
-	status: "success" | "error";
+	/**
+	 * What became of the operation.
+	 *
+	 * `success` means the statement ran — `rows_affected` may still be 0 if it
+	 * matched nothing. `cancelled` means a user declined at the confirmation.
+	 * `dry_run` means it was previewed and deliberately not run. The last two
+	 * were reported as `success` with `rows_affected: 0` until 2.0.0, which made
+	 * them indistinguishable from a write that matched no rows and caused the
+	 * audit log to record declined operations as writes that happened.
+	 */
+	status: "success" | "error" | "cancelled" | "dry_run";
 	/** Type of operation executed */
 	operation: "insert" | "update" | "delete";
 	/** Number of rows affected */
@@ -434,7 +443,53 @@ export interface DataExecutionOptions {
 	force?: boolean;
 	/** Verbose output */
 	verbose?: boolean;
+	/**
+	 * How to ask the caller's user whether to proceed.
+	 *
+	 * Core states what is about to happen; the caller decides how to present it
+	 * and how to collect an answer. Required whenever a mutation would execute
+	 * without `force`, and absent by design rather than defaulted: silently
+	 * proceeding unconfirmed, or silently declining, are both worse than saying
+	 * that nobody was available to ask.
+	 */
+	confirm?: MutationConfirmer;
+}
+/**
+ * Everything a caller needs to describe a pending mutation to its user.
+ */
+export interface MutationConfirmationRequest {
+	operation: DataExecutionResult["operation"];
+	/**
+	 * Which engine will run it.
+	 *
+	 * Only presentation depends on this: a MongoDB shell line or a Redis command
+	 * announced as "Generated SQL" would be a lie about what is being approved,
+	 * and approving the wrong thing is the failure this whole prompt exists to
+	 * prevent.
+	 */
+	engine: "sql" | "mongodb" | "redis";
+	/** The parameterised statement that will run if confirmed */
+	sql: string;
+	/** Values bound to the statement's placeholders */
+	params: (string | number | boolean | null)[];
+	/**
+	 * Whether this operation is irreversible.
+	 *
+	 * A flag rather than the warning sentence and the question themselves, which
+	 * is what this carried first. The division is not "core cannot translate" —
+	 * `permission-guard` translates the refusal it throws, and so does
+	 * `blacklist-validator` — it is that core owns facts and the command layer
+	 * owns presentation. Whether a delete can be undone is a fact. Which sentence
+	 * a person is shown about it, in what tone, on which stream, is presentation,
+	 * and a caller embedding the executor should be able to say it in its own
+	 * product's voice rather than inheriting dbcli's.
+	 */
+	destructive: boolean;
 }
+/**
+ * Returns true to proceed, false to abandon the mutation.
+ */
+export type MutationConfirmer = (request: MutationConfirmationRequest) => Promise<boolean>;
 interface SqlConnectionConfig {
 	system: "postgresql" | "mysql" | "mariadb";
 	host: string | {
@@ -843,6 +898,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 				}>
 			]>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "postgresql" | "mysql" | "mariadb";
 			host: string | {
 				$env: string;
@@ -853,9 +911,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -968,6 +1023,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			tls: z.ZodOptional<z.ZodBoolean>;
 			srv: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "mongodb";
 			host: string | {
 				$env: string;
@@ -978,9 +1036,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -999,6 +1054,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			statementTimeout?: number | undefined;
 		}, {
 			system: "mongodb";
+			password?: string | {
+				$env: string;
+			} | undefined;
 			host?: string | {
 				$env: string;
 			} | undefined;
@@ -1008,9 +1066,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			user?: string | {
 				$env: string;
 			} | undefined;
-			password?: string | {
-				$env: string;
-			} | undefined;
 			database?: string | {
 				$env: string;
 			} | undefined;
@@ -1083,6 +1138,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 				}>
 			]>>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "redis";
 			host: string | {
 				$env: string;
@@ -1093,9 +1151,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -1109,10 +1164,10 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			port: number | {
 				$env: string;
 			};
-			user?: string | {
+			password?: string | {
 				$env: string;
 			} | undefined;
-			password?: string | {
+			user?: string | {
 				$env: string;
 			} | undefined;
 			database?: string | {
@@ -1203,6 +1258,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			caPath: z.ZodOptional<z.ZodString>;
 			rejectUnauthorized: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "elasticsearch";
 			host: string | {
 				$env: string;
@@ -1213,9 +1271,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -1233,6 +1288,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			caPath?: string | undefined;
 		}, {
 			system: "elasticsearch";
+			password?: string | {
+				$env: string;
+			} | undefined;
 			host?: string | {
 				$env: string;
 			} | undefined;
@@ -1242,9 +1300,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			user?: string | {
 				$env: string;
 			} | undefined;
-			password?: string | {
-				$env: string;
-			} | undefined;
 			database?: string | {
 				$env: string;
 			} | undefined;
@@ -1355,7 +1410,11 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			max_entries: number;
 		};
 	};
+	permission: "admin" | "query-only" | "read-write" | "data-admin";
 	connection: {
+		password: string | {
+			$env: string;
+		};
 		system: "mongodb";
 		host: string | {
 			$env: string;
@@ -1366,9 +1425,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -1386,6 +1442,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "postgresql" | "mysql" | "mariadb";
 		host: string | {
 			$env: string;
@@ -1396,15 +1455,15 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "redis";
 		host: string | {
 			$env: string;
@@ -1415,15 +1474,15 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "elasticsearch";
 		host: string | {
 			$env: string;
@@ -1434,9 +1493,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -1453,7 +1509,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		} | undefined;
 		caPath?: string | undefined;
 	};
-	permission: "admin" | "query-only" | "read-write" | "data-admin";
 	metadata: {
 		version: string;
 		createdAt?: string | undefined;
@@ -1469,6 +1524,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 }, {
 	connection: {
 		system: "mongodb";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -1478,9 +1536,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
@@ -1524,10 +1579,10 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		port: number | {
 			$env: string;
 		};
-		user?: string | {
+		password?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
+		user?: string | {
 			$env: string;
 		} | undefined;
 		database?: string | {
@@ -1537,6 +1592,9 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		statementTimeout?: number | undefined;
 	} | {
 		system: "elasticsearch";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -1546,9 +1604,6 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
@@ -1667,6 +1722,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			envFile: z.ZodOptional<z.ZodString>;
 			environment: z.ZodOptional<z.ZodEffects<z.ZodString, string | undefined, string>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "postgresql" | "mysql" | "mariadb";
 			host: string | {
 				$env: string;
@@ -1677,9 +1735,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -1706,8 +1761,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 				$env: string;
 			} | undefined;
 			timeout?: number | undefined;
-			statementTimeout?: number | undefined;
 			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+			statementTimeout?: number | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>,
@@ -1807,6 +1862,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			envFile: z.ZodOptional<z.ZodString>;
 			environment: z.ZodOptional<z.ZodEffects<z.ZodString, string | undefined, string>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "mongodb";
 			host: string | {
 				$env: string;
@@ -1817,9 +1875,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -1841,6 +1896,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			environment?: string | undefined;
 		}, {
 			system: "mongodb";
+			password?: string | {
+				$env: string;
+			} | undefined;
 			host?: string | {
 				$env: string;
 			} | undefined;
@@ -1850,9 +1908,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			user?: string | {
 				$env: string;
 			} | undefined;
-			password?: string | {
-				$env: string;
-			} | undefined;
 			database?: string | {
 				$env: string;
 			} | undefined;
@@ -1868,8 +1923,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			tls?: boolean | undefined;
 			srv?: boolean | undefined;
 			timeout?: number | undefined;
-			statementTimeout?: number | undefined;
 			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+			statementTimeout?: number | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>,
@@ -1937,6 +1992,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			envFile: z.ZodOptional<z.ZodString>;
 			environment: z.ZodOptional<z.ZodEffects<z.ZodString, string | undefined, string>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "redis";
 			host: string | {
 				$env: string;
@@ -1947,9 +2005,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
@@ -1966,18 +2021,18 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			port: number | {
 				$env: string;
 			};
-			user?: string | {
+			password?: string | {
 				$env: string;
 			} | undefined;
-			password?: string | {
+			user?: string | {
 				$env: string;
 			} | undefined;
 			database?: string | {
 				$env: string;
 			} | undefined;
 			timeout?: number | undefined;
-			statementTimeout?: number | undefined;
 			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+			statementTimeout?: number | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>,
@@ -2072,6 +2127,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			envFile: z.ZodOptional<z.ZodString>;
 			environment: z.ZodOptional<z.ZodEffects<z.ZodString, string | undefined, string>>;
 		}, "strip", z.ZodTypeAny, {
+			password: string | {
+				$env: string;
+			};
 			system: "elasticsearch";
 			host: string | {
 				$env: string;
@@ -2082,15 +2140,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			user: string | {
 				$env: string;
 			};
-			password: string | {
-				$env: string;
-			};
 			database: string | {
 				$env: string;
 			};
 			rejectUnauthorized: boolean;
-			protocol: "http" | "https";
 			permission: "admin" | "query-only" | "read-write" | "data-admin";
+			protocol: "http" | "https";
 			timeout?: number | undefined;
 			statementTimeout?: number | undefined;
 			nodes?: string[] | undefined;
@@ -2105,6 +2160,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			environment?: string | undefined;
 		}, {
 			system: "elasticsearch";
+			password?: string | {
+				$env: string;
+			} | undefined;
 			host?: string | {
 				$env: string;
 			} | undefined;
@@ -2114,14 +2172,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			user?: string | {
 				$env: string;
 			} | undefined;
-			password?: string | {
-				$env: string;
-			} | undefined;
 			database?: string | {
 				$env: string;
 			} | undefined;
 			rejectUnauthorized?: boolean | undefined;
 			timeout?: number | undefined;
+			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 			statementTimeout?: number | undefined;
 			protocol?: "http" | "https" | undefined;
 			nodes?: string[] | undefined;
@@ -2132,11 +2188,13 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 				$env: string;
 			} | undefined;
 			caPath?: string | undefined;
-			permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 			envFile?: string | undefined;
 			environment?: string | undefined;
 		}>
 	]>>, Record<string, {
+		password: string | {
+			$env: string;
+		};
 		system: "postgresql" | "mysql" | "mariadb";
 		host: string | {
 			$env: string;
@@ -2147,9 +2205,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2159,6 +2214,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "mongodb";
 		host: string | {
 			$env: string;
@@ -2169,9 +2227,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2192,6 +2247,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "redis";
 		host: string | {
 			$env: string;
@@ -2202,9 +2260,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2214,6 +2269,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "elasticsearch";
 		host: string | {
 			$env: string;
@@ -2224,15 +2282,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
 		rejectUnauthorized: boolean;
-		protocol: "http" | "https";
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		protocol: "http" | "https";
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 		nodes?: string[] | undefined;
@@ -2263,12 +2318,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
 		system: "mongodb";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -2278,9 +2336,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
@@ -2296,8 +2351,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		tls?: boolean | undefined;
 		srv?: boolean | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2308,22 +2363,25 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		port: number | {
 			$env: string;
 		};
-		user?: string | {
+		password?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
+		user?: string | {
 			$env: string;
 		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
 		system: "elasticsearch";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -2333,14 +2391,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
 		rejectUnauthorized?: boolean | undefined;
 		timeout?: number | undefined;
+		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		statementTimeout?: number | undefined;
 		protocol?: "http" | "https" | undefined;
 		nodes?: string[] | undefined;
@@ -2351,7 +2407,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		caPath?: string | undefined;
-		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	}>>;
@@ -2452,6 +2507,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		schemaTableCount?: number | undefined;
 	};
 	connections: Record<string, {
+		password: string | {
+			$env: string;
+		};
 		system: "postgresql" | "mysql" | "mariadb";
 		host: string | {
 			$env: string;
@@ -2462,9 +2520,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2474,6 +2529,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "mongodb";
 		host: string | {
 			$env: string;
@@ -2484,9 +2542,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2507,6 +2562,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "redis";
 		host: string | {
 			$env: string;
@@ -2517,9 +2575,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2529,6 +2584,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "elasticsearch";
 		host: string | {
 			$env: string;
@@ -2539,15 +2597,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
 		rejectUnauthorized: boolean;
-		protocol: "http" | "https";
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		protocol: "http" | "https";
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 		nodes?: string[] | undefined;
@@ -2589,12 +2644,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
 		system: "mongodb";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -2604,9 +2662,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
@@ -2622,8 +2677,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		tls?: boolean | undefined;
 		srv?: boolean | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2634,22 +2689,25 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		port: number | {
 			$env: string;
 		};
-		user?: string | {
+		password?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
+		user?: string | {
 			$env: string;
 		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
 		system: "elasticsearch";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -2659,14 +2717,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
 		rejectUnauthorized?: boolean | undefined;
 		timeout?: number | undefined;
+		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		statementTimeout?: number | undefined;
 		protocol?: "http" | "https" | undefined;
 		nodes?: string[] | undefined;
@@ -2677,7 +2733,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		caPath?: string | undefined;
-		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	}>;
@@ -2728,6 +2783,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		schemaTableCount?: number | undefined;
 	};
 	connections: Record<string, {
+		password: string | {
+			$env: string;
+		};
 		system: "postgresql" | "mysql" | "mariadb";
 		host: string | {
 			$env: string;
@@ -2738,9 +2796,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2750,6 +2805,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "mongodb";
 		host: string | {
 			$env: string;
@@ -2760,9 +2818,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2783,6 +2838,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "redis";
 		host: string | {
 			$env: string;
@@ -2793,9 +2851,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
@@ -2805,6 +2860,9 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
+		password: string | {
+			$env: string;
+		};
 		system: "elasticsearch";
 		host: string | {
 			$env: string;
@@ -2815,15 +2873,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user: string | {
 			$env: string;
 		};
-		password: string | {
-			$env: string;
-		};
 		database: string | {
 			$env: string;
 		};
 		rejectUnauthorized: boolean;
-		protocol: "http" | "https";
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		protocol: "http" | "https";
 		timeout?: number | undefined;
 		statementTimeout?: number | undefined;
 		nodes?: string[] | undefined;
@@ -2865,12 +2920,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
 		system: "mongodb";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -2880,9 +2938,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
@@ -2898,8 +2953,8 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		tls?: boolean | undefined;
 		srv?: boolean | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
@@ -2910,22 +2965,25 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		port: number | {
 			$env: string;
 		};
-		user?: string | {
+		password?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
+		user?: string | {
 			$env: string;
 		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
 		timeout?: number | undefined;
-		statementTimeout?: number | undefined;
 		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
+		statementTimeout?: number | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	} | {
 		system: "elasticsearch";
+		password?: string | {
+			$env: string;
+		} | undefined;
 		host?: string | {
 			$env: string;
 		} | undefined;
@@ -2935,14 +2993,12 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		user?: string | {
 			$env: string;
 		} | undefined;
-		password?: string | {
-			$env: string;
-		} | undefined;
 		database?: string | {
 			$env: string;
 		} | undefined;
 		rejectUnauthorized?: boolean | undefined;
 		timeout?: number | undefined;
+		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		statementTimeout?: number | undefined;
 		protocol?: "http" | "https" | undefined;
 		nodes?: string[] | undefined;
@@ -2953,7 +3009,6 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			$env: string;
 		} | undefined;
 		caPath?: string | undefined;
-		permission?: "admin" | "query-only" | "read-write" | "data-admin" | undefined;
 		envFile?: string | undefined;
 		environment?: string | undefined;
 	}>;
@@ -3105,7 +3160,7 @@ export declare class DataExecutor {
 	private getQuoteChar;
 	private checkBlacklist;
 	private executeMutation;
-	private successResult;
+	private outcomeResult;
 	private handleMutationError;
 	/**
 	 * Build a parameterized UPDATE SQL statement
@@ -3372,8 +3427,6 @@ export type SqlSystem = "postgresql" | "mysql" | "mariadb";
  * 且 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;
@@ -3395,6 +3448,30 @@ 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;
+/**
+ * 單一連線的密碼輪替：只動該連線的密碼，其餘設定原封不動。
+ *
+ * 密碼實際落在哪裡由 config 決定，不是靠命名規則猜的——
+ * 連線若已用 `{ $env: NAME }`，就改寫 NAME 這個 key；若還是明文，
+ * 先把 config 轉成 env 參照再寫檔，之後的輪替就不必再碰 config.json。
+ */
+export interface PasswordTarget {
+	/** 被更新的連線名稱 */
+	connection: string;
+	/** 密碼寫入的 env 檔（相對於 config storage 目錄） */
+	envFile: string;
+	/** 寫入的環境變數名稱 */
+	varName: string;
+	/** 這次是否需要把 config 裡的明文密碼轉成 $env 參照 */
+	convertedToEnvRef: boolean;
+}
+/**
+ * 查出「這條連線的密碼該寫到哪個 env 檔的哪個 key」，不寫入任何檔案。
+ *
+ * 驗證新密碼時得先知道 key 名稱才能注入，所以查詢與寫入分開。
+ */
+export declare function resolvePasswordTarget(projectPath: string, connectionName?: string): Promise<PasswordTarget>;
+export declare function setConnectionPassword(projectPath: string, connectionName: string | undefined, password: string): Promise<PasswordTarget>;
 /**
  * Resolve the per-user dbcli root lazily so embedders and tests can provide an
  * isolated config home without reloading the module. `DBCLI_CONFIG_HOME` is a