Configuring JDBC on Martini Server Runtime
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.
Martini offers pooled database connections that can be effortlessly configured. Here's a straightforward guide to adding a new database connection:
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:
-
Access the API Explorer: Open a web browser and go to
localhost:8080/api-explorer/
to access the API Explorer. -
Navigate to the Database Tag: Locate and click on the
database
tag within the API Explorer to view various database configuration and operation endpoints. -
Configure Connection Pool: Use the
esbapi/databases
endpoint found under the database tag to save a database connection pool. -
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 |
|
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:
-
Locate the Configuration File: Navigate to the
/<martini-home>/conf/db-pool/
directory on your server and locate the<jdbc_name>.dbxml
file. -
Edit the Database Connections: Open the
<jdbc_name>.dbxml
file in a text editor and modify the database connection properties. -
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
- Navigate to the Navigator view and right-click on the Databases node of the instance where you intend to add the database connection.
- Choose New > Martini Database.
- Specify a name for the connection and select the desired database type (e.g., relational/SQL).
- Fill in the database connection details in the provided form.
- 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:
- Obtain the respective driver JAR file.
- Place the JAR file in the
<martini-home>/lib/ext/
directory. - 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 | Parameters | Required | Default Value | Description |
---|---|---|---|---|
Name | name |
true | null | Name of the database connection. |
Auto Start | autoStart |
false | true |
Whether the database connection should start when Martini starts up. |
Type | type |
true | null | Selects the database type. (jdbc , cassandra , redis , mongodb , aws-sqs , gcp-bigtable ) |
Use XA | xa |
false | false |
Whether or not to enable XA transactions. |
Driver Class | driverClassName |
true | null | The JDBC driver for the database you are connecting to. |
URL | url |
true | null | The URL of the JDBC database you are connecting to. |
Username | username |
true | null | Username to use when connecting to the database. |
Password | password |
false | null | Password to use when connecting to the database. Passwords will be encrypted after running. |
Acquire Increment | acquireIncrement |
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 | acquisitionInterval |
false | 1 |
Controls how long (in seconds) the pool waits between attempts to create new connections. |
Acquisition Timeout | acquisitionTimeout |
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 | loginTimeout |
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 | allowLocalTransactions |
false | true |
Whether or not you want to be able to run SQL statements outside of XA transactions scope. |
Auto Commit | autoCommit |
false | true |
Determines how transactions are handled in your database. |
Apply XA Transaction Timeout | applyTransactionTimeout |
false | false |
Whether or not the transaction timeout will be passed to the resource via XAResource#setTransactionTimeout(int) . |
Enlist to XA Automatically | automaticEnlistingEnabled |
false | true |
Controls whether connections from the PoolingDataSource are automatically enlisted or delisted in XA transactions. |
Defer Connection Release | deferConnectionRelease |
false | false |
Set this parameter to false if the vendor's XADataSource implementation supports the interleaving of transactions. |
Enable JDBC4 Connection Test | enableJdbc4ConnectionTest |
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 | ignoreRecoveryFailures |
false | false |
Determines whether recovery errors should be ignored or not. This is useful in development environments. |
Maximum Idle Time | maxIdleTime |
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 | isolationLevel |
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 | minPoolSize |
false | 0 |
The minimum number of active connections the pool will try to keep. |
Maximum Pool Size | maxPoolSize |
false | 5 |
The maximum number of active connections allowed in the pool. |
Prepared Statements Cache Size | preparedStatementCacheSize |
false | 0 |
Controls how many prepared statements are cached (per connection) by Bitronix. |
Share Transaction Connections | shareTransactionConnections |
false | false |
Determines whether or not connections share the same thread context. |
Test Query | testQuery |
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 | twoPcOrderingPosition |
false | 0 |
Controls the position of this resource during the 2PC protocol execution; used to guarantee the order of commits. |
Unique Name | uniqueName |
false | "Name" |
Required for crash recovery; uses "Name" if empty. |
Use Transaction Manager Join | useTmJoin |
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:
- Stop the database connection you want to configure.
- Right click on the database connection and click Configure from the context menu.
- Edit the properties of the database connection in the displayed editor.
- Save your changes.