shentongdb类

shentongdb是池和连接对象的工厂类，shentongdb通过加载node-shentongdb进行实例化：

const shentongdb = require("shentongdb");

在内部，该插件将shentongdb对象创建为单例。在同一Noe.js进程中重新加载它时指向同一对象的新指针。

常量

这些常量在shentongdb模块中定义。本文档后面将介绍其用法。

显示常量的数值以帮助调试。它们将来可能会更改，因此在应用程序中使用常量名称。

查询outFormat常量

查询结果输出格式选项的常量：

属性名	值	描述
shentongdb.OUT_FORMAT_ARRAY	4001	获取每行作为列值数组
shentongdb.OUT_FORMAT_OBJECT	4002	将每一行作为对象获取

数据库类型属性

常量用于节点常量用于node-shentongdb中的数据库类型。

这些值指示数据库的扩展元数据、DbObject类型和Lob类型属性中的数据类型。

某些常数也可用于：

• execute()的bindParams类型executeMany()的bindDefs类型
• createLob()的类型参数
• fetchAsBuffer,fetchAsString, 以及fetchInfo

属性名	值	数据库类型
shentongdb.DB_TYPE_BFILE	2020	BFILE
shentongdb.DB_TYPE_BINARY_DOUBLE	2008	BINARY_DOUBLE
shentongdb.DB_TYPE_BINARY_FLOAT	2007	BINARY_FLOAT
shentongdb.DB_TYPE_BINARY_INTEGER	2009	BINARY_INTEGER, PLS_INTEGER, SMALLINT
shentongdb.DB_TYPE_BLOB	2019	BLOB
shentongdb.DB_TYPE_BOOLEAN	2022	BOOLEAN
shentongdb.DB_TYPE_CHAR	2003	CHAR
shentongdb.DB_TYPE_CLOB	2017	CLOB
shentongdb.DB_TYPE_CURSOR	2021	SYS_REFCURSOR
shentongdb.DB_TYPE_DATE	2011	DATE
shentongdb.DB_TYPE_INTERVAL_DS	2015	INTERVAL DAY TO SECOND
shentongdb.DB_TYPE_INTERVAL_YM	2016	INTERVAL YEAR TO MONTH
shentongdb.DB_TYPE_JSON	2027	JSON
shentongdb.DB_TYPE_LONG	2024	CLOB
shentongdb.DB_TYPE_LONG_RAW	2025	BLOB
shentongdb.DB_TYPE_NUMBER	2010	NUMBER /FLOAT/Decimal/Double
shentongdb.DB_TYPE_NVARCHAR	2002	VARCHAR
shentongdb.DB_TYPE_OBJECT	2023	OBJECT
shentongdb.DB_TYPE_RAW	2006	BINARY、VARBINARY
shentongdb.DB_TYPE_ROWID	2005	ROWID
shentongdb.DB_TYPE_TIMESTAMP	2012	TIMESTAMP
shentongdb.DB_TYPE_TIMESTAMP_LTZ	2014	TIMESTAMP WITH LOCAL TIME ZONE
shentongdb.DB_TYPE_TIMESTAMP_TZ	2013	TIMESTAMP WITH TIME ZONE
shentongdb.DB_TYPE_VARCHAR	2001	VARCHAR2

Node-shentong类型属性

这些常量是数据量类型属性的别名：

属性名	值	数据库属性
shentongdb.BLOB	2019	shentongdb.DB_TYPE_BLOB
shentongdb.BUFFER	2006	shentongdb.DB_TYPE_RAW
shentongdb.CLOB	2017	shentongdb.DB_TYPE_CLOB
shentongdb.CURSOR	2021	shentongdb.DB_TYPE_CURSOR
shentongdb.DATE	2014	shentongdb.DB_TYPE_TIMESTAMP_LTZ
shentongdb.DEFAULT	0	n/a
shentongdb.NUMBER	2010	shentongdb.DB_TYPE_NUMBER
shentongdb.STRING	2001	shentongdb.DB_TYPE_VARCHAR

执行绑定方向的属性

属性可用于execute()的bindParams,queryStream()以及executeMany()的bindDefs。

这些参数指定绑定到SQL或PL/SQL绑定参数的数据值是传入还是传出数据库：

属性名	值	描述
shentongdb.BIND_IN	3001	绑入
shentongdb.BIND_INOUT	3002	可绑入和绑出
shentongdb.BIND_OUT	3003	绑出

SQL语句类型属性

connection.getStatementInfo()调用返回语句类型属性

属性名	值	描述
shentongdb.STMT_TYPE_ALTER	7	ALTER
shentongdb.STMT_TYPE_BEGIN	8	BEGIN
shentongdb.STMT_TYPE_CALL	10	CALL
shentongdb.STMT_TYPE_COMMIT	21	COMMIT
shentongdb.STMT_TYPE_CREATE	5	CREATE
shentongdb.STMT_TYPE_DECLARE	9	DECLARE
shentongdb.STMT_TYPE_DELETE	3	DELETE
shentongdb.STMT_TYPE_DROP	6	DROP
shentongdb.STMT_TYPE_INSERT	4	INSERT
shentongdb.STMT_TYPE_MERGE	16	MERGE
shentongdb.STMT_TYPE_ROLLBACK	17	ROLLBACK
shentongdb.STMT_TYPE_SELECT	1	SELECT
shentongdb.STMT_TYPE_UNKNOWN	0	未知
shentongdb.STMT_TYPE_UPDATE	2	UPDATE

池状态属性

pool.status调用获得以下属性

属性名	值	描述
shentongdb.POOL_STATUS_CLOSED	6002	连接池已经关闭
shentongdb.POOL_STATUS_DRAINING	6001	正在排空正在使用的连接池，并将很快强制关闭
shentongdb.POOL_STATUS_OPEN	6000	连接池已经打开
shentongdb.POOL_STATUS_RECONFIGURING	6003	pool.reconfigure() 调用时处理过程中

属性

shentongdb对象的属性用于设置部署的配置参数。如果需要，可以为池或连接对象重写这些属性。

也可以读取或修改这些属性，如果修改了属性，则只有createPool（）或getConnection（）方法的后续调用会受到影响。在修改属性之前存在的对象不会被更改。

无效的属性值或组合值可能导致错误24413：Invalid number of sessions specified.

每个配置属性如下所述。

shentongdb.autoCommit

Boolean autoCommit

如果此属性为true，则在语句执行结束时自动提交当前连接中的事务。默认值为false。

此属性可以在execute（）调用中重写。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.autoCommit = false;

shentongdb.connectionClass

String connectionClass

用户选择的连接类值定义连接的逻辑名称。大多数单用途应用程序在使用连接池时应设置connectionClass。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.connectionClass = 'HRPOOL';

shentongdb.errorOnConcurrentExecute

Boolean errorOnConcurrentExecute

如果在单个连接上尝试并发操作，可以将此属性设置为引发错误。

errorOnConcurrentExecute的默认值为false。

每个数据库连接一次只能与数据库交互一个操作。试图同时执行多个操作可能是应用程序编码错误的标志，例如，可能缺少等待。无法在单个连接上并行执行的操作示例包括连接。execute（），即连接。executeMany（），连接。queryStream（），即连接。getDbObjectClass（），即连接。commit（），即连接。close（）和LOB流。

此属性的值不影响使用多个连接。这些都可以同时使用，并且每个都可以执行一个操作。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.errorOnConcurrentExecute = false;

shentongdb.fetchArraySize

Number fetchArraySize

此属性设置用于从数据库获取查询行的内部缓冲区的大小。更改它可能会影响查询性能，但不会影响返回给应用程序的行数。

默认值为16。

该属性在默认直接获取、ResultSet的getRow（）调用和queryStream（）期间使用。当没有参数（或值0）传递给getRows（）时，它用于getRows（）。

增加此值会减少到数据库的往返次数，但会增加每次数据提取的内存使用量。对于返回大量行的查询，fetchArraySize的值越高，性能越好。对于仅返回几行的查询，请减少fetchArraySize的值，以最小化数据获取期间的内存管理量。

对于直接获取（那些使用execute（）选项resultSet:false的），内部缓冲区大小将基于maxRows和fetchArraySize中的较小者。

此属性可以被execute（）选项fetchArraySize覆盖。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.fetchArraySize = 100;

shentongdb.fetchAsBuffer

Array fetchAsBuffer

允许查询列作为缓冲区返回。属性应为类型常量数组。目前唯一有效的常量是shentongdb.BLOB或其等价的shentongdb.DB_TYPE_BLOB。

设置后，将使用execute（）或queryStream（）查询BLOB列，然后将列数据作为缓冲区而不是默认Lob实例返回。execute（）或queryStream（）调用中的单个查询列可以使用fetchInfo覆盖fetchAsBuffer全局设置。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.fetchAsBuffer = [ shentongdb.BLOB ];

shentongdb.fetchAsString

Array fetchAsString

允许查询列作为字符串而不是默认类型返回。

在node-shentongdb中，所有列都作为最接近的JavaScript类型返回，或者在CLOB和NCLOB类型中作为Lob实例返回。fetchAsString属性可以覆盖此默认类型映射。

fetchAsString属性应该是一个类型常量数组。有效常数是shentongdb.DATE，shentongdb.NUMBER。shentongdb.BUFFER,shentongdb.CLOB。还可以使用等效的DB_TYPE_*

当使用execute（）或queryStream（）查询具有其中一种类型的任何列时，列数据将作为字符串而不是默认表示形式返回。execute（）或queryStream（）调用中的单个查询列可以使用fetchInfo覆盖fetchAsString全局设置。

注:

指定shentongdb.NUMBER将影响数字列。fetchAsString属性有助于避免使用JavaScript类型可能导致数值精度损失的情况。

指定shentongdb.CLOB将同时影响CLOB和NCLOB列。类似地，指定shentongdb。NCLOB还将影响CLOB和NCLOB列。使用fetchAsString可以直接在查询输出中自动获取LOB数据，而不需要流。

指定shentongdb.DATE将影响日期和时间戳列。使用fetchAsString有助于避免日期转换。

当shentongdb.BUFFER缓冲区用于原始数据，数据库将数据作为十六进制编码字符串返回。对于作为字符串返回的日期和数字，此映射创建的字符串的最大长度为200字节。为CLOB和NCLOB列创建的字符串通常会受到Node.js和V8内存限制。

对于非CLOB类型，转换由客户端库处理，通常称为定义提取类型。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.fetchAsString = [ shentongdb.DATE, shentongdb.NUMBER ];

shentongdb.lobPrefetchSize

Number lobPrefetchSize

此属性暂时禁用。设置它没有效果。为了获得最佳性能，请将LOB提取为字符串或缓冲区。

node-shentongdb在内部使用LOB定位器来操作长对象（LOB）数据。LOB预取允许在第一次返回这些定位器时，将LOB数据提前返回到Node-shentongdb。这允许高效使用资源和Node-shentongdb与数据库之间的往返。

LOB的预取主要用于小LOB,默认大小为16384。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.lobPrefetchSize = 16384;

shentongdb.maxRows

Number maxRows

具有连接的查询获取的最大行数。不使用结果集时执行（）。超出此限制的行不会从数据库中提取。值为0表示没有限制，默认值为0。

此属性可以在execute（）调用中重写。为了提高数据库效率，SQL查询应该使用行限制子句，如OFFSET/FETCH或等效子句。maxRows属性可用于阻止编码错误的查询意外返回大量行。

对于返回固定、少量行的查询，请将maxRows设置为该值。例如，对于返回一行的查询，将maxRows设置为1。

当查询行数相对较大或无法预测时，建议使用ResultSet或queryStream（）。这允许应用程序以较小的块或单独的方式处理行，从而防止节点损坏。js内存限制被超出，或者查询结果被maxRows限制意外截断。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.maxRows = 0;

shentongdb.outFormat

Number outFormat

使用连接时获取的查询行的格式。execute（）或connection.queryStream（）。它同时影响ResultSet和非ResultSet查询。它可以用于顶级查询和REF游标输出。

这可以是shentongdb常量，shentongdb.FORMAT_ARRAY或shentongdb.OUT_FORMAT_OBJECT。默认值是shentongdb.FORMAT_ARRAY更有效。旧的、等效的常数shentongdb.ARRAY和shentongdb.OBJECT已弃用。

如果指定为shentongdb.OUT_FORMAT_ARRAY，每行作为列值数组获取。

如果指定为shentongdb.OUT_FORMAT_OBJECT，每一行作为一个JavaScript对象获取。对象的每个列名都有一个属性，属性值设置为相应的列值。属性名称遵循数据库的标准名称大小写规则。它通常是大写的，因为大多数应用程序使用不带引号、不区分大小写的名称创建表。

当查询中使用重复的列名时，node-shentongdb将在Shentongdb.OUT_FORMAT_OBJECT模式下附加数字后缀。以便所有列都在JavaScript对象中表示。此属性可以在execute（）或queryStream（）调用中重写。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.outFormat = shentongdb.OUT_FORMAT_ARRAY;

shentongdb.poolIncrement

Number poolIncrement

每当连接请求超过当前打开的连接数时新增的连接数目。

默认值为1。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.poolIncrement = 1;

shentongdb.poolMax

Number poolMax

连接池可以增长到的最大连接数。

默认值为4。

创建连接池时，此属性可能会被覆盖。

重要的是，如果增加poolMax，还应该增加node-shentongdb可用的线程数。请参见连接和线程数。

强烈建议使用poolMin等于poolMax的固定池大小。这有助于防止连接风暴，并有助于整个系统的稳定性。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.poolMax = 4;

shentongdb.poolMin

Number poolMin

创建池时与数据库建立的连接数。此外，这是池收缩时维护的最小连接数，请参阅poolTimeout。

默认值为0。

创建连接池时，此属性可能会被覆盖。

强烈建议使用poolMin等于poolMax的固定池大小。这有助于防止连接风暴，并有助于整个系统的稳定性。

一旦打开的连接数超过poolMin，则打开的连接量不会低于PoolMin。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.poolMin = 0;

shentongdb.poolPingInterval

Number poolPingInterval

当调用池getConnection（）并且连接在池中空闲至少达poolPingInterval秒时，node shentongdb会在内部“Ping”数据库，以检查连接是否处于活动状态。ping之后，一个不可用的连接被销毁，一个可用的连接由getConnection（）返回。连接ping提高了池连接首次使用时有效的机会，因为识别出的不可用连接不会返回到应用程序。

默认的poolPingInterval值为60秒。可能的值为：

poolPingInterval 值	Pool getConnection()行为
n < 0	不检测连接是否有效
n = 0	检查连接有效性。不建议使用此值 因为执行每个ping都会带来开销
n > 0	连接在池中空闲大于n秒，检查有效性

创建连接池时，此属性可能会被覆盖。

示例如下：

const shentongdb = require('shentongdb');
shentongdb.poolPingInterval = 60;     // 秒

shentongdb.poolTimeout

Number poolTimeout

poolTimeout属性允许池中打开的连接数收缩到poolMin。

如果应用程序用调用close方法将连接返回到池中，并且这些连接未使用超过poolTimeout秒，则poolMin以上的任何多余连接都将被关闭。

如果poolTimeout设置为0，则不会终止空闲连接。

如果您希望使用pool.reconfigure()更新poolTimeout 。在调用 shentongdb.createPool()时poolTimeout的值必须为非零。

默认值为60。

创建连接池时，此属性可能会被覆盖。

示例如下：

const shentongdb= require('shentongdb');
shentongdb.poolTimeout = 60;

shentongdb.prefetchRows

Number prefetchRows

这是一个查询调优选项，用于设置数据库客户端接口在查询的内部初始语句执行阶段获取的额外行数。预取大小不影响node-shentongdb何时或返回多少行到应用程序。

此参数与fetchArraySize相同。

prefetchRows属性可以与shentongdb结合使用。fetchArraySize要优化查询性能、内存使用，并减少返回查询结果所需的往返调用次数，请参阅优化提取性能。

在某些情况下，例如当查询涉及LOB时，会忽略prefetchRows值。

如果获取一个REF游标，从该游标中检索行，然后将其传递回PL/SQL块，则在获取REF游标的初始语句期间，应将prefetchRows设置为0。

默认值为2。

此属性可能在连接中被重写。execute（）调用，如果需要更改值，这是首选用法。

示例如下：

const shentongdb= require('shentongdb');
shentongdb.prefetchRows = 2;

shentongdb.stmtCacheSize

Number stmtCacheSize

每个连接的语句缓存中缓存的语句数。

默认值为30。

对于特定的池或连接对象，可以重写此属性。

通常，将语句缓存设置为应用程序正在执行的语句工作集的大小。通过将大小设置为0，可以禁用语句缓存。

示例如下：

const shentongdb= require('shentongdb');
shentongdb.stmtCacheSize = 30;

shentongdb.version

readonly Number version

此只读属性提供node-shentongdb版本的数字表示。对于版本x.y.z，此属性给出的数字为：（10000*x）+（100*y）+z

示例如下：

const shentongdb= require('shentongdb');
console.log("Driver version number is " + shentongdb.version);

shentongdb.versionString

readonly String versionString

此只读属性提供node-shentongdb版本的字符串表示，包括版本后缀（如果存在）。

示例如下：

const shentongdb= require('shentongdb');
console.log("Driver version is " + shentongdb.versionString);

类方法

shentongdb.createPool()

原型

回调：

createPool(Object poolAttrs, function(Error error, Pool pool){});

承诺：

promise = createPool(Object poolAttrs);

描述

此方法使用指定的用户名、密码和连接字符串创建连接池。池通常在应用程序初始化期间创建一次。

可以通过在poolAttrs参数中指定新属性来覆盖默认属性。

调用createPool（）时，可以将池添加到池缓存中。这允许以后按名称访问池，无需通过代码传递池对象。有关更多详细信息，请参阅连接池缓存。

池应pool.close()调用关闭。

shentongdb.getConnection()

原型

回调：

getConnection([String poolAlias | Object connAttrs], function(Error error, Connection connection){});

承诺：

promise = getConnection([String poolAlias | Object connAttrs]);

描述

从连接池缓存中的池获取连接，或创建新的独立非池连接。

对于连接不经常使用的情况，创建独立连接可能比创建和管理连接池更有效。但是，在大多数情况下，建议从连接池获取连接。

下表显示了调用getConnection时可以使用的各种签名，并描述了函数的行为。

签名	描述
shentongdb.getConnection()	从先前创建的默认池获取连接。返回一个承诺。
shentongdb.getConnection(callback)	从先前创建的默认池获取连接。调用回调
shentongdb.getConnection(poolAlias)	使用指定的池别名从先前创建的池获取连接。返回一个承诺
shentongdb.getConnection(poolAlias, callback)	使用指定的池别名从先前创建的池获取连接。调用回调
shentongdb.getConnection(connAttrs)	创建独立的非池连接。返回一个承诺。
shentongdb.getConnection(connAttrs, callback)	创建独立的非池连接。调用回调。

注解

如果应用程序打开了多个连接，则应增加节点shengtongdb的可用线程数。请参见连接和线程数。

shentongdb.getPool()

原型

getPool([String poolAlias]);

描述

从连接池缓存中检索以前创建的池。请注意，这是一种同步方法。

shentongdb.shutdown()

原型

回调：

shutdown([Object connAttr, [Number shutdownMode, ] ] function(Error error) {});

承诺：

promise = shutdown([Object connAttr [, Number shutdownMode]]);

描述

这是连接的简化形式。shutdown（）用于关闭数据库实例。它接受连接凭据并完全关闭数据库实例。

shentongdb.startup()

原型

回调：

startup([Object connAttrs, [Object options, ] ] function(Error error) {});

承诺：

promise = startup([Object connAttrs [, Object options ]]);

描述

这是连接的简化形式。startup（）用于启动数据库实例。它接受连接凭据并完全启动数据库实例。

Connection类

连接对象是通过池类getConnection（）或shentongdb类getConnect（）调用获得的。该连接用于访问数据库。

属性

connection.callTimeout

Number callTimeout

设置node-shentongdb和数据库之间的每次底层往返连接可能占用的最大毫秒数。每个node-shentongdb方法或操作可以进行零次或多次往返。callTimeout值单独应用于每个往返，而不是所有往返的总和。每次往返完成之前或之后在node-shentongdb中处理所花费的时间不计算在内。

使用IPC连接时，即node-shentongdb与数据库网络侦听器在同一主机上运行时，callTimeout设置不起作用。

默认值为0，表示没有超时。

connection.currentSchema

String currentSchema

设置currentSchema后，使用对架构对象的非限定引用的SQL语句将解析为指定架构中的对象。

此设置不会更改会话用户或当前用户，也不会为会话用户提供任何额外的系统或对象权限。

currentSchema的值在显式设置之前将为空。

此属性是更改会话集CURRENT_SCHEMA的有效替代方法。

connection.stmtCacheSize

readonly Number stmtCacheSize

连接的语句缓存中要缓存的语句数。默认值是在池中创建连接时在池对象中有效的stmtCacheSize属性。

connection.tag

String tag

应用程序可以在池连接上设置标记属性，以指示连接的“会话状态”。当连接释放到池时，该标记将被保留。随后的池。getConnection（）可以请求具有给定标记的连接。由应用程序设置任何所需的会话状态并设置连接。在关闭连接之前标记。

标记属性不用于独立连接。标记必须是名称=值对的多属性标记，如“k1=v1；k2=v2”。

空字符串表示没有标记集。

• 取标签

  在游泳池之后。getConnection（）请求标记的连接：

  如果未使用sessionCallback，则连接。标记将包含连接的实际标记。

  当连接到节点时。使用js sessionCallback函数，然后连接。在调用回调之前，标记将被设置为连接的实际标记的值。然后，回调可以设置连接状态并更改连接。标记，然后从pool.getConnection（）返回连接。

  当使用PL/SQL sessionCallback过程时，则在池之后。getConnection（）返回连接。标记包含与请求的标记具有相同属性值的标记。这些特性可以是不同的顺序。如果matchAnyTag为true，则为连接。标记可以包含除请求的属性之外的其他属性。每个池后面的代码。可能需要对PL/SQL代码进行镜像的getConnection（）调用来实现连接。标记可以设置为表示在PL/SQL过程中更改的会话状态的值。

• 设置标签

  可以在关闭连接之前的任何时间设置标记。如果是节点。正在使用js sessionCallback函数，最佳实践建议是在回调函数中设置标记。

要清除连接的标记，请设置connection。标签=”。

方法

connection.break()

原型

回调

break(function(Error error){});

承诺

promise = break();

描述

此调用将停止连接上当前正在运行的操作。

如果在发出中断时没有正在进行的操作或操作已完成，则break（）实际上是一个no-op。

connection.changePassword()

原型

回调

changePassword(String user, String oldPassword, String newPassword, function(Error error){});

承诺

promise = changePassword(String user, String oldPassword, String newPassword);

描述

更改指定用户的密码。

只有具有ALTER USER权限的用户才能更改其他用户的密码。

connection.close()

原型

回调

close([Object options, ] function(Error error){});

承诺

promise = close([Object options]);

描述

释放连接。

为了提高系统效率，强烈建议在不再需要连接时调用close（）。需要为池连接调用close（），以防止池中的连接耗尽。

释放连接时，将回滚连接上正在进行的任何事务。

如果池连接上发生错误，并且已知该错误导致连接不可用，则close（）将从连接池中删除该连接，以便将来对池进行扩展的池getConnection（）调用将创建新的有效连接。

connection.commit()

原型

回调

commit(function(Error error){});

承诺

promise = commit();

描述

此调用提交连接上正在进行的当前事务。

connection.rollback()

原型

回调

rollback(function(Error error){});

承诺

promise = rollback();

描述

此调用回滚连接上正在进行的当前事务。

connection.createLob()

原型

回调

createLob(Number type, function(Error error, Lob lob){});

承诺

promise = createLob(Number type);

描述

将Lob创建为临时Lob。LOB最初为空。数据可以流式传输到LOB，然后可以将其传递到PL/SQL块中，或者插入到数据库中。

当不再需要时，使用createLob（）创建的lob应使用lob.destroy() 关闭，因为如果临时LOB未关闭，数据库资源将保持打开状态。

使用createLob（）创建的LOB可以绑定为IN、IN和OUT绑定。

connection.execute()

原型

回调

execute(String sql [, Object bindParams [, Object options]], function(Error error, Object result){});

承诺

promise = execute(String sql [, Object bindParams [, Object options]]);

描述

此调用执行单个SQL或PL/SQL语句。有关示例，请参见SQL执行。另请参见queryStream（），了解执行查询的另一种方法。

要执行的语句可能包含IN绑定、OUT或IN OUT绑定值或变量，这些值或变量使用对象或数组进行绑定。

回调函数返回一个结果对象，其中包含任何提取的行、任何OUT和IN OUT绑定变量的值以及受DML语句执行影响的行数。

connection.executeMany()

原型

回调

executeMany(String sql, Array binds [, Object options], function(Error error, Object result) {});
executeMany(String sql, Number numIterations [, Object options], function(Error error, Object result) {});

承诺

promise = executeMany(String sql, Array binds [, Object options]);
promise = executeMany(String sql, Number numIterations [, Object options]);

描述

此方法允许将数据值集绑定到一个DML或PL/SQL语句以执行。这就像呼叫连接。多次执行execute（），但需要较少的往返。这是处理批处理更改的有效方法，例如在插入或更新多行时。该方法不能用于查询。

executeMany（）方法支持大多数数据类型的IN、IN、OUT和OUT绑定，PL/SQL集合关联数组除外。

当不需要绑定参数或当所有绑定参数都是外绑定时，应使用接受多次迭代的函数版本。

当executeMany（）用于返回外绑定的PL/SQL代码时，它将具有与重复调用execute（）相同的性能特征。

connection.getStatementInfo()

原型

回调

getStatementInfo(String sql, function(Error error, Object information){});

承诺

promise = getStatementInfo(String sql);

描述

解析SQL语句并返回有关它的信息。这对于查找查询的列名和查找所用绑定变量的名称非常有用。

此方法执行到数据库的往返，因此应避免不必要的调用。

这些信息由具有某些限制的低级API提供。一些不常见的语句将返回shentongdb.STMT_type_UNKNOWN形式的语句类型。DDL语句不会被解析，因此不会报告其中的语法错误。无法确定绑定变量的方向和类型。

语句始终添加到语句缓存中。如果使用同一语句重复调用getStatementInfo（），或者在execute（）调用或类似调用中使用该语句，这将提高性能。

connection.isHealthy()

原型

isHealthy()

描述

此同步函数返回一个布尔值，指示连接的运行状况。

在某些情况下，连接可能会变得不可用，例如，如果网络套接字断开，如果数据库错误指示连接不可用，或者在从数据库接收到计划停机通知后。

在现有独立连接上启动新数据库请求之前，最好使用此函数。池连接在将连接返回到应用程序之前在内部执行此检查。

如果此函数返回false，则应用程序应关闭连接，并应建立新连接。

此函数执行本地检查。要完全检查连接的运行状况，请使用ping（），它执行到数据库的往返。

connection.ping()

原型

回调

ping(function(Error error){});

承诺

promise = ping();

描述

此方法检查连接当前是否可用，以及到数据库的网络是否有效。此调用可用于系统健康检查。ping仅确认在ping时单个连接可用。

ping不会取代语句执行期间的错误检查，因为网络或数据库故障可能发生在ping（）和execute（）调用之间的时间间隔内。

ping需要往返数据库，因此应避免不必要的ping（）调用。

如果ping（）返回错误，应用程序应关闭连接。

connection.queryStream()

原型

queryStream(String sql [, Object bindParams, [Object options]]);

返回值

此同步方法将返回一个可读的查询流。

描述

此函数提供查询流支持。参数与execute（）相同，只是不使用回调。相反，此函数返回用于获取数据的流。

每行作为数据事件返回。查询元数据可通过元数据事件获得。结束事件表示查询结果的结束。收到结束事件后，应调用Stream destroy（）函数以正确清理资源。任何进一步的提取逻辑结束，特别是连接释放，都应该处于关闭事件中。或者，可以使用Stream destroy（）方法提前终止流。

有关调整，请调整选项fetchArraySize和prefetchRows的值，请参阅调整提取性能。

Pool类

通过调用shentongdb.createPool（）方法创建连接池对象。

Pool对象使用getConnection（）方法从池中“取出”一个数据库的连接。内部调用接口会话池。

应用程序使用完连接池后，应释放所有连接并通过调用池对象上的close（）方法终止连接池。

属性

可以读取池对象属性以确定当前值。

pool.connectionsInUse

readonly Number connectionsInUse

连接池中当前活动的连接数，即使用pool.getConnection（）获得在用的连接数。

pool.connectionsOpen

readonly Number connectionsOpen

池中通过数据库连接的当前连接数。此数字是应用程序使用的连接数和池中空闲的连接数之和。

如果连接已断开，例如使用等待连接，则该值可能小于poolMin。关闭（｛drop:true｝），或者如果网络问题导致连接无法使用。

pool.connectString

readonly String connectString

用于连接到数据库实例的连接字符串。

pool.poolAlias

readonly Number poolAlias

连接池缓存中此池的别名。一旦创建了池，就不能更改别名。对于在未指定显式别名的情况下创建的第二个池和后续池，将未定义此属性。

pool.poolIncrement

readonly Number poolIncrement

每当连接请求超过当前打开的连接数时打开的连接数目。

pool.poolMax

readonly Number poolMax

连接池中可以打开的最大连接数。

pool.poolMin

readonly Number poolMin

连接池维护的最小连接数，即使目标数据库没有活动。

pool.poolPingInterval

readonly Number poolPingInterval

连接在连接池中空闲时间保持最大的秒数。（未通过getConnection（）签出到应用程序）

pool.poolTimeout

readonly Number poolTimeout

池终止空闲连接（池中未使用）的时间（秒）。连接数不会低于poolMin。

pool.queueMax

readonly Number queueMax

pool.getConnection（）最大挂起个数。

pool.queueTimeout

readonly Number queueTimeout

在请求终止之前，连接请求应在队列中等待的时间（毫秒）。

pool.sessionCallback

      readonly Function sessionCallback
readonly String sessionCallback

Node.js或PL/SQL函数。当连接是全新的时，使用getConnection（）。

pool.status

readonly Number status

返回下来值之一：

shentongdb.POOL_STATUS_OPEN, POOL_STATUS_DRAINING, 或 POOL_STATUS_CLOSED

pool.stmtCacheSize

readonly Number stmtCacheSize

每个连接的语句缓存中要缓存的语句数。

pool.user

readonly String user

池中连接的数据库用户名。

方法

pool.close()

原型

回调

close([Number drainTime,] function(Error error){});

承诺

promise = close([Number drainTime]);

描述

此调用关闭池中的连接并终止连接池。

pool.getConnection()

原型

回调

getConnection([Object poolAttrs,] function(Error error, Connection connection){});

承诺

promise = getConnection([Object poolAttrs]);

描述

此方法从连接池获得连接。

如果池中存在以前打开的连接，则返回该连接。如果池中的所有连接都在使用中，则创建一个新连接并将其返回给调用方，只要连接数不超过池中指定的最大值。如果池处于最大限制，则getConnection（）调用会导致错误，例如ORA-24418:无法打开更多会话。

默认情况下，创建池时将齐次设置为true。创建池时提供用户名和密码。每次都是游泳池。调用getConnection（），则返回该用户的连接：

const connection = await pool.getConnection();

如果在创建过程中通过将“同构”设置为false创建了异构池，并且省略了凭据，则可以在池中使用用户名和密码。getConnection（）类似于：

const connection = await pool.getConnection(
  {
        user     : 'sysdba',
        password : 'szoscar55',
  });,

在这种情况下，每个时间池可以使用不同的用户名。调用getConnection（）。还可以指定代理用户。

pool.reconfigure()

原型

回调

reconfigure(Object poolAttrs, function(Error error){});

承诺

promise = reconfigure(Object poolAttrs);

描述

允许更改池创建属性的子集，而无需重新启动池或重新启动应用程序。可以更改池中的最大连接数或连接使用的语句缓存大小等属性。

属性是可选的。未指定的属性将使这些池属性保持不变。属性分两个阶段处理。在处理任何大小更改后，将按顺序重新配置其他属性。如果在更改一个属性时发生错误（如无效值），则将抛出错误，但任何已更改的属性将保留其新值。

在重新配置过程中，将创建一个池。状态将是POOL_status_reconfiguration，并且：

任何游泳池。getConnection（）调用将排队，直到池重新配置且连接可用。对这些请求进行排队时，队列超时和队列最大值设置在池中时生效。调用getConnection（）。

用connection.close()关闭连接等待重新配置完成。

在重新配置期间尝试关闭池将引发错误。

await pool.reconfigure({poolMin: 5, poolMax: 10, increment: 5});

Lob类

Lob对象可用于访问数据库CLOB和BLOB数据。

一个Lob对象处理的Node.js流接口。

有关详细信息，请参见大对象使用章节。

属性

Lob对象的属性如下所示：

lob.chunkSize

readonly Number chunkSize

这对应于数据库LOB层在访问或修改LOB值时使用的大小。

lob.length

readonly Number length

查询的LOB的长度，以字节（对于BLOB）或字符（对于CLOB）为单位。

lob.pieceSize

Number pieceSize

为查询的LOB的每个流数据事件读取的字节数（对于BLOB）或字符数（对于CLOB）。

默认值为chunkSize。

为了提高效率，建议将pieceSize设置为chunkSize的倍数。

该属性不应在流媒体处理过程中重置，因为调整内部缓冲区的大小时，数据将丢失。

分段大小的最大值限制为UINT_MAX的值。

lob.type

readonly Number type

此只读属性显示正在使用的Lob类型。它将具有一个常数shentongdb.BLOB，shentongdb.CLOB。当使用LOB绑定变量时，该值从绑定类型派生，或者当查询返回LOB时，从列类型派生。

方法

lob.close()

原型

回调

close(function(Error error){});

承诺

promise = close();

描述

显式关闭Lob。

使用createLob（）创建的LOB在不再需要时应显式关闭。这将释放数据库中的资源。

只要当前未发生流传输，从数据库返回的持久或临时LOB也可以关闭。注意：这些LOB在流式传输完成或用作入/出绑定的源时自动关闭。如果尝试关闭用于流式传输的Lob，将出现错误NJS-023：不允许对Lob执行并发操作。

调用lob时，连接必须打开。临时LOB上的close（），例如由createLob（）创建的LOB。Lob一旦关闭，就无法绑定。

pool.destroy()

原型

destroy([Error error]);

描述

此同步方法显式销毁Lob。

使用createLob（）创建的lob应使用lob显式关闭。不再需要时销毁（）。

从数据库返回的持久或临时lob也可以使用lob.destroy（）关闭。注意：这些LOB在流式传输完成或用作入/出绑定的源时自动关闭。

Lob一旦被销毁，就无法使用。

pool.getData()

原型

回调

getData(function(Error error, String data));
getData(function(Error error, Buffer data));

承诺

promise = getData();

描述

返回所有LOB数据。Clob将作为字符串返回。blob将作为缓冲区返回。此方法可用于长度不超过1 GB的LOB。

对于返回LOB列的查询，使用fetchAsString、fetchAsBuffer或fetchInfo而不是LOB.getData（）可能更有效。

注意：这是一种异步方法，需要往返数据库：

const data=await myLob.getData（）；

ResultSet类

结果集允许从数据库中一次提取一个查询结果，或按行分组提取查询结果。它们还可以转换为可读流。结果集使应用程序能够处理非常大的数据集。

当查询行数无法预测且可能大于节点数时，也应使用结果集。js可以在单个数组中处理。

执行查询时，通过在Connection execute（）方法的options参数中设置ResultSet:true，可以获得ResultSet对象。当绑定为shentongdb类型时，结果集也会返回到node-shentongdb。

属性

Lob对象的属性如下所示：

resultset.metaData

readonly Array metaData

包含一个对象数组，其中包含有关查询或引用游标列的元数据。

每一列的名称总是给定的。如果是shentongdb.extendedMetaData或execute（）选项extendedMetaData为true，则包含其他信息。

resultset.lastRowid

readonly String lastRowid

受INSERT、UPDATE、DELETE或MERGE语句影响的行的ROWID。对于其他语句，或者如果没有行受到影响，则不设置它。

如果影响了多行，则仅返回最后一行的ROWID,Rowid本质返回的是具有auto_increment属性列的值。

方法

resultset.close()

原型

回调

close(function(Error error){});

承诺

promise = close();

描述

关闭结果集。应用程序应始终在提取结束时或不需要更多行时调用此函数。如果从未从结果集中提取任何行，也应该调用它。

resultset.getRow()

原型

回调

getRow(function(Error error, Object row){});

承诺

promise = getRow();

描述

此调用将ResultSet的一行作为对象或列值数组获取，具体取决于outFormat的值。

在抓取结束时，应通过调用close（）释放ResultSet。

要进行调整，请调整连接的值。execute（）选项：fetchArraySize和prefetchRows。必须在从数据库获取结果集时设置这两个值。事后设置它们没有效果。有关调优的更多信息，请参阅调优获取性能。

resultset.getRows()

原型

回调

getRows([Number numRows,] function(Error error, Array rows){});

承诺

promise = getRows([Number numRows]);

描述

此函数从结果集中获取numRows行。返回值是一个对象或列值数组，具体取决于outFormat的值。可以连续调用以获取所有行。

在抓取结束时，应通过调用ResultSet.close（）释放ResultSet。

如果未传递任何参数，或者numRows为零，则将获取所有行。从技术上讲，如果之前发生了对getRow（）或getRows（numRows）的其他调用，则这会从ResultSet中提取所有剩余的行。对于作为绑定变量返回的小结果集，使用getRows（）获取所有行非常方便，请参阅REF CURSOR bind Parameters。对于已知返回少量行的普通查询，不使用结果集更容易。

numRows的不同值可能会改变从数据库获取数据所需的时间。“预取行”值也会产生影响。当numRows为零时，或者没有参数传递给getRows（），则可以使用fetchArraySize的值进行调优。从数据库获取结果集时，必须同时设置prefetchRows和fetchArraySize。事后设置它们没有效果。有关调优的更多信息，请参阅调优获取性能。

resultset.toQueryStream()

原型

toQueryStream();

描述

此同步方法将结果集转换为可读流。

它可用于使来自顶级查询或来自REF CURSOR bind变量的结果集可流化。为了使顶级查询可流化，可选择的连接。queryStream（）方法可能更容易使用。

要更改toQueryStream（）的行为，如设置查询输出格式或内部缓冲区大小以提高性能，请调整全局属性，如shentongdb.outFormat，shentongdb.fetchArraySize和shentongdb.prefetchRows在调用execute（）之前设置。