Skip to content

JDBC

Martini Server Runtime enables seamless connection to various Java Database Connectivity (JDBC) relational (SQL) databases and facilitates SQL operations execution against them. Ensure the appropriate drivers are installed for smooth database connectivity.

Configuring JDBC in Martini

Martini offers pooled database connections that can be effortlessly configured. Here's a straightforward guide to adding a new database connection:

Configuring JDBC in Martini Server Runtime

Via API Explorer: Database connections can be configured using the Martini API Explorer, a user-friendly interface designed for efficient interaction with the system's APIs. Follow these steps to configure the database connections through the API Explorer:

  1. Access the API Explorer: Open a web browser and go to localhost:8080/api-explorer/ to access the API Explorer.

  2. Navigate to the Database Tag: Locate and click on the database tag within the API Explorer to view various database configuration and operation endpoints.

  3. Configure Connection Pool: Use the esbapi/databases endpoint found under the database tag to save a database connection pool.

  4. Use POST to Save a Connection Pool: Save the connection pool by using the POST method at the /esbapi/databases endpoint. Here is an example of how to format your JSON payload:

1
2
3
4
5
6
 {
  "name": "string",
  "type": "string",
  "status": "string",
  "autoStart": "string"
 }

Via File System: Alternatively, database connections can also be modified directly in the file system by editing the <jdbc_name>.dbxml file located in the /<martini-home>/conf/db-pool/ directory. This method is particularly useful for environments where API access is restricted or during initial setup stages.

To modify database connections directly through the file system, follow these steps:

  1. Locate the Configuration File: Navigate to the /<martini-home>/conf/db-pool/ directory on your server and locate the <jdbc_name>.dbxml file.

  2. Edit the Database Connections: Open the <jdbc_name>.dbxml file in a text editor and modify the database connection properties.

  3. Save and Restart: After making the desired changes, save the file. It is essential to restart the Martini Runtime instance to apply the new settings. This ensures that all components of the application use the updated JDBC configuration.

Configuring JDBC in Martini Designer

  1. Navigate to the Navigator view and right-click on the Databases node of the instance where you intend to add the database connection.
  2. Choose New > Martini Database.
  3. Specify a name for the connection and select the desired database type (e.g., relational/SQL).
  4. Fill in the database connection details in the provided form.
  5. Save the changes.

Testing Database Connections

While optional, it's advisable to test the database connectivity before saving any changes to ensure successful connection establishment.

Installing Additional Database Drivers

Martini Server Runtime utilizes JDBC drivers for database connectivity. Besides the built-in drivers, you can install additional drivers using their JAR files.

Installing a New Driver

To add a new database driver:

  1. Obtain the respective driver JAR file.
  2. Place the JAR file in the <martini-home>/lib/ext/ directory.
  3. Restart Martini Server Runtime.

After this process, the newly installed driver will be visible for selection when adding a new database connection.

Database Properties

The table below outlines the configurable properties for a database connection:

Field Name Required Default Value Description
Name true null Name of the database connection.
Auto Start false true Whether the database connection should start when Martini starts up.
Use XA false false Whether or not to enable XA transactions.
Driver Class true null The JDBC driver for the database you are connecting to.
URL true null The URL of the JDBC database you are connecting to.
Username true null Username to use when connecting to the database.
Password false null Password to use when connecting to the database.
Acquire Increment false 1 Controls how many connections are filled into the pool when the pool is empty but the maxPoolSize has not been reached.
Acquisition Interval false 1 Controls how long (in seconds) the pool waits between attempts to create new connections.
Acquisition Timeout false 30 Controls how long (in seconds) to wait for a pool connection request to succeed before being aborted (and throwing an exception).
Login Timeout false 0 Controls how long (in seconds) to wait for a successful authentication against the database server. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it assumes that there is no timeout.
Allow Local Transactions false true Whether or not you want to be able to run SQL statements outside of XA transactions scope.
Apply XA Transaction Timeout false false Whether or not the transaction timeout will be passed to the resource via XAResource#setTransactionTimeout(int).
Enlist to XA Automatically false true Controls whether connections from the PoolingDataSource are automatically enlisted or delisted in XA transactions.
Defer Connection Release false false Set this parameter to false if the vendor's XADataSource implementation supports the interleaving of transactions.
Enable JDBC4 Connection Test false false If your JDBC driver supports JDBC4, this method of testing the connection is likely much more efficient than using the testQuery parameter.
Ignore Recovery Failures false false Determines whether recovery errors should be ignored or not. This is useful in development environments.
Maximum Idle Time false 60 When the pool is above the minPoolSize, this parameter controls how long (in seconds) an idle connection will stay in the pool before being retired.
Isolation Level false READ_COMMITTED Sets the default isolation level. All of the four standard values (READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ and SERIALIZABLE) are supported.
Minimum Pool Size false 0 The minimum number of active connections the pool will try to keep.
Maximum Pool Size false 5 The maximum number of active connections allowed in the pool.
Prepared Statements Cache Size false 0 Controls how many prepared statements are cached (per connection) by Bitronix.
Share Transaction Connections false false Determines whether or not connections share the same thread context.
Test Query false null In contrast with enableJdbc4ConnectionTest, this query is sent to the database to determine whether or not a connection is still usable.
Two-Phase Commit Order Position false 0 Controls the position of this resource during the 2PC protocol execution; used to guarantee the order of commits.
Unique Name false "Name" Required for crash recovery; uses "Name" if empty.
Use Transaction Manager Join false true Set this parameter to false if the vendor's XADataSource implementation does not implement XAResource#isSameRM(...) properly.

Configuration

Follow these steps to modify the properties of a database connection:

  1. Stop the database connection you want to configure.
  2. Right click on the database connection and click Configure from the context menu.
  3. Edit the properties of the database connection in the displayed editor.
  4. Save your changes.