数据库

数据库数据接口通过创建接口实现应用程序与数据库数据的同步

添加数据库数据分组

点击【数据接口】，进入数据接口功能模块，选中数据库数据，数据库数据对应一个外部数据库连接配置，填写分组信息，点击保存按钮，即可创建数据库数据分组

属性配置说明

类型： 选择数据库数据
名称： 自定义数据接口名称，名称不可重复
分组说明：可填写与此数据源相关的一些附属说明信息
数据库类型：系统内置MySQL,Postgres,SQLserver,MariaDB,SQLite3、Oracle六种类型，可下拉选择其中一种
测试连接： 校验数据库连接配置是否有效
数据库服务器的用户名、密码、IP 地址、端口号、数据库名称为被使用数据库的基本信息

添加接口具体操作

数据接口分组基本信息填写完毕后，点击添加数据接口。分组下每个接口对应一个完整的数据库数据操作，执行时，会根据原配置和执行时参数生成SQL并执行。

属性配置说明

标识： 接口的唯一标识，必须为英文字母、数值或下划线。该标识在调用接口时使用。
名称： 自定义接口名称，名称不可重复
参数： 执行操作时传递的参数，可以指定默认值。字段配置绑定参数后，每次执行时可以作用于不同的数据，从而让操作更灵活
表名： 数据库表名，接口操作的对象（目前只限增、删、改操作）
操作类型： 可对数据接口中的数据进行查询、插入、修改和删除的操作 原生模式： 勾选原生模式后，根据用户输入的SQL语句执行，不用进行字段配置，不勾选需进行字段配置
删除条件为或关系： 或关系删除其中一个数据，与关系删除全部关系，默认不勾选（即关系之间为与关系），当操作类型选择删除时才显示此配置项
字段配置： 对数据库数据需要插入、修改或删除操作的字段进行配置，主要有以下三点：

• 插入操作： 需填写目标字段，将目标字段插入数据库
• 删除操作： 删除目标字段符合条件的数据，当不选中符号时，默认为等于
• 修改操作： 需指定主键，将对应行的指定字段更新为指定数值。当指定主键不存在时相当于插入数据

前置脚本： 前置脚本是在请求发送前执行的代码片段。如要在请求头中包含时间戳或在 URL 参数中发送随机的字母数字字符串等类似请求中非常适用。 具体信息请参考数据接口通用功能中的前置脚本数据接口 后置脚本： 后置脚本是在请求发送完成后执行的代码片段。主要用来断言请求返回的结果是否正确、将请求返回的结果数据写入环境变量等。具体信息请参考数据接口通用功能中的后置脚本数据接口
信息填写完毕后点击运行按钮 输入请求变量并发送请求

接口运行后返回的数据格式

数据库数据接口执行后的结果都以 json 的形式返回，不同操作类型的返回的格式有所不同，写后置脚本时注意区分。

注意这里指的是数据接口正常执行时返回的数据。出现错误（包括 SQL 导致的错误）时会返回错误信息，与操作类型无关。

插入、修改和删除操作

这三种操作都可能影响数据库的数据，执行后返回的结果表明了对数据的影响。

{
    "rowsAffected": 10,      // 操作影响的行数
    "rowsAffectedErr": "",  // 获取影响行数时的错误信息
    "lastInsertId": 0,      // 操作最后插入的行的id
    "lastInsertIdErr": ""   // 获取插入行id时的错误信息
}

字段说明如下：

rowsAffected：操作影响的行数。最有用的信息（如根据一定条件删除数据后，用这个字段获取删除了多少条数据）。绝大多数数据库支持获取这个信息。

rowsAffectedErr：获取影响行数时的错误信息，一般为空字符串。注意这个字段并不反应数据库操作的错误，所以非空也不代表数据库执行错误。

lastInsertId：操作最后插入的行的id。一般是插入操作且数据表的主键为自增形式时才会返回这个字段，缺省为 0。部分数据库不支持获取这个信息。

lastInsertIdErr：获取插入行id时的错误信息，一般为空字符串。注意这个字段并不反应数据库操作的错误，所以非空也不代表数据库执行错误。部分数据库不支持获取这个信息。

后置脚本示例

后置脚本是一个函数，其入参 data 代表执行后置脚本前的数据（上文中的格式）。注意：没有后置脚本时，数据库数据接口返回的 json 数据的字段都是字母为小写；有后置脚本时，数据的各字段首字母要用大写。

// 返回影响行数和是否发生了影响
function handler(data) {
  // 注意字段名要用大写
  let rows = data.RowsAffected;
  return {
    "rows": rows,
    "affected": rows > 0
  }
}

查询操作

查询操作会分开返回数据和列配置，具体字段如下：

• feilds：数组，每个元素代表数查询结果中的一列
  • originalName/name：列名称。
  • originalType：列类型，不同数据库中列类型名称不同。
  • colIndex：此列在结果中的顺序，从 0 开始，与该列在 fields 中的索引相同。
• data：二维数组。当查询结果为 m 行 n 列时，data 中有 m 个一维数组，每个数组（代表结果中的一行）有 n 个子元素（一般子元素的数据类型是不同的）。
• sql：执行查询的 SQL。

示例1: MySQL和MariaDB

假设数据库中有一个表示商品信息的表，表名为 bi_test。

id	name	count	price	active
a1	大米	100	1.20	true
b1	栗子	20	5.00	true
a2	五常大米	26	10.00	false
aaa	小米	1000	2.90	null

当我们执行查询操作，SQL 为 SELECT * FROM "bi_test" 。

返回的结果如下：

{
  "data": [
    [
      "a1",
      "大米",
      100,
      "1.20",
      true
    ],
    [
      "b1",
      "栗子",
      20,
      "5.00",
      true
    ],
    [
      "a2",
      "五常大米",
      26,
      "10.00",
      false
    ],
    [
      "aaa",
      "小米",
      1000,
      "2.90",
      null
    ]
  ],
  "fields": [
    {
      "id": "",
      "createdAt": "0001-01-01T00:00:00Z",
      "updatedAt": "0001-01-01T00:00:00Z",
      "tableId": "",
      "name": "id",
      "originalName": "id",
      "originalType": "VARCHAR",
      "isMeasure": false,
      "calculated": false,
      "checked": true,
      "colIndex": 0,
      "biType": "string",
      "size": 128
    },
    {
      "id": "",
      "createdAt": "0001-01-01T00:00:00Z",
      "updatedAt": "0001-01-01T00:00:00Z",
      "tableId": "",
      "name": "name",
      "originalName": "name",
      "originalType": "TEXT",
      "isMeasure": false,
      "calculated": false,
      "checked": true,
      "colIndex": 1,
      "biType": "string",
      "size": 9223372036854776000
    },
    {
      "id": "",
      "createdAt": "0001-01-01T00:00:00Z",
      "updatedAt": "0001-01-01T00:00:00Z",
      "tableId": "",
      "name": "count",
      "originalName": "count",
      "originalType": "INT8",
      "isMeasure": false,
      "calculated": false,
      "checked": true,
      "colIndex": 2,
      "biType": "string"
    },
    {
      "id": "",
      "createdAt": "0001-01-01T00:00:00Z",
      "updatedAt": "0001-01-01T00:00:00Z",
      "tableId": "",
      "name": "price",
      "originalName": "price",
      "originalType": "NUMERIC",
      "isMeasure": false,
      "calculated": false,
      "checked": true,
      "colIndex": 3,
      "biType": "string"
    },
    {
      "id": "",
      "createdAt": "0001-01-01T00:00:00Z",
      "updatedAt": "0001-01-01T00:00:00Z",
      "tableId": "",
      "name": "active",
      "originalName": "active",
      "originalType": "BOOL",
      "isMeasure": false,
      "calculated": false,
      "checked": true,
      "colIndex": 4,
      "biType": "string"
    }
  ],
  "sql": "select * from bi_test"
}

示例2: PostgreSQL

由于在数据接口组配置中只有数据库名配置，而没有 shcema 配置，当数据库存在多个 schema 时，需要 SQL 中加上 schema 信息。

还是以上个例子，bi_test 表不在默认的 schema 中，而是在 my_schema 中，此时 SQL 应为 SELECT * FROM "my_schema"."bi_test" 。

后置脚本示例

后置脚本是一个函数，其入参 data 代表执行后置脚本前的数据（上文中的格式）。

// 将结果转化为一个一维数组，将列名作为字段名
// 如果没有数据，会返回空数组
// 这个脚本与返回结果的内容无关
function handler(data) {
    // 可以在 data-service 服务的日志中看到 console 的输出
    // console.log(JSON.stringify(data));
    return [data.data.map(row =>
        data.fields.reduce((obj, field, i) =>
            Object.assign(obj, { [field.originalName]: row[i] }), {})
    )]
}

对于 4.6.1 及其之前的版本的 data-source 模块，使用后置脚本处理数据库数据接口返回的 json 数据时，需要注意返回数据 data 中的字段与首字母是大写（与没有后置脚本时得到的结果不同）。

以上述脚本为例，为了避免返回的数据是 undefined， 应做如下修改：

• data.data 改为 data.Data
• data.fields 改为 data.Fields
• field.originalName 改为 field.OriginalName