Data Store Properties

MicroTx Distributed Transactions coordinator supports the following storage types:

db: Oracle Database 19c and later
etcd: etcd
embedded_db: embedded LevelDB-based local storage
memory: in-memory storage

Oracle Database and etcd are centralized data stores. They provide shared, durable storage that can be accessed by all coordinator replicas. Use these storage types when you need a common external store for transaction state, recovery, and coordination across replicas.

The embedded LevelDB-based local storage type uses an embedded LevelDB-based store on the coordinator instance. When session affinity is enabled, requests for a transaction are routed to the same coordinator replica, allowing the embedded database to act as local persistent storage. This avoids the network hop and contention associated with centralized stores such as Oracle Database or etcd, and can improve transaction processing performance. The embedded database is suitable for production deployments that use session affinity and are designed around local coordinator storage. When you want to use multiple replicas of the transaction coordinator, you must set up an etcd cluster or Oracle Database as the transaction log data store.

The in-memory storage type stores transaction data only in memory. Use it for local development, testing, and samples. If you use internal memory, you can't create multiple replicas of the transaction coordinator. It is not intended for production because data is lost when the coordinator restarts.

Type of Data Store for Transaction Logs and Limit for Record Retention

Under coordinator.tmmConfiguration.storage, specify the type of data store that MicroTx Distributed Transactions uses for persistence of transaction state. After specifying the type of data store, you can provide additional details to connect to the external data store.

Only records of transactions that have reached a final state, irrespective of whether it is success or failure, are deleted. When any one of the limits specified in completedTransactionTTL, batchInterval, or thresholdFactor is reached, it triggers the deletion of the completed transaction records.

Completed transaction records are retained for the duration specified by completedTransactionTTL. After this TTL expires, records that are in a final state are added to the deletion queue. The coordinator deletes queued records in batches when either the configured batchInterval elapses or the number of queued records reaches the threshold calculated from thresholdFactor.

Only completed transaction records are deleted. Active or in-progress transaction records are not deleted by this cleanup process.

For etcd storage, completed records are removed automatically using the etcd lease TTL. For other storage types, the coordinator runs the batch deletion loop.

Property	Description
`type`	Enter one of the following values to specify the persistent data that you want MicroTx Distributed Transactions to use to track the transaction information. `etcd` to use etcd as the data store. You must provide details to connect to the etcd data store in the `storage.etcd` field. `db` to use Oracle Database as the data store. You must provide details to connect to the Oracle data store in the `storage.db` field. `memory` to skip entering details to connect to either etcd or Oracle Database and use the internal memory instead. When you use internal memory, all the transaction details are lost every time you restart MicroTx Distributed Transactions. `embedded_db` for embedded LevelDB-based local storage.
`completedTransactionTTL`	Specify the time to live, in seconds, for a completed transaction record in the transaction data store. After this period expires, the completed transaction record becomes eligible for deletion. The permissible range is 60 to 1200 seconds. If a lower value is configured, it is set to 60. If a higher value is configured, it is set to 1200. The default value is 60 seconds.
`batchInterval`	Specify the interval, in seconds, at which the coordinator checks and deletes queued completed transaction records in batches. If the interval has elapsed and the deletion queue is not empty, the coordinator deletes the queued records from the transaction data store. The default value is 180 seconds.
`thresholdFactor`	Specify an integer multiplier used to calculate the deletion threshold. The threshold is calculated as: `threshold = batchSize * thresholdFactor` The current `batchSize` is 1000. For example, if `thresholdFactor` is 2, completed transaction records are deleted when the deletion queue reaches 2000 records. The deletion channel capacity is calculated as: `channelSize = batchSize * thresholdFactor * bufferFactor` The current `bufferFactor` is 2. The default and recommended value is 2. Use the default value, unless you need to retain more queued completed records before triggering deletion. A higher value increases the number of records retained in the deletion queue before threshold-based deletion starts.

Oracle Database as Data Store for Transaction Logs

Under tmmConfiguration.storage.db, specify the details to connect to an Oracle Database. Skip this section and do not provide these values if you are connecting to an etcd database or using internal memory.

The following table specifies the properties required to connect to an Oracle Database as the MicroTx Distributed Transactions data store.

Property	Description
`connectionString`	Enter the connection string for the data store in Oracle Database. If you are using a database that uses a credential wallet, such as Oracle Autonomous Transaction Processing, use the following format to enter the connection string: `tcps://<database-host>:<database-portNumber>/<service_name>` You can find the required details, such as protocol, host, port, and service name in the `tnsnames.ora` file, which is located in folder where you have extracted the credential wallet. See Download Client Credentials (Wallets) in Using Oracle Autonomous Database on Shared Exadata Infrastructure. For example: `tcps://adb.us-phoenix-1.oraclecloud.com:1521/sales.adb.oraclecloud.com` Additionally, you can pass database timeout parameters, such as `retry_count` and `retry_delay`, by appending it to the connection string. For example, `<connection-string>?retry_count=20&retry_delay=3` If you are using a non-autonomous Oracle Database (a database that does not use a credential wallet), use the following format to enter the connection string: `<database-host-IPaddress>:<database-portNumber>/<databaseUniqueName>.<hostDomainName>` For example: `123.213.85.123:1521/CustDB_iad1vm.sub05031027070.customervcnwith.oraclevcn.com` Where, `CustDB_iad1vm.sub05031027070.customervcnwith` is the unique name of the database or the service name. If you are using Oracle RAC database, see About Connecting to an Oracle RAC Database Using SCANs.
`credentialSecretName`	Enter the name of the Kubernetes secret that contains the credentials to connect to the Oracle Database. Example, `db-secret`. See Create a Kubernetes Secret for Oracle Database Credentials.
`connectionParams`	Enter a space-separated list of connection parameters. For details about the connection parameters that you can specify, see https://pkg.go.dev/github.com/godror/godror#section-documentation. For example, `poolMinSessions=1 poolMaxSessions=300`
`walletConfigMap.configMapName`	Provide a value for this field only if you connect to a database that uses a credential wallet, such as Autonomous Database. For other databases, you can leave this field empty. Enter the name of the configuration map that you have created for the credential wallet of the Autonomous Database instance. See Get Autonomous Database Client Credentials. For example, `db-wallet-configmap`.

etcd Database as Data Store for Transaction Logs

Under tmmConfiguration.storage.etcd, specify the details to connect to an etcd database. Skip this section and do not provide these values if you are connecting to an Oracle Database or are using internal memory.

The following table specifies the properties required to connect to an etcd database as the MicroTx Distributed Transactions data store.

Before you provide this information, ensure that you complete the following tasks and note down the required details.

Property	Description
`endpoints`	Enter the external IP address of the etcd database server. If you have installed the etcd cluster in the Kubernetes cluster where you will install MicroTx Distributed Transactions, then provide the Kubernetes service name and the port of the etcd cluster (nodes) as values. Otherwise, enter a comma-separated list of host names or IP addresses of the etcd cluster nodes along with the ports, such as `198.51.100.1:4002,198.51.100.2:4002,198.51.100.3:4002`.
`skipHostNameVerification`	Set this to `false` to verify the IP address of the etcd database server. If you set this to `true`, then the server host name or IP address is not verified. You can set this field to `true` only for test or development environments. Caution: You must set this field to `false` in production environments.
`credentialSecret.secretName`	Enter the path to the Kubernetes secret in the container. The secret contains the client credentials, client key, and the password that you have used to protect the client certificate. For example, `/etc/otmm/etcd-cert-secret`. See Create a Kubernetes Secret for etcd.
`credentialSecret.secretFileName`	Enter the location of the JSON file, that contains client credentials, client key, and the password that you have used to protect the client certificate. For example, `/etc/otmm/etcdecred.json`. See Generate RSA Certificates for etcd.
`cacertConfigMap.configMapName`	Enter the name of the configuration map file, which you had created while initializing the certificate authority. For example, `etcd-ca-cert-map`. See Create a Kubernetes Secret for etcd.
`cacertConfigMap.configMapFileName`	Enter the name of the PEM file that you had created while initializing the certificate authority. For example, `ca.pem`. See Generate RSA Certificates for etcd.

The following code snippet provides sample value which are based on the sample values provided in the Generate RSA Certificates for etcd and Create a Kubernetes Secret for etcd topics.

storage:
    type: etcd
    etcd:
      endpoints: "https://198.51.100.1:4002"
      skipHostNameVerification: "false"
      credentialSecret:
        secretName: "etcd-cert-secret"
        secretFileName: "etcdecred.json"
      cacertConfigMap:
        configMapName: "etcd-ca-cert-map"
        configMapFileName: "ca.pem"

If you do not provide the correct IP address for the endpoints field, then host verification fails when you install MicroTx Distributed Transactions.

4.2.4.5 Data Store Properties