API.md

connection-pool-party

• connection-pool-party
  • .ConnectionPoolParty ⇐ EventEmitter
    • new ConnectionPoolParty(config, [cb])
    • .warmup([cb]) ⇒ Promise
    • .request() ⇒ mssql.Request
    • .close([cb]) ⇒ Promise
    • .stats() ⇒ Object
  • .forceFqdnConnectionPoolFactory(suffix) ⇒ Promise

connection-pool-party.ConnectionPoolParty ⇐ EventEmitter

Kind: static class of connection-pool-party
Extends: EventEmitter

• .ConnectionPoolParty ⇐ EventEmitter
  • new ConnectionPoolParty(config, [cb])
  • .warmup([cb]) ⇒ Promise
  • .request() ⇒ mssql.Request
  • .close([cb]) ⇒ Promise
  • .stats() ⇒ Object

new ConnectionPoolParty(config, [cb])

Class representing a ConnectionPoolParty, which manages one or more ConnectionPool instance(s). ConnectionPoolParty extends the mssql package to provide failover between ConnectionPools, reconnets/retries, and basic health/statistics reporting.

Param	Type	Default	Description
config	object		Configuration for ConnectionPoolParty
[config.reconnects]	number	0	The number of times a request will be retried against ALL pools. A heal operation is attempted before a reconnect. Total request attempts is calculated using: pools * (1+reconnects) * (1+retries)
[config.retries]	number	0	The number of times a request will be retried against a single pool. Each pool is retried separately. Total request attempts is calculated using: pools * (1+reconnects) * (1+retries)
[config.dsn]	object		A single DSN, matches the configuration object expected by the mssql package. Required if dsns and dsnProvider are not provided.
[config.dsns]	array		An array of DSNs, each entry should match the configuraiton object expected by the mssql package. Overrides config.dsn. Required if dsn and dsnProvider are not provided.
[config.dsnProvider]	function		A function returning a promise that resolves with an array of dsn object(s). This option will override config.dsn and config.dsns. Required if dsn and dsns are not provided.
[config.connectionPoolFactory]	function		A function that receives the dsn objects from the dnsProvider and returns a promise that resolves with connected instance(s) of ConnectionPool. Use this option if you want to customize how mssql ConnectionPools are instantiated and connected.
[config.connectionPoolConfig]	object		An object containing any configuration you want to attach to the config provided when creating an mssql ConnectionPool. This is useful if you don't want to create a custom dsnProvider or connectionPoolFactory to modify the configuration used to create ConnectionPools. Just keep in mind that any config set here will override the config set in the dsnProvider. Check node-mssql README.md for more information.
[config.connectionPoolConfig.options]	object		An object containing any configuration you want to pass all the way to driver used by node-mssql, e.g. appName, encrypt, etc. Check node-mssql README.md for more information.
[config.connectionPoolConfig.pool]	object		An object containing any configuration you want to pass to the pool implementation internal to node-mssql, e.g. max, min, idleTimeout, etc. Check node-mssql README.md for more information.
[config.prioritizePools]	boolean		A flag to enable pool prioritization behavior. If you enable this behavior, your dsns must have a numeric priority property. The lower the number, the higher the priority of the dsn, starting at 0. At a specified interval, the pools collection will be examined to see if the pools are no longer indexed in order of priority. If this is the case, the pools will be healed (if applicable) and re-ordered in terms of their priority. This is a useful behavior if you want to fail back to a "primary" dsn after it becomes healthy again.
[config.prioritizeInterval]	number	30000	The interval in milliseconds to run the pool prioritization check. Setting a value below 10000 is not advised, as the pool prioritization check can take significant resources if a pool heal is required.
[cb]	function		Optional callback interface, providing this automatically calls warmup. It is preferable to use the Promise-based interface and call warmup explicitly.

connectionPoolParty.warmup([cb]) ⇒ Promise

Retrieve the dsn(s) from the dsnProvider, create and connect the ConnectionPool instance(s) using the connectionPoolFactory. Returns a promise. Can be called to explicitly warmup database connections. Called implicitly when submitting any requests. After a successful warmup, subsequent calls will not warmup again.

Kind: instance method of ConnectionPoolParty
Returns: Promise - A promise indicating that a warmup was successful. This promise cannot reject, but errors during warmup will result in the cached warmup promise being removed, which will allow warmup to be re-attempted.

Param	Type	Description
[cb]	function	An optional callback interface. It is preferable to use the Promise-based interface.

connectionPoolParty.request() ⇒ mssql.Request

Retrieve a new Request instance. This is the same Request provided by the mssql package, but it's specially extended to interact with ConnectionPoolParty.

Kind: instance method of ConnectionPoolParty
Returns: mssql.Request - An extended instance of mssql.Request.

connectionPoolParty.close([cb]) ⇒ Promise

Close all pools associated with this instance of ConnectionPoolParty

Kind: instance method of ConnectionPoolParty
Returns: Promise - A Promise that resolves when all pools are closed. Will also resolve if there is an error encountered while closing the pools.

Param	Type	Description
[cb]	function	An optional callback interface. It is preferable to use the Promise-based interface.

connectionPoolParty.stats() ⇒ Object

Retrieve health and statistics for this ConnectionPoolParty and its associated pools.

Kind: instance method of ConnectionPoolParty
Returns: Object - An object containing a bunch of health/stats data for this instance of ConnectionPoolParty and its associated pools.

connection-pool-party.forceFqdnConnectionPoolFactory(suffix) ⇒ Promise

This connection pool factory is only needed for a niche use case, but it serves as an example of what is possible when creating a custom connectionPoolFactory.

If your dsn provider returns servers as hostnames instead of FQDNs or IPs, you may have systems that are unable to resolve the hostnames due to misconfigured DNS settings. If you are unable to fix the DNS resolution for whatever reason, and you know what the FQDN suffix is, you can use this connectionPoolFactory to add the suffix.

Kind: static method of connection-pool-party
Returns: Promise - A promise that uses a dsn provided by the dsnProvider to create an mssql ConnectionPool.

Param	Type	Description
suffix	string	The FQDN suffix to use if your dsn's server is provided as a hostname.