setSessionAttr()

名称

setSessionAttr - 设置会话属性

语法

db.setSessionAttr( <options> )

参数

参数名参数类型描述是否必填
optionsJson 对象会话属性选项是

options 格式

属性名描述格式
PreferedInstance会话读操作优先选择的实例，取值列表：”M”、”m”、”S”、”s”、”A”、”a”、1-255。可以使用数组指定多个取值。
“M”, “m”：可读写实例（主实例）
“S”, “s”：只读实例（备实例）
“A”, “a”：任意实例
1-255：通过 instanceid 指定实例 ID		PreferedInstance : “M”
PreferedInstance : [ 1, 10 ]
PreferedInstanceMode指定会话当多个实例符合 PreferedInstance 的条件时的选择模式。
“random”：从候选的实例取值中随机选择。
“ordered”：从候选的实例取值中按照 PerferedInstance 的顺序进行选择。
PreferedInstance 中的角色取值，根据规则选择时优于或者次于实例取值，与 PreferedInstanceMode 取值无关。		PreferedInstaceMode : “random”
PreferedStrict指定节点选择是否为严格模式，当为严格模式时，节点只能从 preferedinstance 指定的 ID 中选取PreferedStrict : true
PreferedPeriod优先实例的有效周期，单位为秒。PreferedPeriod : 60
Timeout指定会话执行操作的超时时间（单位：毫秒）。
-1 表示不进行超时检测。
最小值为 1000 毫秒。		Timeout : 10000
TransIsolation会话事务的隔离级别，0为RU级别，1为RC级别，2为RS级别，3为RR级别。TransIsolation : 1
TransTimeout会话事务锁等待超时时间（单位：秒）。TransTimeout : 10
TransLockWait会话事务在 RC 隔离级别下是否需要等锁。TransLockWait : true
TransUseRBS会话事务是否使用回滚段。TransUseRBS : true
TransAutoCommit会话事务是否支持自动事务提交。TransAutoCommit : true
TransAutoRollback会话事务在操作失败时是否自动回滚。TransAutoRollback : true
TransRCCount会话事务是否使用读已提交来处理 count() 查询。TransRCCount : true

Note:

  • PreferedInstance 和 PreferedInstaceMode 的缺省值是协调节点配置中 preferedinstance 和 preferedinstancemode 的取值。
    • 协调节点配置 preferedinstance 的默认值是 “M”，preferedinstacemode 的默认值是 “random”。
  • PreferedInstance 的取值分为两类，一类是角色取值，如 “M”, “S” 等；一类是实例取值，即数据节点通过配置 instanceid 设置的实例 ID。
    • 角色取值：”M”, “m”：可读写实例（主实例）；”S”, “s”: 只读实例（备实例）；”A”, “a”: 任意角色实例。
    • 实例取值：1-255，指定匹配 instanceid 设置的节点。数据节点可以通过配置 instanceid 配合使用。
      • 实例的 ID 可以通过数据节点的配置项 instanceid 进行设置，同一个数据组中可以配置多个相同实例 ID 的数据节点。
      • 修改数据节点的配置项 instanceid 不能动态生效，需要手工停启数据节点。重启之后也需要手工调用 Sdb.invalidateCache() 清空各个协调节点的缓存。
      • 在节点配置了 instanceid 的情况下，按照 instanceid 进行获取。在节点没有配置 instanceid 的情况下，按照节点的 NodeID 在组内的排序序列（从1开始）作为 instanceid 来进行选取，例如 组 db1 中有3个节点 [ {NodeID:1001}, {NodeID:1004}, {NodeID:1002} ]，那么其节点的 instanceid 分别为 1, 3, 2。
    • 如果一个或多个实例取值和一个角色取值混合指定，则优先选择匹配实例 ID 的一组节点中符合角色的节点。如 [ 1, 2, "S" ] 表示优先选择实例 ID 为 1 或者 2 的节点中的备节点。
    • 混合指定时，可以通过 “-“ 扩展角色取值，如 “-M”，”-S” 等，表示如果没有匹配实例 ID 的节点时，优先选择角色节点，如 [ 1, 2, "-S" ] 表示优先匹配实例 ID 为 1 或者 2 的节点，如果没有，则优先选择任意一个备节点。
    • 混合指定时，如果指定多个角色取值实例，或者其扩展取值，则只有第一个生效。如 [ "M", "S" ] 中只生效 “M”。
    • 单独指定时，角色取值的扩展模式和角色取值的语义是相同的。如单独指定 “S” 和 “-S”，语义是一致的。
    • 如果同一个会话中，读请求前有写请求，写请求之后的一段时间内读请求将默认使用写请求使用的节点（可读写例）进行读取，可以通过设置 PreferedPeriod 来修改读请求复用写请求节点的有效期限。
    • 如果没有符合 PreferedInstance 的实例，之前也没有写请求，一般在数据组中随机选取节点进行。特殊情况是，为了兼容之前的版本，如果单独指定一个实例取值时，将按照实例 ID - 1 后对节点总数取模后在组内按照 NodeID 的升序排序顺序选取。
  • PreferedPeriod 的缺省值是协调节点配置中 preferedperiod 的取值。
    • 如果上一次选择进行请求的节点在有效周期内，读请求仍使用该节点进行查询，周期之后，将根据 PreferedInstance 重新选择。
    • 默认值为60。
    • 取值范围为 [-1, 231 - 1]。
    • -1表示不失效。
    • 0表示本次查询不使用上次选择的优先实例，根据 PreferedInstance 进行重新选择。
    • 该参数仅适用于 SequoiaDB 2.8.9 版本，3.2.5 及以上版本。
  • Timeout 的默认值是 -1，即不进行超时检测。
  • 事务相关属性只有 TransTimeout 允许在事务中设置，其它事务属性需要在非事务中设置。
  • RR 隔离级别需要全局事务的支持：
  • 获取会话属性请参考 Sdb.getSessionAttr() 。

返回值

函数执行成功时无返回值。

函数执行失败时，将抛出异常并输出错误信息。

错误

setSessionAttr() 函数常见异常如下：

错误码错误类型可能发生的原因解决办法
-6SDB_INVALIDARGoptions 属性输入错误检查所设置属性的值和范围等

当异常抛出时，可以通过 getLastErrMsg() 获取错误信息或通过 getLastError() 获取错误码，关于错误处理可以参考常见错误处理指南。

版本

v2.0 及以上版本

示例

  • 设置会话优先从“主”数据库实例获取数据
  1. > db.setSessionAttr( { PreferedInstance: "M" } )
  • 设置会话优先从 1 和 3 的备实例读取数据
  1. > db.setSessionAttr( { PreferedInstance : [ 1, 3, "S" ] } )
  • 设置会话的操作超时时间为 10 秒
  1. > db.setSessionAttr( { Timeout : 10000 } )