@proteinjs/db-driver-knex 1.13.9 → 1.14.0

package/generated/test/index.ts

@@ -8,7 +8,7 @@ import '@proteinjs/logger';
 /** Generate Source Graph */
 
 const sourceGraph =
-  '{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"@proteinjs/db-driver-knex/TestDbDriverFactory","value":{"packageName":"@proteinjs/db-driver-knex","name":"TestDbDriverFactory","filePath":"test/config/TestDbDriverFactory.ts","qualifiedName":"@proteinjs/db-driver-knex/TestDbDriverFactory","isAbstract":false,"isStatic":false,"visibility":"public","properties":[],"methods":[{"name":"getDbDriver","returnType":{"packageName":"@proteinjs/db","name":"DbDriver","filePath":null,"qualifiedName":"@proteinjs/db/DbDriver","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"DefaultDbDriverFactory","filePath":null,"qualifiedName":"@proteinjs/db/DefaultDbDriverFactory","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/DefaultDbDriverFactory"},{"v":"@proteinjs/db-driver-knex/KnexDriver","value":{"packageName":"@proteinjs/db-driver-knex","name":"KnexDriver","filePath":"src/KnexDriver.ts","qualifiedName":"@proteinjs/db-driver-knex/KnexDriver","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"KNEX","type":{"packageName":"","name":"knex","filePath":null,"qualifiedName":"/knex","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"logger","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"config","type":{"packageName":"@proteinjs/db-driver-knex","name":"KnexConfig","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/KnexConfig","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"knexConfig","type":{"packageName":"","name":"any","filePath":null,"qualifiedName":"/any","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"getTable","type":{"packageName":"","name":"((name: string) => Table<any>) | undefined","filePath":null,"qualifiedName":"/((name: string) => Table<any>) | undefined","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[{"name":"getKnex","returnType":{"packageName":"","name":"knex","filePath":null,"qualifiedName":"/knex","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"getDbName","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"createDbIfNotExists","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"createDb","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"name","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"options","type":{"packageName":"@proteinjs/db-driver-knex","name":"{ ddl?: string[] }","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/{ ddl?: string[] }","typeParameters":null,"directParents":null}}]},{"name":"dropDb","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"name","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}}]},{"name":"dbExists","returnType":{"packageName":"","name":"Promise<boolean>","filePath":null,"qualifiedName":"/Promise<boolean>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"databaseName","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}}]},{"name":"start","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"stop","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"setMaxAllowedPacketSize","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[]},{"name":"getTableManager","returnType":{"packageName":"@proteinjs/db","name":"TableManager","filePath":null,"qualifiedName":"@proteinjs/db/TableManager","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"handleCaseSensitivity","returnType":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"tableName","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"columnName","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"caseSensitive","type":{"packageName":"","name":"boolean","filePath":null,"qualifiedName":"/boolean","typeParameters":null,"directParents":null}}]},{"name":"runQuery","returnType":{"packageName":"","name":"Promise<SerializedRecord[]>","filePath":null,"qualifiedName":"/Promise<SerializedRecord[]>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"generateStatement","type":{"packageName":"","name":"(config: DbDriverQueryStatementConfig) => Statement","filePath":null,"qualifiedName":"/(config: DbDriverQueryStatementConfig) => Statement","typeParameters":null,"directParents":null}},{"name":"transaction","type":{"packageName":"knex","name":"Transaction","filePath":null,"qualifiedName":"knex/Transaction","typeParameters":null,"directParents":null}}]},{"name":"runDml","returnType":{"packageName":"","name":"Promise<number>","filePath":null,"qualifiedName":"/Promise<number>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"generateStatement","type":{"packageName":"","name":"(config: DbDriverDmlStatementConfig) => Statement","filePath":null,"qualifiedName":"/(config: DbDriverDmlStatementConfig) => Statement","typeParameters":null,"directParents":null}},{"name":"transaction","type":{"packageName":"knex","name":"Transaction","filePath":null,"qualifiedName":"knex/Transaction","typeParameters":null,"directParents":null}}]},{"name":"runTransaction","returnType":{"packageName":"","name":"Promise<T>","filePath":null,"qualifiedName":"/Promise<T>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"fn","type":{"packageName":"","name":"(transaction: Transaction) => Promise<T>","filePath":null,"qualifiedName":"/(transaction: Transaction) => Promise<T>","typeParameters":null,"directParents":null}}]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"DbDriver","filePath":null,"qualifiedName":"@proteinjs/db/DbDriver","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/DbDriver"},{"v":"@proteinjs/db-driver-knex/KnexSchemaOperations","value":{"packageName":"@proteinjs/db-driver-knex","name":"KnexSchemaOperations","filePath":"src/KnexSchemaOperations.ts","qualifiedName":"@proteinjs/db-driver-knex/KnexSchemaOperations","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"logger","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"knexDriver","type":{"packageName":"@proteinjs/db-driver-knex","name":"KnexDriver","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/KnexDriver","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"}],"methods":[{"name":"createTables","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"tables","type":{"packageName":"","name":"Table<any>[]","filePath":null,"qualifiedName":"/Table<any>[]","typeParameters":null,"directParents":null}}]},{"name":"createTable","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"table","type":{"packageName":"","name":"Table<any>","filePath":null,"qualifiedName":"/Table<any>","typeParameters":null,"directParents":null}}]},{"name":"alterTable","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"table","type":{"packageName":"","name":"Table<any>","filePath":null,"qualifiedName":"/Table<any>","typeParameters":null,"directParents":null}},{"name":"tableChanges","type":{"packageName":"@proteinjs/db","name":"TableChanges","filePath":null,"qualifiedName":"@proteinjs/db/TableChanges","typeParameters":null,"directParents":null}}]},{"name":"createColumn","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"column","type":{"packageName":"","name":"Column<any, any>","filePath":null,"qualifiedName":"/Column<any, any>","typeParameters":null,"directParents":null}},{"name":"table","type":{"packageName":"","name":"Table<any>","filePath":null,"qualifiedName":"/Table<any>","typeParameters":null,"directParents":null}},{"name":"tableBuilder","type":{"packageName":"","name":"knex.TableBuilder","filePath":null,"qualifiedName":"/knex.TableBuilder","typeParameters":null,"directParents":null}},{"name":"tableChanges","type":{"packageName":"@proteinjs/db","name":"TableChanges","filePath":null,"qualifiedName":"@proteinjs/db/TableChanges","typeParameters":null,"directParents":null}}]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"SchemaOperations","filePath":null,"qualifiedName":"@proteinjs/db/SchemaOperations","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/SchemaOperations"}],"edges":[{"v":"@proteinjs/db-driver-knex/TestDbDriverFactory","w":"@proteinjs/db/DefaultDbDriverFactory","value":"implements interface"},{"v":"@proteinjs/db-driver-knex/KnexDriver","w":"@proteinjs/db/DbDriver","value":"implements interface"},{"v":"@proteinjs/db-driver-knex/KnexSchemaOperations","w":"@proteinjs/db/SchemaOperations","value":"implements interface"}]}';
+  '{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"@proteinjs/db-driver-knex/TestDbDriverFactory","value":{"packageName":"@proteinjs/db-driver-knex","name":"TestDbDriverFactory","filePath":"test/config/TestDbDriverFactory.ts","qualifiedName":"@proteinjs/db-driver-knex/TestDbDriverFactory","isAbstract":false,"isStatic":false,"visibility":"public","properties":[],"methods":[{"name":"getDbDriver","returnType":{"packageName":"@proteinjs/db","name":"DbDriver","filePath":null,"qualifiedName":"@proteinjs/db/DbDriver","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"DefaultDbDriverFactory","filePath":null,"qualifiedName":"@proteinjs/db/DefaultDbDriverFactory","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/DefaultDbDriverFactory"},{"v":"@proteinjs/db-driver-knex/KnexDriver","value":{"packageName":"@proteinjs/db-driver-knex","name":"KnexDriver","filePath":"src/KnexDriver.ts","qualifiedName":"@proteinjs/db-driver-knex/KnexDriver","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"KNEX","type":{"packageName":"","name":"knex","filePath":null,"qualifiedName":"/knex","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"logger","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"config","type":{"packageName":"@proteinjs/db-driver-knex","name":"KnexConfig","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/KnexConfig","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"knexConfig","type":{"packageName":"","name":"any","filePath":null,"qualifiedName":"/any","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"getTable","type":{"packageName":"","name":"((name: string) => Table<any>) | undefined","filePath":null,"qualifiedName":"/((name: string) => Table<any>) | undefined","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[{"name":"getKnex","returnType":{"packageName":"","name":"knex","filePath":null,"qualifiedName":"/knex","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"getDbName","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"createDbIfNotExists","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"createDb","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"name","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"options","type":{"packageName":"@proteinjs/db-driver-knex","name":"{ ddl?: string[] }","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/{ ddl?: string[] }","typeParameters":null,"directParents":null}}]},{"name":"dropDb","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"name","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}}]},{"name":"dbExists","returnType":{"packageName":"","name":"Promise<boolean>","filePath":null,"qualifiedName":"/Promise<boolean>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"databaseName","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}}]},{"name":"start","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"stop","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"setMaxAllowedPacketSize","returnType":{"packageName":"","name":"Promise<void>","filePath":null,"qualifiedName":"/Promise<void>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[]},{"name":"getTableManager","returnType":{"packageName":"@proteinjs/db","name":"TableManager","filePath":null,"qualifiedName":"@proteinjs/db/TableManager","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"handleCaseSensitivity","returnType":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"tableName","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"columnName","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"caseSensitive","type":{"packageName":"","name":"boolean","filePath":null,"qualifiedName":"/boolean","typeParameters":null,"directParents":null}}]},{"name":"runQuery","returnType":{"packageName":"","name":"Promise<SerializedRecord[]>","filePath":null,"qualifiedName":"/Promise<SerializedRecord[]>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"generateStatement","type":{"packageName":"","name":"(config: DbDriverQueryStatementConfig) => Statement","filePath":null,"qualifiedName":"/(config: DbDriverQueryStatementConfig) => Statement","typeParameters":null,"directParents":null}},{"name":"transaction","type":{"packageName":"knex","name":"Transaction","filePath":null,"qualifiedName":"knex/Transaction","typeParameters":null,"directParents":null}}]},{"name":"runDml","returnType":{"packageName":"","name":"Promise<number>","filePath":null,"qualifiedName":"/Promise<number>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"generateStatement","type":{"packageName":"","name":"(config: DbDriverDmlStatementConfig) => Statement","filePath":null,"qualifiedName":"/(config: DbDriverDmlStatementConfig) => Statement","typeParameters":null,"directParents":null}},{"name":"transaction","type":{"packageName":"knex","name":"Transaction","filePath":null,"qualifiedName":"knex/Transaction","typeParameters":null,"directParents":null}}]},{"name":"runTransaction","returnType":{"packageName":"","name":"Promise<T>","filePath":null,"qualifiedName":"/Promise<T>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"fn","type":{"packageName":"","name":"(transaction: Transaction) => Promise<T>","filePath":null,"qualifiedName":"/(transaction: Transaction) => Promise<T>","typeParameters":null,"directParents":null}}]},{"name":"logFailure","returnType":{"packageName":"","name":"void","filePath":null,"qualifiedName":"/void","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"sql","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}},{"name":"params","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}},{"name":"error","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}}]},{"name":"writeStatementLine","returnType":{"packageName":"","name":"void","filePath":null,"qualifiedName":"/void","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"write","type":{"packageName":"","name":"() => void","filePath":null,"qualifiedName":"/() => void","typeParameters":null,"directParents":null}}]},{"name":"causeSummary","returnType":{"packageName":"@proteinjs/db-driver-knex","name":"FailureCauseSummary","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/FailureCauseSummary","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"error","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}}]},{"name":"describeParams","returnType":{"packageName":"","name":"ParamsDescription | undefined","filePath":null,"qualifiedName":"/ParamsDescription | undefined","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"params","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}}]},{"name":"describeParam","returnType":{"packageName":"@proteinjs/db-driver-knex","name":"ParamDescription","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/ParamDescription","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"read","type":{"packageName":"","name":"() => unknown","filePath":null,"qualifiedName":"/() => unknown","typeParameters":null,"directParents":null}}]},{"name":"paramKind","returnType":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"value","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}}]},{"name":"isDictionary","returnType":{"packageName":"","name":"params is { [name: string]: unknown }","filePath":null,"qualifiedName":"/params is { [name: string]: unknown }","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"params","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}}]},{"name":"vendorFact","returnType":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"error","type":{"packageName":"","name":"unknown","filePath":null,"qualifiedName":"/unknown","typeParameters":null,"directParents":null}},{"name":"fact","type":{"packageName":"","name":"keyof FailureCauseSummary","filePath":null,"qualifiedName":"/keyof FailureCauseSummary","typeParameters":null,"directParents":null}}]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"DbDriver","filePath":null,"qualifiedName":"@proteinjs/db/DbDriver","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/DbDriver"},{"v":"@proteinjs/db-driver-knex/KnexSchemaOperations","value":{"packageName":"@proteinjs/db-driver-knex","name":"KnexSchemaOperations","filePath":"src/KnexSchemaOperations.ts","qualifiedName":"@proteinjs/db-driver-knex/KnexSchemaOperations","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"logger","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"knexDriver","type":{"packageName":"@proteinjs/db-driver-knex","name":"KnexDriver","filePath":null,"qualifiedName":"@proteinjs/db-driver-knex/KnexDriver","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"}],"methods":[{"name":"createTables","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"tables","type":{"packageName":"","name":"Table<any>[]","filePath":null,"qualifiedName":"/Table<any>[]","typeParameters":null,"directParents":null}}]},{"name":"createTable","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"table","type":{"packageName":"","name":"Table<any>","filePath":null,"qualifiedName":"/Table<any>","typeParameters":null,"directParents":null}}]},{"name":"alterTable","returnType":null,"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"table","type":{"packageName":"","name":"Table<any>","filePath":null,"qualifiedName":"/Table<any>","typeParameters":null,"directParents":null}},{"name":"tableChanges","type":{"packageName":"@proteinjs/db","name":"TableChanges","filePath":null,"qualifiedName":"@proteinjs/db/TableChanges","typeParameters":null,"directParents":null}}]},{"name":"createColumn","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[{"name":"column","type":{"packageName":"","name":"Column<any, any>","filePath":null,"qualifiedName":"/Column<any, any>","typeParameters":null,"directParents":null}},{"name":"table","type":{"packageName":"","name":"Table<any>","filePath":null,"qualifiedName":"/Table<any>","typeParameters":null,"directParents":null}},{"name":"tableBuilder","type":{"packageName":"","name":"knex.TableBuilder","filePath":null,"qualifiedName":"/knex.TableBuilder","typeParameters":null,"directParents":null}},{"name":"tableChanges","type":{"packageName":"@proteinjs/db","name":"TableChanges","filePath":null,"qualifiedName":"@proteinjs/db/TableChanges","typeParameters":null,"directParents":null}}]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"SchemaOperations","filePath":null,"qualifiedName":"@proteinjs/db/SchemaOperations","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/SchemaOperations"}],"edges":[{"v":"@proteinjs/db-driver-knex/TestDbDriverFactory","w":"@proteinjs/db/DefaultDbDriverFactory","value":"implements interface"},{"v":"@proteinjs/db-driver-knex/KnexDriver","w":"@proteinjs/db/DbDriver","value":"implements interface"},{"v":"@proteinjs/db-driver-knex/KnexSchemaOperations","w":"@proteinjs/db/SchemaOperations","value":"implements interface"}]}';
 
 /** Generate Source Links */
 

package/index.ts

@@ -1,2 +1,3 @@
 export * from './src/KnexDriver';
 export * from './src/KnexConfig';
+export * from './src/KnexLogValues';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db-driver-knex",
-  "version": "1.13.9",
+  "version": "1.14.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,9 +41,9 @@
     "test": "jest --runInBand --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db": "^1.47.1",
+    "@proteinjs/db": "^1.47.2",
     "@proteinjs/db-query": "^1.10.1",
-    "@proteinjs/db-transaction-context": "^0.5.33",
+    "@proteinjs/db-transaction-context": "^0.5.34",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/util": "^1.6.1",
@@ -67,5 +67,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "ad0e3db9563d9be4277af86e6c942d7ae4d811f6"
+  "gitHead": "5811ffac3d235bce810460223eaa567b9f36a3a6"
 }

package/src/KnexDriver.ts

@@ -9,11 +9,24 @@ import {
   tableByName,
 } from '@proteinjs/db';
 import { KnexConfig } from './KnexConfig';
+import { KnexLogValues } from './KnexLogValues';
 import { Logger } from '@proteinjs/logger';
 import { Statement } from '@proteinjs/db-query';
 import { KnexSchemaOperations } from './KnexSchemaOperations';
 import { KnexColumnTypeFactory } from './KnexColumnTypeFactory';
 
+/** A bound parameter as a log line carries it (see KnexDriver.describeParams): never its value. */
+type ParamDescription = { type: string; length?: number; null?: true };
+
+/**
+ * A statement's bindings as a log line carries them: positional bindings by position, a bindings
+ * dictionary by entry name — or the one word for bindings that could not be read at all.
+ */
+type ParamsDescription = ParamDescription[] | { [name: string]: ParamDescription } | 'unreadable';
+
+/** A failure as the log line carries it: the error's name, the vendor's codes and the server's own message. */
+type FailureCauseSummary = { name?: string; code?: string; errno?: number; sqlState?: string; sqlMessage?: string };
+
 /**
  * Knex driver (configured for MariaDb) for ProteinJs Db
  */
@@ -160,8 +173,8 @@ export class KnexDriver implements DbDriver {
     try {
       const runner = transaction || this.getKnex();
       return (await runner.raw(sql, params as any))[0]; // returns 2 arrays, first is records, second is metadata per record
-    } catch (error: any) {
-      this.logger.error({ message: `Failed when executing sql`, obj: { sql }, error });
+    } catch (error: unknown) {
+      this.logFailure(sql, params, error);
       throw error;
     }
   }
@@ -185,4 +198,180 @@ export class KnexDriver implements DbDriver {
       return result;
     });
   }
+
+  /**
+   * The one line a failed statement writes. What is THROWN is the vendor's error itself, untouched
+   * (runQuery rethrows it); this is only what the driver PRINTS of it.
+   *
+   * The vendor error is not safe to print as it is: the query layer rewrites a failed query's
+   * `message` to the SQL with its bindings INTERPOLATED, and the client library's error carries
+   * the same formatted text as `sql` — every bound value of the statement, on any line the error
+   * reaches. So the line carries the SQL text (placeholders only), the parameters DESCRIBED
+   * (describeParams) and a summary of the failure: the error's name, the vendor's codes and the
+   * server's own message (`sqlMessage` — which can itself quote a value, e.g. a colliding key; the
+   * driver prints it as it always has). The vendor error itself, and the values as bound, ride
+   * the line only behind the dev-only switch (KnexLogValues).
+   *
+   * `params` is whatever the statement carried. `Statement` types it as an array, but the query
+   * layer also accepts a bindings dictionary (and wraps anything else as one binding), and
+   * runQuery forwards what it was handed — so nothing here may assume a shape. The line is
+   * written through writeStatementLine: it sits on the way to a `throw`, and must never be the
+   * reason something else is thrown.
+   */
+  private logFailure(sql: string, params: unknown, error: unknown): void {
+    this.writeStatementLine(() =>
+      this.logger.error({
+        message: `Failed when executing sql`,
+        obj: {
+          sql,
+          params: this.describeParams(params),
+          ...KnexLogValues.ofStatement(params),
+          cause: this.causeSummary(error),
+        },
+        ...KnexLogValues.ofFailure(error),
+      })
+    );
+  }
+
+  /**
+   * The ONE door a statement's log line is written through — the owner of the rule that writing
+   * a line can NEVER change what the driver throws. A statement line is written on the way to a
+   * `throw`, so whatever goes wrong while building or writing it — a log writer that is down, a
+   * serializer meeting a value it cannot print (a bigint or a throwing `toJSON`, under the values
+   * switch), a helper meeting a shape nobody foresaw — is caught HERE and reported as one FIXED
+   * line that carries nothing of the statement; the caller then throws exactly what it was going
+   * to throw. If the logger itself is what failed, the fixed line fails too and is dropped:
+   * nothing is left to write with.
+   */
+  private writeStatementLine(write: () => void): void {
+    try {
+      write();
+    } catch {
+      try {
+        this.logger.error({ message: `Failed to write a statement log line` });
+      } catch {
+        // The logger itself is what failed: nothing is left to write with, and nothing here may throw.
+      }
+    }
+  }
+
+  /**
+   * The name, codes and server message of any thrown value — never the query layer's rewritten
+   * `message` or `sql`. Total: a fact that cannot be read (vendorFact) is left out.
+   */
+  private causeSummary(error: unknown): FailureCauseSummary {
+    const name = this.vendorFact(error, 'name');
+    const code = this.vendorFact(error, 'code');
+    const errno = this.vendorFact(error, 'errno');
+    const sqlState = this.vendorFact(error, 'sqlState');
+    const sqlMessage = this.vendorFact(error, 'sqlMessage');
+    return {
+      ...(typeof name === 'string' ? { name } : {}),
+      ...(typeof code === 'string' ? { code } : {}),
+      ...(typeof errno === 'number' ? { errno } : {}),
+      ...(typeof sqlState === 'string' ? { sqlState } : {}),
+      ...(typeof sqlMessage === 'string' ? { sqlMessage } : {}),
+    };
+  }
+
+  /**
+   * A statement's bound parameters as a LOG LINE carries them — the one owner of that form: by
+   * position, the KIND of each value and, for strings, arrays and bytes, its LENGTH. Never a
+   * value: a parameter is row content (a presented token, a credential hash, an address), and a
+   * log line outlives and out-travels the row it came from. The SQL text beside it carries `?`
+   * placeholders only, so position + kind + length is what locates a failure (which parameter was
+   * null, which was oversized) without quoting it.
+   *
+   * The shapes are the query layer's own: positional bindings (an array) are described by
+   * POSITION; a bindings DICTIONARY (a plain object, bound to `:name` placeholders) by entry
+   * NAME; no bindings describe nothing; and anything else — null, a scalar, a Map, a Date — is
+   * what the query layer binds as ONE parameter, so it is described as one.
+   *
+   * TOTAL, for any input: a value that cannot be read is described as `unreadable`
+   * (describeParam), and bindings that cannot even be walked are the one word `unreadable`.
+   */
+  private describeParams(params?: unknown): ParamsDescription | undefined {
+    if (params === undefined) {
+      return undefined;
+    }
+    try {
+      if (Array.isArray(params)) {
+        const described: ParamDescription[] = [];
+        for (let position = 0; position < params.length; position++) {
+          described.push(this.describeParam(() => params[position]));
+        }
+        return described;
+      }
+      if (this.isDictionary(params)) {
+        const described: { [name: string]: ParamDescription } = {};
+        for (const name of Object.keys(params)) {
+          described[name] = this.describeParam(() => params[name]);
+        }
+        return described;
+      }
+      return [this.describeParam(() => params)];
+    } catch {
+      return 'unreadable';
+    }
+  }
+
+  /**
+   * One bound value, described: its kind, a length for strings, arrays and bytes, null named. The
+   * value is READ in here (`read`), so a read that throws — an accessor, a revoked proxy — is
+   * described as `unreadable` and its neighbours still are described. A length that is not a
+   * number is no length: nothing a value says about itself rides the line but that one number.
+   */
+  private describeParam(read: () => unknown): ParamDescription {
+    try {
+      const value = read();
+      const description: ParamDescription = { type: this.paramKind(value) };
+      if (typeof value === 'string' || Array.isArray(value) || value instanceof Uint8Array) {
+        const length: unknown = value.length;
+        if (typeof length === 'number') {
+          description.length = length;
+        }
+      }
+      if (value === null || value === undefined) {
+        description.null = true;
+      }
+      return description;
+    } catch {
+      return { type: 'unreadable' };
+    }
+  }
+
+  /** The kind of a bound value — a word, never the value. */
+  private paramKind(value: unknown): string {
+    if (value === null || value === undefined) {
+      return 'null';
+    }
+    if (Array.isArray(value)) {
+      return 'array';
+    }
+    if (value instanceof Date) {
+      return 'date';
+    }
+    if (value instanceof Uint8Array) {
+      return 'bytes';
+    }
+    return typeof value;
+  }
+
+  /** Whether bindings are a DICTIONARY — a plain object, which the query layer binds by entry name. */
+  private isDictionary(params: unknown): params is { [name: string]: unknown } {
+    if (typeof params !== 'object' || params === null) {
+      return false;
+    }
+    const prototype = Object.getPrototypeOf(params);
+    return prototype === null || Object.getPrototypeOf(prototype) === null;
+  }
+
+  /** One fact of a thrown value, or nothing when it cannot be read (nothing thrown, a scalar, a throwing accessor). */
+  private vendorFact(error: unknown, fact: keyof FailureCauseSummary): unknown {
+    try {
+      return (error as { [fact: string]: unknown } | null | undefined)?.[fact];
+    } catch {
+      return undefined;
+    }
+  }
 }

package/src/KnexLogValues.ts

@@ -0,0 +1,42 @@
+/**
+ * The ONE owner of the dev-only switch that lets the driver's failure line carry the REAL values
+ * of a statement's bound parameters, and of the fields that carry them.
+ *
+ * By default the line carries no bound value: the parameters are described
+ * (KnexDriver.describeParams — positions, kinds, lengths) and the failure is summarized by the
+ * vendor's codes and the server's own message — never by the vendor error itself, whose `message`
+ * the query layer rewrites to the SQL with every binding INTERPOLATED (and whose `sql` is the
+ * same text). A parameter is row content, and a log line outlives and out-travels the row it came
+ * from. A local dev database holds nothing that needs that protection, and there the values are
+ * what locates a bug. So the switch: when BOTH `DEVELOPMENT` is set (the dev-server switch, never
+ * set in a production image) AND `DB_LOG_PARAM_VALUES=1`, the line adds `paramValues` — the
+ * parameters as they were bound — and carries the vendor error itself as `error`. With either
+ * unset: never. Both are read at each line, so a process cannot hold a stale answer.
+ *
+ * The switch adds FIELDS to a log line and changes nothing else: what the driver throws is the
+ * same with the switch on or off.
+ */
+export class KnexLogValues {
+  /** The dev-server switch: the first gate. */
+  static readonly DEVELOPMENT_VAR = 'DEVELOPMENT';
+  /** The values switch: the second gate, on only as exactly `1`. */
+  static readonly SWITCH_VAR = 'DB_LOG_PARAM_VALUES';
+
+  /** Whether lines may carry real values right now — both gates, read now. */
+  static enabled(): boolean {
+    return !!process.env[KnexLogValues.DEVELOPMENT_VAR] && process.env[KnexLogValues.SWITCH_VAR] === '1';
+  }
+
+  /**
+   * What a statement's line adds beside its described parameters: `{ paramValues }` — the bindings
+   * as the statement carried them, positional or a bindings dictionary — or nothing.
+   */
+  static ofStatement(params: unknown): { paramValues?: unknown } {
+    return KnexLogValues.enabled() && params !== undefined ? { paramValues: params } : {};
+  }
+
+  /** What a failure's line carries beside its cause summary: the vendor error itself as `{ error }`, or nothing. */
+  static ofFailure(error: unknown): { error?: unknown } {
+    return KnexLogValues.enabled() ? { error } : {};
+  }
+}

package/test/LogValuesSwitch.test.ts

@@ -0,0 +1,201 @@
+import knex from 'knex';
+import { KnexDriver, KnexLogValues } from '@proteinjs/db-driver-knex';
+import { Logger } from '@proteinjs/logger';
+import { CapturedLog, lineOf } from './util/printedLine';
+
+/**
+ * The dev-only values switch (`KnexLogValues`): the driver's failure line carries the REAL values
+ * of the bound parameters — `paramValues`, and the vendor error itself as `error` — only when BOTH
+ * `DEVELOPMENT` is set AND `DB_LOG_PARAM_VALUES=1`. With either gate closed: never.
+ *
+ * By default the line describes the parameters and summarizes the failure
+ * (StatementParamLogging.test.ts holds that). On a local dev database the values are what locates
+ * a bug, so there — and only there — the line adds them, beside the description, which stays. What
+ * a caller CATCHES is the same error whatever the switch says: the switch adds fields to a line
+ * and changes nothing else.
+ *
+ * No server is needed: the REAL query layer and dialect run over a stub connection that rejects
+ * the way the client library does. The stub server's message quotes no bound value: what the
+ * SERVER echoes is not this switch's subject (see StatementParamLogging.test.ts's header).
+ */
+
+// A fixture value shaped like row content (not a real credential).
+const VALUE = 'rst_5d41402abc4b2a76b9719d911017c592';
+
+type DriverInternals = { logger: Logger };
+type DriverStatics = { KNEX?: unknown };
+
+/** A connection that rejects every statement like a missing table — a server message that quotes no binding. */
+const rejectingConnection = () => {
+  const mysql = require('mysql');
+  return {
+    state: 'authenticated',
+    on: () => undefined,
+    removeAllListeners: () => undefined,
+    connect: (done: (error?: Error) => void) => done(),
+    end: (done: (error?: Error) => void) => done(),
+    query: (options: { sql: string }, bindings: any[], done: (error: Error) => void) => {
+      const sqlMessage = `Table 'test.credential' doesn't exist`;
+      done(
+        Object.assign(new Error(`ER_NO_SUCH_TABLE: ${sqlMessage}`), {
+          code: 'ER_NO_SUCH_TABLE',
+          errno: 1146,
+          sqlState: '42S02',
+          sqlMessage,
+          sql: mysql.format(options.sql, bindings),
+        })
+      );
+    },
+  };
+};
+
+const GATES: [string, { [name: string]: string }, boolean][] = [
+  ['DEVELOPMENT set AND DB_LOG_PARAM_VALUES=1', { DEVELOPMENT: 'true', DB_LOG_PARAM_VALUES: '1' }, true],
+  ['DEVELOPMENT unset, DB_LOG_PARAM_VALUES=1', { DB_LOG_PARAM_VALUES: '1' }, false],
+  ['DEVELOPMENT empty, DB_LOG_PARAM_VALUES=1', { DEVELOPMENT: '', DB_LOG_PARAM_VALUES: '1' }, false],
+  ['DEVELOPMENT set, DB_LOG_PARAM_VALUES unset', { DEVELOPMENT: 'true' }, false],
+  [
+    'DEVELOPMENT set, DB_LOG_PARAM_VALUES=true (on only as exactly 1)',
+    { DEVELOPMENT: 'true', DB_LOG_PARAM_VALUES: 'true' },
+    false,
+  ],
+  ['DEVELOPMENT set, DB_LOG_PARAM_VALUES=0', { DEVELOPMENT: 'true', DB_LOG_PARAM_VALUES: '0' }, false],
+  ['neither set', {}, false],
+];
+
+describe('the dev-only values switch: real values ride the driver`s failure line only behind both gates', () => {
+  const driver = new KnexDriver({ host: 'localhost', user: 'root', password: '', dbName: 'test' });
+  const internals = driver as unknown as DriverInternals;
+  const statics = KnexDriver as unknown as DriverStatics;
+  const ENV = [KnexLogValues.DEVELOPMENT_VAR, KnexLogValues.SWITCH_VAR];
+  const envBefore: { [name: string]: string | undefined } = {};
+  let captured: CapturedLog[] = [];
+  let instance: ReturnType<typeof knex>;
+  let previousInstance: unknown;
+
+  beforeAll(() => {
+    instance = knex({ client: 'mysql', connection: { host: 'localhost', user: 'root', password: '' } });
+    (instance as any).client.driver = { createConnection: rejectingConnection };
+    previousInstance = statics.KNEX;
+    statics.KNEX = instance;
+    internals.logger = new Logger({
+      name: 'KnexDriver',
+      logLevel: 'debug',
+      logWriter: { write: (log: CapturedLog) => captured.push(log) } as any,
+    });
+  });
+
+  afterAll(async () => {
+    statics.KNEX = previousInstance;
+    await instance.destroy();
+  });
+
+  beforeEach(() => {
+    captured = [];
+    for (const name of ENV) {
+      envBefore[name] = process.env[name];
+      delete process.env[name];
+    }
+  });
+
+  afterEach(() => {
+    for (const name of ENV) {
+      if (envBefore[name] === undefined) {
+        delete process.env[name];
+      } else {
+        process.env[name] = envBefore[name];
+      }
+    }
+  });
+
+  const params = [VALUE, 42];
+  const failingInsert = (): Promise<any> =>
+    driver
+      .runDml(() => ({ sql: 'INSERT INTO `credential` (`id`, `n`) VALUES (?, ?)', params }))
+      .then(
+        () => 'resolved',
+        (error: unknown) => error
+      );
+  /** Everything a caller can read off a caught error. */
+  const facts = (error: any) => ({
+    class: error.constructor.name,
+    message: error.message,
+    own: Object.getOwnPropertyNames(error)
+      .sort()
+      .map((name) => [name, name === 'stack' ? '(stack)' : error[name]]),
+  });
+
+  test.each(GATES)('%s', async (_gate, env, on) => {
+    // The error a caller catches with the switch untouched — what every gate must reproduce.
+    const baseline = facts(await failingInsert());
+    captured = [];
+    Object.assign(process.env, env);
+
+    const caught = await failingInsert();
+
+    expect(KnexLogValues.enabled()).toBe(on);
+    const failures = captured.filter((log) => log.message === 'Failed when executing sql');
+    expect(failures).toHaveLength(1);
+    const [failure] = failures;
+    // What a caller catches is the same whatever the switch says.
+    expect(facts(caught)).toEqual(baseline);
+    // The description and the summary ride the line at every gate.
+    expect(failure.obj.params).toEqual([{ type: 'string', length: VALUE.length }, { type: 'number' }]);
+    expect(failure.obj.cause).toEqual({
+      name: 'Error',
+      code: 'ER_NO_SUCH_TABLE',
+      errno: 1146,
+      sqlState: '42S02',
+      sqlMessage: `Table 'test.credential' doesn't exist`,
+    });
+    if (!on) {
+      for (const log of captured) {
+        expect(lineOf(log)).not.toContain(VALUE);
+        expect(Object.keys(log.obj ?? {})).not.toContain('paramValues');
+        expect(log.error).toBeUndefined();
+      }
+      return;
+    }
+    // The values as bound, BESIDE the description; and the vendor error itself, as it was thrown.
+    expect(failure.obj.paramValues).toEqual(params);
+    expect(failure.error).toBe(caught);
+    expect(lineOf(failure)).toContain(VALUE);
+  });
+
+  // A bindings DICTIONARY — wider than `Statement` declares, and what the query layer accepts.
+  const namedParams = { id: VALUE, n: 42 };
+  const failingNamedInsert = (): Promise<any> =>
+    driver
+      .runDml(() => ({ sql: 'INSERT INTO `credential` (`id`, `n`) VALUES (:id, :n)', params: namedParams as any }))
+      .then(
+        () => 'resolved',
+        (error: unknown) => error
+      );
+
+  test.each(GATES)('a bindings dictionary rides the same switch — %s', async (_gate, env, on) => {
+    const baseline = facts(await failingNamedInsert());
+    captured = [];
+    Object.assign(process.env, env);
+
+    const caught = await failingNamedInsert();
+
+    const failures = captured.filter((log) => log.message === 'Failed when executing sql');
+    expect(failures).toHaveLength(1);
+    const [failure] = failures;
+    expect(caught.code).toBe('ER_NO_SUCH_TABLE');
+    expect(facts(caught)).toEqual(baseline);
+    // The description, by entry name, rides the line at every gate.
+    expect(failure.obj.params).toEqual({ id: { type: 'string', length: VALUE.length }, n: { type: 'number' } });
+    if (!on) {
+      for (const log of captured) {
+        expect(lineOf(log)).not.toContain(VALUE);
+        expect(Object.keys(log.obj ?? {})).not.toContain('paramValues');
+        expect(log.error).toBeUndefined();
+      }
+      return;
+    }
+    // The dictionary as bound, BESIDE the description; and the vendor error itself, as it was thrown.
+    expect(failure.obj.paramValues).toEqual(namedParams);
+    expect(failure.error).toBe(caught);
+  });
+});