Modules
	SQL Pool Tracing

Typedefs
typedef struct M_sql_connpool	M_sql_connpool_t

Enumerations
enum	M_sql_connpool_flags_t { M_SQL_CONNPOOL_FLAG_NONE = 0 , M_SQL_CONNPOOL_FLAG_PRESPAWN_ALL = 1 << 0 , M_SQL_CONNPOOL_FLAG_NO_AUTORETRY_QUERY = 1 << 1 , M_SQL_CONNPOOL_FLAG_LOAD_BALANCE = 1 << 2 }

Functions
M_sql_error_t	M_sql_connpool_create (M_sql_connpool_t *pool, const char driver, const char conn_str, const char username, const char password, size_t max_conns, M_uint32 flags, char error, size_t error_size)

M_sql_error_t	M_sql_connpool_add_readonly_pool (M_sql_connpool_t pool, const char conn_str, size_t max_conns, char *error, size_t error_size)

void	M_sql_connpool_set_timeouts (M_sql_connpool_t *pool, M_time_t reconnect_time_s, M_time_t max_idle_time_s, M_time_t fallback_s)

M_sql_error_t	M_sql_connpool_start (M_sql_connpool_t pool, char error, size_t error_size)

M_sql_error_t	M_sql_connpool_destroy (M_sql_connpool_t *pool)

size_t	M_sql_connpool_active_conns (M_sql_connpool_t *pool, M_bool readonly)

const char *	M_sql_connpool_server_version (M_sql_connpool_t *pool)

const char *	M_sql_connpool_driver_display_name (M_sql_connpool_t *pool)

const char *	M_sql_connpool_driver_name (M_sql_connpool_t *pool)

const char *	M_sql_connpool_driver_version (M_sql_connpool_t *pool)

Detailed Description

SQL Connection Management

Typedef Documentation

◆ M_sql_connpool_t

typedef struct M_sql_connpool M_sql_connpool_t

Connection pool object

Enumeration Type Documentation

◆ M_sql_connpool_flags_t

enum M_sql_connpool_flags_t

Flags controlling behavior of the connection pool

Enumerator
M_SQL_CONNPOOL_FLAG_NONE	No special pool flags
M_SQL_CONNPOOL_FLAG_PRESPAWN_ALL	Pre-spawn all connections, not just the first. Without this, the remaining connections are on-demand
M_SQL_CONNPOOL_FLAG_NO_AUTORETRY_QUERY	If a non-transactional query is rolled back due to a deadlock or connectivity failure, the default behavior is to automatically retry the query, indefinitely. For queries executed as part of a transaction, rollbacks must be handled by the caller as they may be dependent on prior queries in the transaction. This flag will turn off the auto-retry logic
M_SQL_CONNPOOL_FLAG_LOAD_BALANCE	If there are multiple servers specified for the connection string, this will load balance requests across the servers instead of using them for failover.

Function Documentation

◆ M_sql_connpool_create()

M_sql_error_t M_sql_connpool_create	(	M_sql_connpool_t **	pool,
		const char *	driver,
		const char *	conn_str,
		const char *	username,
		const char *	password,
		size_t	max_conns,
		M_uint32	flags,
		char *	error,
		size_t	error_size
	)

Create an SQL connection pool.

A connection pool is required to be able to run SQL transactions. An internal connection is automatically claimed for a transaction or statement, or will wait on an available connection.

Note: The pool is not started untile M_sql_connpool_start() is called, which must occur before the pool can be used by M_sql_stmt_execute() or M_sql_trans_begin().

Warning: Pool modifications such as M_sql_connpool_add_readonly_pool() and M_sql_connpool_add_trace() must be called prior to M_sql_connpool_start().

Parameters

[out]	pool	Newly initialized pool object
[in]	driver	Name of driver to use. If the driver is not already loaded, will attempt to load the driver module automatically. Driver modules are named mstdlib_sql_$driver.dll or mstdlib_sql_$driver.so as appropriate.
[in]	conn_str	A driver-specific connection string or DSN. This string often configures the host/port, and available options for the driver in use. The connection strings are a set of key/value pairs, with keys seperated from the values with an equal sign (=), and values separated by a semi-colon (;). If quoting is in use, a single-quote (') is recognized, and an escape character of a single quote (') can be used such that to use a real single quote, you would use two single quotes. E.g. : host=10.130.40.5:3306;ssl=yes Please see the documentation for your driver for available configuration options.
[in]	username	Connection username.
[in]	password	Connection password.
[in]	max_conns	Maximum number of SQL connections to attempt to create. Valid range 1-1000.
[in]	flags	Bitmap of M_sql_connpool_flags_t options to configure.
[out]	error	Buffer to hold error message.
[in]	error_size	Size of error buffer passed in.

Returns: M_SQL_ERROR_SUCCESS on successful pool creation, otherwise one of the M_sql_error_t errors.

◆ M_sql_connpool_add_readonly_pool()

M_sql_error_t M_sql_connpool_add_readonly_pool	(	M_sql_connpool_t *	pool,
		const char *	conn_str,
		size_t	max_conns,
		char *	error,
		size_t	error_size
	)

Create a read-only pool attached to our already-created pool.

The read-only pool will automatically route SELECT transactions, not part of a transaction (e.g. not within a M_sql_trans_begin() ... M_sql_trans_commit() block) to the read-only pool. This can be useful for report generation, where the data is coming from an asyncronous replication pool for reducing load on the master.

Note: The caller can optionally use M_sql_stmt_set_master_only() to enforce routing of SELECT transactions to the read/write pool instead.

The read-only pool must share the same driver, username, password, and usage flags as specified via M_sql_connpool_create(), and must be called before M_sql_connpool_start().

Only a single read-only pool per pool object is allowed, repeated calls to this function will result in a failure.

Parameters

[in]	pool	Initialized pool object by M_sql_connpool_create().
[in]	conn_str	A driver-specific connection string or DSN. This string often configures the host/port, and available options for the driver in use. The connection strings are a set of key/value pairs, with keys seperated from the values with an equal sign (=), and values separated by a semi-colon (;). If quoting is in use, a single-quote (') is recognized, and an escape character of a single quote (') can be used such that to use a real single quote, you would use two single quotes. E.g. : host=10.130.40.5:3306;ssl=yes Please see the documentation for your driver for available configuration options.
[in]	max_conns	Maximum number of SQL connections to attempt to create. Valid range 1-1000.
[out]	error	Buffer to hold error message.
[in]	error_size	Size of error buffer passed in.

Returns: M_SQL_ERROR_SUCCESS on successful readonly pool creation, otherwise one of the M_sql_error_t errors.

◆ M_sql_connpool_set_timeouts()

void M_sql_connpool_set_timeouts	(	M_sql_connpool_t *	pool,
		M_time_t	reconnect_time_s,
		M_time_t	max_idle_time_s,
		M_time_t	fallback_s
	)

Set timeouts for connections on the pool. Timeouts can be used to prevent stale connections from being used if known firewall timers expire, or to force reconnects to possibly rebalance connections across multiple servers.

Typically these should be set before M_sql_connpool_start() however it is safe to change these on an active pool.

Parameters

[in]	pool	Initialized connection pool object
[in]	reconnect_time_s	How many seconds to allow a connection to be used before a disconnection is forced. The connection will be terminated even if not idle, termination will occur when a connection is returned to the pool instead of prior to use to prevent unexpected delays. This can be used to either redistribute load after a node failure when load balancing, or to fall back to a prior host. Set to 0 for infinite, set to -1 to not change the current value. Default is 0.
[in]	max_idle_time_s	Maximum amount of time a connection can have been idle to be used. Some firewalls may lose connection state after a given duration, so it may be advisable to set this to below that threshold so the connection will be forcibly terminated rather than use. The connection will be terminated before use and the consumer will attempt to grab a different connection from the pool, or start a new one if none are available. Set to 0 for infinite, set to -1 to not change the current value. Default is 0.
[in]	fallback_s	Number of seconds when a connection error occurs to a host before it is eligible for "fallback". If this isn't set, the only time the first host will be re-used is if the secondary host(s) also fail. This should be used in conjunction with reconnect_time_s. Set to 0 to never fallback, or -1 to not change the current value. Not relevant for load balancing, the host will always be in the attempt pool. Default is 0.

◆ M_sql_connpool_start()

M_sql_error_t M_sql_connpool_start	(	M_sql_connpool_t *	pool,
		char *	error,
		size_t	error_size
	)

Start the connection pool and make it ready for use.

At least one connection from the primary pool, and optionally the read-only pool will be started, controlled via the M_SQL_CONNPOOL_FLAG_PRESPAWN_ALL flag.

If this returns a failure, either it can be attempted to be started again, or should be destroyed with M_sql_connpool_destroy(). No other functions are eligible for use after a failed start.

Note: This must be called once prior to being able to use M_sql_stmt_execute() or M_sql_trans_begin(), but must be called after M_sql_connpool_add_readonly_pool() or M_sql_connpool_add_trace().

Parameters

[in]	pool	Initialized pool object by M_sql_connpool_create().
[out]	error	Buffer to hold error message.
[in]	error_size	Size of error buffer passed in.

Returns: M_SQL_ERROR_SUCCESS on successful readonly pool creation, otherwise one of the M_sql_error_t errors.

◆ M_sql_connpool_destroy()

M_sql_error_t M_sql_connpool_destroy ( M_sql_connpool_t * pool )

Destroy the SQL connection pool and close all open connections.

All connections must be idle/unused or will return a failure.

Parameters

[in] pool Pool object to be destroyed

Returns: M_SQL_ERROR_SUCCESS on successful pool destruction, otherwise one of the M_sql_error_t errors.

◆ M_sql_connpool_active_conns()

size_t M_sql_connpool_active_conns	(	M_sql_connpool_t *	pool,
		M_bool	readonly
	)

Count of active/connected SQL connections (but not ones that are in process of being brought online).

Parameters

[in]	pool	Initialized pool object
[in]	readonly	M_TRUE if querying for readonly connections, M_FALSE for primary

Returns: count of active/connected SQL connections.

◆ M_sql_connpool_server_version()

const char * M_sql_connpool_server_version ( M_sql_connpool_t * pool )

SQL server name and version

Parameters

[in] pool Initialized pool object

Returns: SQL server name and version

◆ M_sql_connpool_driver_display_name()

const char * M_sql_connpool_driver_display_name ( M_sql_connpool_t * pool )

SQL driver display (pretty) name

Parameters

[in] pool Initialized pool object

Returns: SQL driver pretty name

◆ M_sql_connpool_driver_name()

const char * M_sql_connpool_driver_name ( M_sql_connpool_t * pool )

SQL driver internal/short name

Parameters

[in] pool Initialized pool object

Returns: SQL driver internal/short name

◆ M_sql_connpool_driver_version()

const char * M_sql_connpool_driver_version ( M_sql_connpool_t * pool )

SQL driver version (not db version)

Parameters

[in] pool Initialized pool object

Returns: SQL driver version (not db version)

Modules

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ M_sql_connpool_t

Enumeration Type Documentation

◆ M_sql_connpool_flags_t

Function Documentation

◆ M_sql_connpool_create()

◆ M_sql_connpool_add_readonly_pool()

◆ M_sql_connpool_set_timeouts()

◆ M_sql_connpool_start()

◆ M_sql_connpool_destroy()

◆ M_sql_connpool_active_conns()

◆ M_sql_connpool_server_version()

◆ M_sql_connpool_driver_display_name()

◆ M_sql_connpool_driver_name()

◆ M_sql_connpool_driver_version()