There are different configurations of a Crux node:
Name | Transaction Log | Java API |
---|---|---|
Cluster | Uses Kafka |
|
JDBC | Uses JDBC event log |
|
Standalone | Uses local event log |
|
Use a cluster node when horizontal scalability is required or when you want the guarantees that Kafka offers in terms of resiliency, availability, and retention of data.
Multiple cluster nodes participate in a cluster using Kafka as the primary store and as the central means of coordination.
The JDBC node is for when you don’t want the overhead of maintaining a Kafka cluster. Read more about the motivations of this setup here.
The Standalone node is where a single Crux instance has everything it needs locally. This is good for experimenting with Crux and for small to medium sized deployments, where running a single instance is permissible.
Crux nodes implement the ICruxAPI
interface and are the
starting point for making use of Crux. Nodes also implement
java.io.Closeable
and can therefore be lifecycle managed.
To see an example of a Crux Node being integrated into a Clojure lifecycle management framework such as Integrant, see the example Integrant node. |
The follow properties are required for any type of Crux Node:
Component | Property | Description |
---|---|---|
kv-store |
| Sets the K/V Store to use, e.g. |
kv-store |
| Sets the data-directory to use, e.g. |
tx-log |
| Kafka Servers to connect to e.g. |
http-server |
| Port for Crux HTTP Server e.g. |
Using a Crux standalone node is the best way to get started. Once you’ve started a standalone Crux instance as described below, you can then follow the getting started example.
Component | Property | Description |
---|---|---|
tx-log |
| where to store events locally, i.e. |
link:./deps.edn[role=include]
link:./examples.clj[role=include]
You can later stop the node if you wish:
link:./examples.clj[role=include]
When using Crux at scale it is recommended to use multiple Crux nodes connected via a Kafka cluster.
The following properties are required for a Kafka Cluster Node:
Component | Property | Description |
---|---|---|
tx-log |
| Kafka Servers to connect to e.g. |
link:./deps.edn[role=include]
Use the API to start a cluster node, configuring it with the
bootstrap-servers
property in order to connect to Kafka:
link:./examples.clj[role=include]
If you don’t specify kv-backend then by default the
cluster node will use RocksDB. You will need to add RocksDB to
your list of project dependencies.
|
You can later stop the node if you wish:
link:./examples.clj[role=include]
JDBC Nodes use next.jdbc
internally and pass through the relevant configuration options that
you can find
here.
Below is the minimal configuration you will need:
Property | Description |
---|---|
| One of: postgresql, oracle, mysql, h2, sqlite |
| Database Name |
| Database Host |
| Database Username |
| Database Password |
| For h2 and sqlite |
Add crux-jdbc
to your project dependencies:
Use the API to start a JDBC node, configuring it with the required parameters:
link:./examples.clj[role=include]
Set the following properties when configuring RocksDB in Crux:
Property | Value |
---|---|
|
|
| i.e. |
For example when constructing the standalone node:
link:./examples.clj[role=include]
Crux can be used programmatically as a library, but Crux also ships with an embedded HTTP server, that allows clients to use the API remotely via REST.
Set the server-port
configuration property on a Crux node to
expose a HTTP port that will accept REST requests:
Component | Property | Description |
---|---|---|
http-server |
| Port for Crux HTTP Server e.g. |
Visit the guide on using the REST api for examples of how to interact with Crux over HTTP.
If you want to experiment with Crux using a demo Docker container from Docker Hub (no JVM/JDK/Clojure install required, only Docker!) then please see the standalone web service example. You can also use this self-contained demonstration image to experiment with the REST API.
Crux provides utility APIs for local backup and restore when you are using the standalone mode. For an example of usage, see the standalone web service example.
An additional example of backup and restore is provided that only applies to a stopped standalone node here.
In a clustered deployment, only Kafka’s official backup and restore functionality should be relied on to provide safe durability. The standalone mode’s backup and restore operations can instead be used for creating operational snapshots of a node’s indexes for scaling purposes.
Crux is ready to work with an embedded Kafka for when you don’t have a indepently running Kafka available to connect to (such as during development).
Add crux-kafka-embedded
to your project dependencies:
See the below example code:
link:./examples.clj[role=include]
You can later stop the Embedded Kafka if you wish:
link:./examples.clj[role=include]
Can you improve this documentation? These fine people already did:
Jeremy Taylor, Jon Pither, Ben Gerard, Ivan Fedorov, Antonelli712 & Alex DavisEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close