Martini Database Connection Pool Functions

Overview

Martini's Database Connection Pool Functions, generated from DatabaseConnectionPoolMethods, let your workflows and services manage the lifecycle of a Martini database connection programmatically, instead of only through the Database navigator. Most of these functions work with any registered connection type — JDBC (SQL) as well as NoSQL connections such as Cassandra, MongoDB, and Redis — while a smaller set apply only to JDBC connections; see Available Database Connection Pool Functions for the full breakdown.

These functions are typically used to provision or activate a database connection as part of a package's own startup logic — for example, creating a connection pool the first time a package runs, or conditionally starting one based on an environment variable — rather than requiring a developer to configure it manually every time the package is deployed.

What You Will Learn

What a connection pool is and how its enabled and running status relate to each other
How to retrieve existing connection pools with getConnectionPoolInfos, getConnectionPoolInfo, and containsConnectionWithName
How to enable, disable, start, and stop a connection pool by name
How to create or update a connection pool at runtime with savePool, and remove one with deletePool
How to validate connection details before saving them with testConnection
How to check whether Martini supports a given JDBC driver with supportsDriver
How to retrieve or create a system connection pool with getSystemConnectionPoolInfo

When To Use This

Use Database Connection Pool Functions when:

You need to create a database connection pool automatically during package startup, instead of asking every developer to configure it by hand in the Database navigator
You want to enable, disable, start, or stop a connection pool conditionally, based on runtime logic such as an environment variable or a feature flag
You need to validate a set of connection details — host, driver, credentials — before persisting them, for example inside a setup wizard your package exposes to end users
You need to confirm Martini supports a particular JDBC driver before attempting to connect with it
You need to inspect existing connection pools' configuration or status from within a workflow or service, for diagnostics or administration tooling

Prerequisites

Martini Designer installed and running
A Martini package with at least one service or workflow to invoke the functions from
Familiarity with SQL Database Connection, since savePool creates and manages the same kind of connection pool you can configure through the Database navigator

Database Connection Pool Functions Reference

Database Connection Pool Functions Key Terms

Term	Definition
name	The unique identifier of a connection, matching the name it is registered under in Martini Runtime, regardless of connection type (JDBC or NoSQL).
connectionPoolInfo	A model reference of `io.toro.martini.jdbc.JDBCConnectionPoolInfo`, describing a JDBC connection's configuration — see Connection Pool Properties.
enabled	A persisted property controlling whether a connection automatically starts the next time Martini starts — distinct from whether it is running right now.
driverClass	The fully qualified JDBC driver class name a JDBC connection uses to connect to its database.

Available Database Connection Pool Functions

Most of these functions reference a connection only by its name and work with any connection type — JDBC or NoSQL (Cassandra, MongoDB, Redis, and so on). A smaller set instead read or write the connectionPoolInfo model, which is specific to JDBC connections; these are called out in the Connection Types column below.

Function	What It Does	Connection Types
`getConnectionPoolInfos()`	Returns every JDBC connection configured in the Martini instance.	JDBC only
`getConnectionPoolInfo(name)`	Returns the JDBC connection registered under `name`, if one exists.	JDBC only
`containsConnectionWithName(name)`	Returns whether a connection named `name` exists.	JDBC and NoSQL
`enablePool(name)`	Sets the `enabled` property of the connection named `name` to `true`, so it auto-starts on the next Martini startup.	JDBC and NoSQL
`disablePool(name)`	Sets the `enabled` property of the connection named `name` to `false`, so it no longer auto-starts.	JDBC and NoSQL
`startPool(name)`	Starts the connection named `name` right now, establishing it as an active, usable connection.	JDBC and NoSQL
`stopPool(name)`	Stops the connection named `name` right now, closing its active connections.	JDBC and NoSQL
`savePool(connectionPoolInfo)`	Creates a new JDBC connection, or updates the existing one if `connectionPoolInfo.name` already matches a saved connection.	JDBC only
`deletePool(name)`	Permanently removes the connection named `name`.	JDBC and NoSQL
`testConnection(connectionPoolInfo)`	Attempts to open a JDBC connection using `connectionPoolInfo` without saving it, throwing an exception on failure.	JDBC only
`supportsDriver(driverClass)`	Returns whether Martini supports the JDBC driver identified by the `driverClass` `Class`.	JDBC only
`getSystemConnectionPoolInfo(name)`	Returns the JDBC connection info for the system data source named `name`, creating it first if it doesn't exist.	JDBC only

Understanding `enabled` vs. Started

Every connection pool has two independent aspects to its status: whether it is enabled (a persisted setting that survives restarts) and whether it is currently started (its live, in-memory running state). Mixing these up is one of the most common sources of confusion when managing pools programmatically.

Action	Changes `enabled`?	Changes running state right now?
`enablePool`	Sets to `true`	No
`disablePool`	Sets to `false`	No
`startPool`	No	Starts the pool immediately
`stopPool`	No	Stops the pool immediately

To have a pool both running now and auto-starting on every future Martini startup, call enablePool and startPool together. Calling only startPool on a disabled pool starts it for the current session, but it will not auto-start the next time Martini restarts unless you also call enablePool — or set enabled: true when you call savePool.

Getting Started with Creating and Starting a Pool

This example creates a PostgreSQL connection pool named orders-db and starts it, typically as part of a package's own startup logic.

flowchart LR
    s["Start Trigger"]
    a["`**Function Node:** containsConnectionWithName('orders-db')`"]
    b{"Pool exists?"}
    c["`**Function Node:** savePool(connectionPoolInfo)`"]
    d["`**Function Node:** startPool('orders-db')`"]
    e[...]
    s --> a --> b
    b -- No --> c --> d --> e
    b -- Yes --> e

Step 1: Check whether the pool already exists

In a Function Node, invoke containsConnectionWithName('orders-db') and branch on the result so you don't overwrite a pool a developer or administrator has already customized.

Step 2: Create the pool

When the pool doesn't exist yet, invoke savePool with a connectionPoolInfo model populated with at least the required properties:

savePool(
    connectionPoolInfo: [
        name: 'orders-db',
        driverClass: 'org.postgresql.Driver',
        url: 'jdbc:postgresql://localhost:5432/orders',
        username: 'orders_app',
        password: 'secret',
        enabled: true,
        maxPoolSize: 10
    ]
)

Step 3: Start the pool

Invoke startPool('orders-db') to make the connection available immediately.

Expected result: A connection pool named orders-db appears in the Database navigator's connections list, already started, and it auto-starts on every future Martini startup because enabled was set to true.

Connection Pool Properties

connectionPoolInfo, passed to savePool and testConnection and returned by getConnectionPoolInfo, getConnectionPoolInfos, and getSystemConnectionPoolInfo, is a model reference of io.toro.martini.jdbc.JDBCConnectionPoolInfo. The properties below cover the core connection details most integrations need.

Property	Required	Default	Description
`name`	Yes	—	The unique name of the connection pool.
`driverClass`	Yes	—	The fully qualified JDBC driver class name to use.
`url`	Yes	—	The JDBC connection URL.
`username`	Yes	—	The username used to authenticate with the database.
`password`	Yes	—	The password used to authenticate with the database.
`enabled`	No	`true`	Whether the pool auto-starts on Martini startup — see Understanding `enabled` vs. Started.
`xa`	No	`false`	Whether this connection participates in XA (distributed) transactions.
`maxPoolSize`	No	`5`	The maximum number of active connections the pool allows at once. Override this for production workloads.
`minPoolSize`	No	`0`	The minimum number of active connections the pool tries to keep open.
`testQuery`	No	—	A SQL statement used to test whether a connection is still alive before it's returned from the pool.

Advanced pooling and XA transaction properties

JDBCConnectionPoolInfo also exposes lower-level tuning properties — acquireIncrement, acquisitionInterval, acquisitionTimeout, maxIdleTime, preparedStatementCacheSize, loginTimeout, isolationLevel, and autoCommit — plus properties specific to XA/JTA transaction coordination via the Bitronix transaction manager Martini uses internally: allowLocalTransactions, applyTransactionTimeout, automaticEnlistingEnabled, deferConnectionRelease, enableJdbc4ConnectionTest, ignoreRecoveryFailures, shareTransactionConnections, twoPcOrderingPosition, uniqueName, and useTmJoin. Most integrations can leave these at their defaults; adjust them only when you have a specific performance or distributed-transaction requirement. startupError is a read-only property that Martini populates with any error encountered while starting the pool.

Retrieving and Inspecting Connection Pools

Use getConnectionPoolInfos and getConnectionPoolInfo to read a JDBC connection's current configuration — including its enabled flag and any startupError — without needing to open the Database navigator.

getConnectionPoolInfos() returns every JDBC connection configured in the Martini instance, useful for building diagnostic or administrative tooling.
getConnectionPoolInfo('orders-db') returns the single connection named orders-db, or an empty result if it hasn't been created yet.
containsConnectionWithName('orders-db') returns true or false, which is cheaper than fetching the full connectionPoolInfo when you only need to know whether the connection exists — for example, before deciding whether to call savePool.

Testing a Connection Before Saving It

testConnection(connectionPoolInfo) attempts to open a connection using the details you provide, without persisting a pool. Use it to validate connection details — for example, ones a user entered into a setup form — before calling savePool.

testConnection(
    connectionPoolInfo: [
        name: 'orders-db',
        driverClass: 'org.postgresql.Driver',
        url: 'jdbc:postgresql://localhost:5432/orders',
        username: 'orders_app',
        password: 'secret'
    ]
)

Expected result: the call completes normally if a connection can be established. If it cannot, testConnection throws an exception describing the failure — catch it with a Try/Catch Node in a workflow, or a try/catch block step in a service, to surface a friendly validation message instead of failing the whole workflow or service.

Checking Driver Support with `supportsDriver`

supportsDriver(driverClass) returns whether Martini supports the JDBC driver identified by a Class object, letting you validate a driver before offering it to a user or attempting a connection with it.

supportsDriver(driverClass: Class.forName('org.postgresql.Driver'))

Expected result: returns true if Martini supports the supplied driver class, or false if that loaded class is not a supported JDBC driver. If the driver dependency is missing, loading it with Class.forName fails before supportsDriver is called.

Managing System Connection Pools with `getSystemConnectionPoolInfo`

getSystemConnectionPoolInfo(name) retrieves the connection pool info for a system data source — an internal connection pool Martini itself relies on — identified by name. Unlike getConnectionPoolInfo, if no system data source exists yet with the given name, Martini creates one automatically and returns its info, so you never need to check for existence first.

Database Connection Pool Functions Benefits and Use Cases

Managing connection pools through functions, instead of only through the Database navigator, lets you treat database connectivity as part of your package's own logic:

Zero-touch provisioning — Create the connection pools a package needs the first time it starts, so deploying the package to a new environment doesn't require a manual configuration step.
Environment-driven configuration — Read connection details from environment variables or a secrets store at startup, then call savePool with those values instead of hardcoding them in a dbxml file.
Setup wizards — Validate a user-supplied connection with testConnection before saving it with savePool, giving immediate feedback instead of a failure deep inside a later workflow run.
Conditional lifecycle management — Start or stop specific connection pools based on a feature flag, license state, or maintenance window, using startPool and stopPool.
Cleanup automation — Remove connection pools that are no longer needed with deletePool, for example when decommissioning a tenant-specific database.

Troubleshooting Database Connection Pool Function Issues

Problem	Detection	Cause	Fix
`getConnectionPoolInfo` returns an empty result	No connection pool details returned for a known name	The `name` passed doesn't exactly match a saved pool's name	Confirm the exact pool name with `getConnectionPoolInfos()` or in the Database navigator, including case
`savePool` doesn't seem to update an existing pool	Configuration changes aren't reflected after saving	`connectionPoolInfo.name` doesn't match the existing pool's name, so a new pool was created instead	Pass the exact `name` of the pool you intend to update
Pool doesn't auto-start after a Martini restart	`startPool` worked earlier, but the pool is stopped after restart	`enabled` on the pool is `false`, so it isn't set to auto-start	Call `enablePool(name)`, or set `enabled: true` in `connectionPoolInfo` the next time you call `savePool`
`testConnection` throws an exception even with correct credentials	Connection attempt fails during validation	The JDBC driver isn't installed as a package dependency, or the database isn't reachable from Martini	Confirm `supportsDriver` returns `true` for the driver class, and that the database host/port is reachable
`startPool` throws an exception	Pool remains stopped after calling `startPool`	The connection details are invalid, or the database is unreachable — check `startupError` on `getConnectionPoolInfo`	Inspect `connectionPoolInfo.startupError` for the underlying cause, then correct the connection details and retry
`deletePool` fails or the pool reappears	Pool still exists after calling `deletePool`	A dependency package, service, or workflow still references the pool and Martini recreated it	Remove any references to the pool from services and workflows before deleting it

Helpful Resources

SQL Database Connection — Create and manage the same connection pools through the Database navigator
SQL Functions — Run SQL statements and manage transactions against a connection pool created here
Configuring Databases on Martini Server Runtime — Understand the underlying dbxml files these functions manage
Managing JDBC Connections — Monitor connection pool usage and detect connection leaks at runtime
Martini Triggers — Start a workflow that provisions a connection pool during package startup
Community Q&A: Martini Community
Have a question? Post or search it here.