Cassandra

Cassandra is a highly scalable, distributed NoSQL database designed for high availability and performance. When integrated with the Martini runtime, Cassandra provides a robust data storage solution optimized for handling large volumes of data with minimal downtime and quick access speeds.

Configuring Cassandra

Configuring Cassandra involves setting up various parameters to optimize the database's performance, availability, and scalability based on your specific use case. Proper configuration ensures that Cassandra operates efficiently and reliably, meeting the demands of high-throughput and large-scale data environments. Here’s a straightforward guide to adding a new database connection:

Configuration Guide

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 [HOST]: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 a minimum requirement for a JSON payload:

    {
        "name": "[name]",
        "autoStart": true,
        "type": "cassandra",
        "contactPoints": [
            "[HOST]" 
        ],
        "port": 9042, 
        "credentials": {
            "username": "", 
            "password": ""   
        },
        "ssl": false 
    }
   

   • contactPoints: At least one contact point (hostname or IP address) must be specified for the database connection.
   • port: The default port for Cassandra is 9042. If you are using a custom port, update this value accordingly.
   • credentials: Populate the username and password fields if authentication is required.
   • ssl: Set this to true if SSL encryption is needed for the connection.

This provides the necessary structure for saving a connection pool via the /esbapi/databases endpoint using a POST request.

Via File System: Alternatively, database connections can be modified directly in the file system by editing the <name>.dbxml file located in the /<martini-home>/conf/db-pool/ directory. The <name>.dbxml file refers to the specific file for your database configuration. This method is particularly useful in environments with restricted API access 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 <name>.dbxml file.

2. Edit the Database Connections: Open the <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 Cassandra configuration. Here is a minimum requirement for a dbXML:

    <database>
        <name>[name]</name>
        <autoStart>true</autoStart>
        <type>cassandra</type>
        <contactPoints>
            <contactPoint0>[HOST]</contactPoint0> <!-- At least one contact point is required -->
        </contactPoints>
        <port>9042</port> <!-- Port number for connecting to the database; edit if using a custom port -->
        <credentials>
            <username></username> <!-- Username for authentication; populate if required -->
            <password></password> <!-- Password for authentication; populate if required -->
        </credentials>
        <ssl>false</ssl> <!-- Set to true if using SSL -->
    </database>
   

Database Properties

The table below outlines the configurable properties for a database connection: Refer to the Cassandra Documentation for more information on the values.

Field Name	Parameters	Required	Default Value	Description
Name	name	true	null	The name of the database connection.
Auto Start	autoStart	false	true	Whether the database connection should start automatically.
Type	type	true	null	The type of database (e.g., cassandra).
Contact Points	contactPoints	true	null	The contact points or hosts where the database is reachable.
Port	port	true	9042	The port number used to connect to the database.
Max Schema Agreement Wait Seconds	maxSchemaAgreementWaitSeconds	false	10	The maximum time in seconds to wait for schema agreement.
Compression	compression	false	NONE	The compression method used for data. Options may include NONE, SNAPPY, LZ4, etc.
Metrics	metrics	false	true	Whether metrics collection is enabled.
SSL	ssl	false	false	Whether SSL should be used for the connection.

Credentials

Field Name	Parameters	Required	Default Value	Description
Username	username	false	(empty)	The username required for authentication.
Password	password	false	(empty)	The password required for authentication.

Pooling Options

Field Name	Parameters	Required	Default Value	Description
Core Connections Per Host Local	coreConnectionsPerHostLocal	false	1	Number of core connections per local host.
Core Connections Per Host Remote	coreConnectionsPerHostRemote	false	1	Number of core connections per remote host.
Max Connections Per Host Local	maxConnectionsPerHostLocal	false	1	Maximum number of connections per local host.
Max Connections Per Host Remote	maxConnectionsPerHostRemote	false	1	Maximum number of connections per remote host.
New Connection Threshold Local	newConnectionThresholdLocal	false	800	Threshold for creating new connections per local host.
New Connection Threshold Remote	newConnectionThresholdRemote	false	200	Threshold for creating new connections per remote host.
Max Requests Per Connection Local	maxRequestsPerConnectionLocal	false	1024	Maximum number of requests per connection per local host.
Max Requests Per Connection Remote	maxRequestsPerConnectionRemote	false	256	Maximum number of requests per connection per remote host.
Idle Timeout Seconds	idleTimeoutSeconds	false	120	Time in seconds before an idle connection is closed.
Pool Timeout Millis	poolTimeoutMillis	false	5000	Timeout in milliseconds for acquiring a connection from the pool.
Max Queue Size	maxQueueSize	false	256	Maximum size of the connection queue.
Heartbeat Interval Seconds	heartbeatIntervalSeconds	false	30	Interval in seconds for heartbeat checks to maintain connection.

Socket Options

Field Name	Parameters	Required	Default Value	Description
Connect Timeout Millis	connectTimeoutMillis	false	5000	Timeout in milliseconds for connecting to the database.
Read Timeout Millis	readTimeoutMillis	false	12000	Timeout in milliseconds for reading from the database.
Keep Alive	keepAlive	false	true	Whether to keep the socket connection alive.
Reuse Address	reuseAddress	false	true	Whether to reuse local addresses.
SO Linger	soLinger	false	0	The SO_LINGER option value for the socket.
TCP No Delay	tcpNoDelay	false	true	Whether to disable Nagle's algorithm for TCP connections.
Receive Buffer Size	receiveBufferSize	false	0	The size of the receive buffer for the socket.
Send Buffer Size	sendBufferSize	false	0	The size of the send buffer for the socket.

Query Options

Field Name	Parameters	Required	Default Value	Description
Consistency Level	consistencyLevel	false	LOCAL_ONE	The consistency level for queries. (e.g., LOCAL_ONE, QUORUM).
Serial Consistency Level	serialConsistencyLevel	false	SERIAL	The serial consistency level for queries.
Fetch Size	fetchSize	false	5000	The number of rows to fetch per query.
Default Idempotence	defaultIdempotence	false	false	Whether to use idempotence by default for queries.
Prepare On All Hosts	prepareOnAllHosts	false	true	Whether to prepare queries on all hosts.
Reprepare On Up	reprepareOnUp	false	true	Whether to reprepare queries when nodes are up.
Refresh Schema Interval Millis	refreshSchemaIntervalMillis	false	1000	Interval in milliseconds for schema refresh.
Max Pending Refresh Schema Requests	maxPendingRefreshSchemaRequests	false	20	Maximum number of pending schema refresh requests.
Refresh Node List Interval Millis	refreshNodeListIntervalMillis	false	1000	Interval in milliseconds for node list refresh.
Max Pending Refresh Node List Requests	maxPendingRefreshNodeListRequests	false	20	Maximum number of pending node list refresh requests.
Refresh Node Interval Millis	refreshNodeIntervalMillis	false	1000	Interval in milliseconds for node refresh.
Max Pending Refresh Node Requests	maxPendingRefreshNodeRequests	false	20	Maximum number of pending node refresh requests.