Transactor Reference
Running the Transactor
A Datomic transactor performs ACID transactions for a set of databases. You can launch a transactor for one or more databases with the bin/transactor script in the Datomic directory:
cd /home/user/datomic/datomic-pro-1.0.7187
Once your storage service is configured, you can start the transactor locally by running bin/transactor. It takes a properties file as input. The file varies depending on the storage service:
- For Dev and SQL, make a copy of the appropriate template properties file in config/samples and edit it as desired.
- If you are using a Heroku-hosted PostgreSQL instance, edit your sql-transactor-template.properties as follows:
- Add the Heroku-provided host and database name to the JDBC URL in the sql-url property.
- Put the username and password in the sql-user and sql-password properties.
- Uncomment the sql-driver-params property and set it to:
sql-driver-params=ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory
- When you run the transactor locally against DynamoDB, specify AWS access keys using either environment variables (AWS_SECRET_KEY and AWS_ACCESS_KEY_ID) or Java system properties (aws.secretKey and aws.accessKeyId). You can use your AWS account access keys or a set of IAM user access keys. If you use IAM user access keys, the user must be assigned the necessary policies. Running locally this way should only be considered for development and is not a supported means for handling permissions in production.
For more information on configuring the transactor review the transactor properties section of the documentation.
- To start the transactor, run the following command, passing in your
properties file:
noslide
bin/transactor my-transactor.properties
Check configuring high availability for information on launching a second transactor for high availability.
If you set a pid-file
in the transactor properties file, Datomic
will write the current process ID to that file on startup.
The transactor startup script accepts JVM arguments, but note that JVM args other than -Xmx
and -Xms
passed to bin/transactor
(including Java system properties passed via -D
) override Datomic's recommended Java options, including the GC settings.
JVM Argument | Dev default setting | Prod default setting |
---|---|---|
Max Heap | Xmx1g | Xmx4g |
Initial Heap size | Xms1g | Xms4g |
GC Settings | -XX:+UseG1GC | -XX:+UseG1GC |
-XX:MaxGCPauseMillis=50 | -XX:MaxGCPauseMillis=50 |
Check storage services and peers for information on supported storages and how transactors interact with peers.
Health Check Endpoint
A web endpoint for a health check is not needed for the Datomic transactor. The Datomic transactor is not a web application, and Datomic high availability takes care of transactor health automatically.
- However, some tools have a checklist requirement that all processes
provide a health check endpoint. If you need one, Datomic Pro lets you set a health check host and port in the transactor properties file:
ping-host=localhost ping-port=9999
- Or on the command line:
bin/transactor -Ddatomic.pingHost=localhost -Ddatomic.pingPort=9999 {etc.}
When the health check is enabled, Datomic will respond with a 2xx status code to HTTP requests for {host}:{port}/health, e.g.
wget localhost:9999/health
=> HTTP request sent, awaiting response... 200 OK
TrustStore and KeyStore
If you are accessing Cassandra via SSL, you must provide a
- Java TrustStore for the transactor to use when connecting to storage.
- The TrustStore must contain one or more certificates that can be used to verify the
identity of the storage node(s) the transactor is connecting to.
- Provide a Java KeyStore that the transactor will use to establish an SSL connection with peers.
- Use the standard Java system properties to specify the TrustStore and KeyStore:
noslide
bin/transactor -Djavax.net.ssl.trustStore=path-to-truststore -Djavax.net.ssl.trustStorePassword=password-for-truststore -Djavax.net.ssl.keyStore=path-to-keystore -Djavax.net.ssl.keyStorePassword=password-for-keystore my-transactor.properties
Check the Troubleshooting section for more info if you get an exception when trying to start the transactor with SSL.
If you are not using SSL to access Cassandra, Datomic configures a KeyStore for the transactor and a TrustStore for peers automatically.
If the console output includes a line of the form shown below, it means that the transactor is working correctly:
System started {URI}
The URI is used by peers to attach to the system. Check the JavaDoc for Peer.connect() for the full connection details.
The transactor requires a Java 1.6+ Server VM. By default, the transactor runs with 1GB memory pool. You can change the default by passing a -Xmx flag, as you would when you launch a JVM application directly.
Note that transactors and peers that use DynamoDB will have the best performance running on EC2. You can test them locally to ensure the correct configuration, but should deploy them to EC2 for the best performance.
Connecting to the Transactor
After the transactor is running, you can test the configuration using the Datomic shell. You need the storage-specific connection URI as described in the JavaDoc for Peer.connect().
After connecting to storage, peers will look up the transactor endpoint. The transactor writes the value of the host transactor property in storage, and this is the address peers will attempt to connect to. If the transactor cannot bind to its publicly reachable IP address (e.g. the transactor is on a VM that doesn't own or can't see its external address), you will need to provide a value for alt-host on the transactor with the publicly reachable IP address in addition to the host property. If the peers cannot reach the transactor using host they will use the alt-host address instead.
If you are accessing Cassandra via SSL, you must provide a Java TrustStore for the peer to use. The TrustStore must contain one or more certificates that can be used to verify the identity of the storage node(s) the peer is connecting to. The TrustStore must also contain the certificate that can be used to verify the identity of the transactor. You specify a TrustStore using the standard Java system properties:
noslide
-Djavax.net.ssl.trustStore=path-to-truststore -Djavax.net.ssl.trustStorePassword=password-for-truststore
Check the Troubleshooting section for more info if you get an exception when trying to connect a peer when using SSL.
If you are not using SSL to access Cassandra, Datomic configures a KeyStore for the transactor and a TrustStore for peers automatically.
The code below shows how to create and connect to a database using the Datomic shell:
bin/shell
datomic % uri = <uri-for-storage-service>;
datomic % Peer.createDatabase(uri);
datomic % conn = Peer.connect(uri);
Configuring Options
Once you have verified that your transactor is working with your storage configuration, you can configure and test additional options, such as memcached.
To enable the use of Memcached, uncomment the memcached entry in your transactor properties file. Then set its value to a comma-delimited list of host:port pairs naming your memcached endpoints:
memcached=m1.example.com:11211,m2.example.com:11211
When you restart the transactor, it will transparently use Memcached.
Check the Caching documentation for more information on configuring Memcached.
Running on AWS
Once you know everything is working, you may want to run your transactor on AWS if you are planning on using other AWS services, specifically Dynamo DB. The document running on AWS contains the instructions.
Troubleshooting SSL Connections
The following error message indicates that the transactor or peer cannot communicate with the storage nodes. Verify that you can connect to the storage nodes using other tools; for instance a simple Cassandra cqlsh. Also, verify that the TrustStore contains the certificates necessary for connecting to the storage nodes.
Typical error message when unable to connect to Cassandra via SSL:
com.datastax.driver.core.exceptions.NoHostAvailableException: All host(s) tried for query failed
If you see the following error message, this indicates that the transactor and peer are not configured with the same SSL information. Verify the transactor KeyStore and peer TrustStore are properly configured.
HornetQNotConnectedException HQ119007: Cannot connect to server(s). Tried with all available servers. org.hornetq.core.client.impl.ServerLocatorImpl.createSessionFactory