abler-db

v1.0.116

Published

a day ago

数据库相关工具

Downloads

3,691

0High
0Medium
0Low

peng_peng

彭彭自用包：abler-db

数据库访问相关工具库

安装

npm i abler-db@latest -s

引用

const {db, dbUtil, Redis, redisSimulator, kvStorage} = require("abler-db");
dbUtil.config(conf, err);
kvStorage.config(conf, err).setRedis(new redisSimulator(dbSql));

更新日志

1.0.115

原来的分页控制参数 start, limit, orderBy 改为 _start, _limit, _order (为兼容，原参数名暂时保留)， _limit 不再强制要求排序参数。
增加 _logging 参数，可控制是否在日志中记录实际执行的SQL语句
若SQL语句中的查询条件是列名=:参数名的形式，实际传参时，可通过给参数名添加前缀或后缀(之一)来改变、添加条件，如下表：

| 前缀 | 后缀 | 含义 | | ---- | -------------------- | ------------------------------------------------------------ | | ! | _not | 条件取反，仅限原始参数名和_like后缀参数名，如：!name, !name_like | | * | _like | 模糊匹配 | | | _from , _min, _gte | >= | | | _gt | > | | | _to, _lt | < | | | _max, _lte | <= | | | _coi, _range | 半开区间 [a, b), COLUMN >= a and COLUMN < b | | | _oci | 半闭区间 (a, b], COLUMN > a and COLUMN <= b | | | _ooi | 全开区间 (a, b), COLUMN > a and COLUMN < b | | | _cci | 全闭区间 [a, b], COLUMN >= a and COLUMN <= b | | | s/es(复数形式), _arr | IN (废弃，可直接用原参数名传递数组参数值) |

【注1】前缀 ! 与后缀 _not 等价，前缀 * 和后缀 _like 等价，不要给一个参数同时添加等价的前缀和后缀。

【注2】区间参数表示数据位于区间之内，可以添加前缀！表示取反，即表示数据位于区间之外。

还可以传递数组参数值将单值比较改为多值比较，自动变IN/NOT IN，自动分离null产生合法条件语句等。

例如：SQL语句中的条件片段（单独一行）如下,可用多种方式传递参数，以生成不同的条件及其组合：

# SQL 条件片段
AND A.NAME = :name

| 参数名 | 参数值 | 最终执行的SQL条件片段 | | ---------- | ----------------------- | ------------------------------------------------------------ | | name | "张三" | AND A.NAME = '张三' | | | ["","null"] | AND (A.NAME = '' OR A.NAME IS NULL) | | | ["张三","李四"] | AND A.NAME IN ('张三','李四') | | | ["张三","李四", "null"] | AND (A.NAME IN ('张三','李四') OR A.NAME IS NULL) | | | | | | !name | "张三" | AND A.NAME <> '张三' | | | ["","null"] | AND (A.NAME <> '' AND A.NAME IS NOT NULL) | | | ["张三","李四"] | AND A.NAME NOT IN ('张三','李四') | | | ["张三","李四", "null"] | AND (A.NAME NOT IN ('张三','李四') AND A.NAME IS NOT NULL) | | | | | | name_like | "张" | AND A.NAME LIKE '%张%' | | | "张*" 或 "张%" | AND A.NAME LIKE '张%' | | | "张_" | AND A.NAME LIKE '张_' | | | ["张%","null"] | AND (A.NAME LIKE '张%' OR A.NAME IS NULL) | | | ["张%","李%"] | AND (A.NAME LIKE '张%' OR A.NAME LIKE '李%' ) | | | ["张%","李%", "null"] | AND (A.NAME LIKE '张%' OR A.NAME LIKE '李%' OR A.NAME IS NULL) | | | | | | !name_like | "张*" | AND A.NAME NOT LIKE '张%' | | | ["张%","null"] | AND (A.NAME NOT LIKE '张%' AND A.NAME IS NOT NULL) | | | .... | 其它类推 |

# SQL 条件片段
AND A.LST_UPD_DT = :updateTime

| 参数名 | 参数值 | 最终执行的SQL条件片段 | | ----------------- | ------------------------------------- | ------------------------------------------------------------ | | updateTime | "2026-04-29T03:52:18.000Z" | (MariaDB) AND A.LST_UPD_DT = '2026-04-29 11:52:18.000'(MySql) AND A.LST_UPD_DT = '2026-04-29 11:52:18' | | | "null" | AND A.LST_UPD_DT IS NULL | | updateTime_from | "2026.04.29" | AND A.LST_UPD_DT >= '2026.04.29' | | updateTime_to | "2026.04.30" | AND A.LST_UPD_DT < '2026.04.30' | | updateTime_gt | "2026.04.29" | AND A.LST_UPD_DT > '2026.04.29' | | updateTime_lte | "2026.04.30" | AND A.LST_UPD_DT <= '2026.04.30' | | updateTime_min | "2026.04.29" | AND A.LST_UPD_DT >= '2026.04.29' | | updateTime_max | "2026.04.30" | AND A.LST_UPD_DT <= '2026.04.30' | | | | | | updateTime_range | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT >= '2026.04.29' AND A.LST_UPD_DT < '2026.05.31') | | | ["2026.04.29","2026.05.31"] | AND (A.LST_UPD_DT >= '2026.04.29' AND A.LST_UPD_DT < '2026.05.31') | | updateTime_coi | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT >= '2026.04.29' AND A.LST_UPD_DT < '2026.05.31') | | updateTime_oci | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT > '2026.04.29' AND A.LST_UPD_DT <= '2026.05.31') | | updateTime_cci | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT >= '2026.04.29' AND A.LST_UPD_DT <= '2026.05.31') | | updateTime_ooi | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT > '2026.04.29' AND A.LST_UPD_DT < '2026.05.31') | | | | | | !updateTime_range | "2026.04.29 12:31:27.567, 2026.05.31" | AND (A.LST_UPD_DT < '2026.04.29 12:31:27.567' OR A.LST_UPD_DT >= '2026.05.31') | | !updateTime_coi | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT < '2026.04.29' OR A.LST_UPD_DT >= '2026.05.31') | | !updateTime_oci | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT <= '2026.04.29' OR A.LST_UPD_DT > '2026.05.31') | | !updateTime_cci | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT < '2026.04.29' OR A.LST_UPD_DT > '2026.05.31') | | !updateTime_ooi | "2026.04.29, 2026.05.31" | AND (A.LST_UPD_DT <= '2026.04.29' OR A.LST_UPD_DT >= '2026.05.31') | | | | | | updateTime_like | "2026-04-29*" | AND A.LST_UPD_DT LIKE '2026-04-29%' | | | | |

【注1】表格中的参数值以JSON格式描述，实际URL中传递时，字符串没有引号；数组是分别用多个同名参数传递每一个成员；

【注2】字符串“null”默认自动解析为null,若要需要实际使用字符串“null”，可通过参数 _null 指定使用其他字符串作为null值，如 _null = "NIL",则只有字符串“NIL”被解析为null值

若SQL语句中的查询条件是列名 IN :参数名的形式，而实际传参不是数组或者只有一个元素，则自动优化为单值比较

1.0.55

redisSimulator 增加 ttl 函数

1.0.53

SQL脚本可支持条件语句(以 -- @condition 开头)，条件语句返回结果求值为true时才执行下一条SQL

1.0.50

完善查询参数后缀规则与范围查询规范，like 自动添加通配符，可以用*代替%, [_from,_to] 修正为 [_from,_to），同时增加[_min,_max],_gt,_gte,_lt,_lte,_not

1.0.47

SQL查询条件根据参数自动添加 like, <> , >=, <=, in

1.0.43

重组SQL语句清理流程，修复Bug

1.0.40

SqlUtil cleanSqlBlock() 支持嵌套块

1.0.33

SqlLoader 改为 SqlUtil，装入SQL文件时支持 --$include 指令

1.0.32

增加 SqlLoader 类

1.0.28

redis包升级，修改配置，支持双向ssl连接

1.0.27

清理SQL语句的Where子句时，可以清除包含无效占位符的 OR (...) 条件了

1.0.26

Bug修复，解决执行SQL报错时找不到错误信息问题

1.0.25

完善dbUtil.executeScript，执行SQL脚本时跳过无有效SQL的语句

1.0.24

修复Bug: 解决数据库更新脚本为js时无法动态加载的问题

1.0.23

修复Bug

1.0.22

删除了没有用到的依赖

1.0.21

数据库版本升级脚本支持js

1.0.20

解决不同方言执行update和delete语句返回属性名称不同，从而导致获取作用行数失败的问题

1.0.13

修改达梦数据库方言：

查询返回结果 BLOB 字段自动返回数据到 Buffer
解决提交大型数据时，报 “跨事务挺重大数据” 问题

1.0.12

完善 DbVersionManager，实现在没有创建数据库的情况下，全自动完成从创建数据库开始的历次数据库版本更新，应用系统配合脚本检查可从安装开始全自动到达服务提供状态

完善 sequelizeCustomizer

1.0.10

执行SQL语句前，根据配置或参数数据类型确定 sequelize 参数传递方式（是否强制Bind参数）

1.0.3~1.09

废弃

1.0.2

增加 Sequelize 方言定制功能，支持达梦数据库，同时修正MySql相关代码，使之支持 createSchema ，tabelExists等函数

版本1.0.2更新注意事项

应用配置部分配置项改名

envSettings.xxx.dbname >> ...dbName
envSettings.xxx.dbuser >> ...dbUser

envSettingNotes.dbname >> ...dbName
envSettingNotes.dbuser >> ...dbUser

conf.dbconn  >>  conf.dbConf
conf.dbconn.dbname  >>  conf.dbConf.dbName
conf.dbconn.dbuser  >>  conf.dbConf.dbUser
envSetting.dbname  >>  envSetting.dbName
envSetting.dbuser  >>  envSetting.dbUser

关于 SQL 语句配置文件

之前的SQL语句是写在 config 目录中的 dbsql.js 的 class dbSql 中，没有区分数据库类型，现在要求 dbsql.js 输出一个 dbSqls 对象，按数据库类型组织SQL语句：

class dbSql_MySql {
    static API_LOG_QUERY = `
    SELECT    
        ID as id,
        ......
    FROM ~dbOwner~API_REQUEST_LOG
    WHERE true
        AND ID = :id
        ......
    `
}
class dbSql_dm {
    static API_LOG_QUERY = `
    SELECT
        ......
    `
}
const dbSqls = {
    MySql: dbSql_MySql,
    dm: dbSql_dm,
}
module.exports = dbSqls;

同时在 config.js 的 config 中包含 dbSql：

let config = {
	......
    dbSql: dbSqls.MySql, // 默认，系统初始化时根据配置可能重新设置
	......
}

增加 DbVersionManager 管理应用系统的数据库版本

应用配置增加 conf.appSetting.dbVersionControl，其内容来自原来的 dbupdate/dd-version.js，有所简化，示例：

appSetting: {
	......
    dbVersionControl: {
        autoUpdate: false, //是否自动执行更新脚本
        currentVersion: 2, //当前版本，目标部署环境中，最后更新的数据库版本必须与此相符，否则系统无法正常运行
        versions: {
            "1": {
                info: "初始化数据库",
                upScript: "1-dbinit.sql"
            },
            "2": {
                info: "增加三个测试表",
                upScript: "2-up.sql"
            }
        }
    },
    ......

各版本的SQL脚本文件（上例中的 1-dbinit.sql 和 2-up.sql ）仍然保存在 dbupdate 目录，其内容也只写业务相关的SQL，不需要写更新创建schema和维护DD_VERSION表的SQL，如：

文件 1-dbinit.sql：

-- ============================
-- v1, 2025.01.25

-- 增加API访问记录表
CREATE TABLE "{schema}".API_REQUEST_LOG (
    ID VARCHAR(32) NOT NULL,
    REQ_TIME TIMESTAMP(3), -- DATETIME(3) 转为 TIMESTAMP(3)
    API_KEY VARCHAR(32),
    USER_ID VARCHAR(32),
    FROM_IP VARCHAR(45),
    USER_AGENT VARCHAR(50), -- nvarchar 转为 varchar
    METHOD VARCHAR(10),
    ENDPOINT VARCHAR(100), -- nvarchar 转为 varchar
    REQ_PARAMS CLOB, -- LongText 转为 CLOB
    RES_CODE INT,
    RES_INFO VARCHAR(200), -- nvarchar 转为 varchar
    RES_BODY CLOB, -- LongText 转为 CLOB
    DURATION INT,
    LST_UPD_DT DATETIME(3),
    PRIMARY KEY (ID)
)
;

-- 键值对表，每项键值对都有过期时间，缺省为1天
CREATE TABLE "{schema}".KV_PAIR (
  KP_KEY VARCHAR(100) NOT NULL,
  KP_VALUE CLOB,                    -- 达梦大文本用CLOB替代TEXT
  EXPIRE_AT DATETIME(3) DEFAULT DATEADD(DAY, 1, CURRENT_TIMESTAMP), -- 默认过期时间1天
  LST_UPD_DT DATETIME(3),
  PRIMARY KEY (KP_KEY)
);

INSERT INTO "{schema}".KV_PAIR VALUES (
  'keyX',
  'valueX of keyX',
  DATEADD(DAY, 1, CURRENT_TIMESTAMP),
  sysdate()
);

文件 2-up.sql：

-- ============================
-- v2, 2025.01.26

CREATE TABLE "{schema}".TEST1 (
    ID VARCHAR(32) NOT NULL,
    TEST_FIELD1 VARCHAR(32),
    PRIMARY KEY (ID)
);

CREATE TABLE "{schema}".TEST2 (
    ID VARCHAR(32) NOT NULL,
    TEST_FIELD1 VARCHAR(32),
    PRIMARY KEY (ID)
);

CREATE TABLE "{schema}".TEST3 (
    ID VARCHAR(32) NOT NULL,
    TEST_FIELD1 VARCHAR(32),
    PRIMARY KEY (ID)
)

版本1.0.1无效发布，废弃

由于.git 损坏，修复过程中误操作导致部分修改的代码丢失，发布的这个版本无法使用。