System Properties

Datomic's Java system properties are all named via the convention datomic.somePropertyName.

Memory settings can be specified in plain bytes, or use k / m / g suffixes for kilobytes / megabytes / gigabytes, e.g. 256m.

Example property files are in the config/samples directory of the Datomic distribution.

Reading Properties Files

Each property has a comment describing its use, plus one or more of the tags below:

Property tag	Meaning
Required	No reasonable default, you must set this property
Defaulted	Setup will default this property for you
Generated	Setup will generate a unique value for you
Optional	Property is not required

Peer Properties

Datomic Peer properties should be set using command line arguments, for example:

-Ddatomic.txTimeoutMsec=60000

Property	Use	Units	Default
datomic.ddbRequestTimeout	Amount of time a DDB request must complete before timing out	Integer milliseconds	1000
datomic.memcachedExpirationDays	Please contact support before attempting to use this setting	Integer	30
datomic.memcachedPassword	Memcached password	String	{None}
datomic.memcachedServers	Memcached server list	host:port(,host:port)*	{None}
datomic.memcachedUsername	Memcached username	String	{None}
datomic.memcachedAutoDiscovery	Auto discovery of Memcached nodes	Boolean	False
datomic.memcachedConfigTimeoutMsec	Timeout for Elasticache auto-discovery	Integer milliseconds	100
datomic.objectCacheMax	Size of object cache	Bytes	50% of VM RAM, min 32m
datomic.readConcurrency	Soft limit on concurrent storage reads	Integer	2x write concurrency
datomic.txTimeoutMsec	Timeout for transact	Integer milliseconds	10000
datomic.metricsCallback	Callback for reporting peer metrics	String	{none}
datomic.valcachePath	Valcache SSD directory	String	{None}
datomic.valcacheMaxGb	Maximum GB Valcache will try to use	Gigabytes	{None}
datomic.prefetchConcurrency	Limit on concurrent reads supporting datomic.api/with	Integer	half of available CPUs
datomic.prefetchProbes	Whether to prefetch reads supporting datomic.api/with	Boolean	true when >= 2 CPUs

Transactor Properties

The equivalent names in the transactor properties file have no namespace, and are hyphen delimited lowercase, e.g. some-property-name. The exception to this rule is the transactor property corresponding to `datomic.memcachedServers`, which is called `memcached`.

The transactor script provided with Datomic expects the properties file to be the last argument.

Note that JVM args other than `-Xmx` and `-Xms` passed to `bin/transactor` (including Java system properties passed via `-D`) override Datomic's default Java options, including the GC settings.

System property	Use	Units	Default	Where to set
datomic.cassandraClusterCallback	Name of a callback method/fn returning a Cluster	String	{None}	Transactor properties file
datomic.ddbRequestTimeout	Amount of time a DDB request must complete before timing out	Integer milliseconds	1000	Command line arg
datomic.heartbeatIntervalMsec	Interval between heartbeat write to storage	Integer milliseconds	5000, min 1000
datomic.licenseKey	Transactor license key	String	{None}	Transactor properties file
datomic.memcachedPassword	Memcached password	String	{None}	Transactor properties file
datomic.memcachedServers	Memcached server list	host:port (,host:port)*	{None}	Transactor properties file
datomic.memcachedUsername	Memcached username	String	{None}	Transactor properties file
datomic.memcachedAutoDiscovery	Auto discovery of memcached nodes	Boolean	False	Command line arg or transactor properties file
datomic.memcachedConfigTimeoutMsec	Timeout for Elasticache auto-discovery	Integer milliseconds	100	Command line arg or transactor properties file
datomic.memoryIndexThreshold	Size that kicks off indexing job	Bytes	{see recommendations}	transactor properties file
datomic.memoryIndexMax	Transactions throttle to let index job catch up	Bytes	{See recommendations}	Transactor properties file
datomic.gcStoragePaceMsec	Paces gc-storage delete operations	Integer (msec)	0	Command line arg
datomic.metricsCallback	The name of a static Java method or Clojure fn	String	RAM	Transactor properties file
datomic.objectCacheMax	Size of object cache	Bytes	50% of VM RAM, min 32mb	Transactor properties file
datomic.pidFile	Write pid to this file on startup	Filename	{None}	Transactor properties file
datomic.printConnectionInfo	Print connection info at startup	Boolean	False	Command line arg
datomic.sqlUser	Username for SQL storage	String	{None}	Command line arg or transactor properties file
datomic.sqlPassword	Password for SQL storage	String	{None}	Command line arg or transactor properties file
datomic.sqlValidationQuery	Query used to validate JDBC connections	String	{See storage docs}	Transactor properties file
datomic.readConcurrency	Soft limit on concurrent storage reads	Integer	2x write concurrency	Transactor properties file
datomic.writeConcurrency	Soft limit on concurrent storage writes	Integer	4	Transactor properties file
datomic.prefetchConcurrency	Limit on concurrent transaction-supporting reads	Integer	half of available CPUs	Command line arg or transactor properties file
datomic.prefetchProbes	Whether to prefetch transaction-supporting reads	Boolean	true when >= 2 CPUs	Command line arg or transactor properties file

Backup Properties

Property	Use	Units	Default
datomic.backupPaceMsec	Interval to pause between backup writes	Integer milliseconds	{None}
datomic.fileBackupConcurrency	Number of threads used for file backup/restore	Integer	5
datomic.s3BackupConcurrency	Number of threads used for s3 backup/restore	Integer	25

Note that:

backupPaceMsec can reduce I/O pressure by slowing the pace of backups.
datomic.fileBackupConcurrency affects the number of concurrent read/writes on local storage.
datomic.s3BackupConcurrency affects the number of concurrent read/writes when backing up to S3.

Properties Changes

In 0.8.3814, datomic.objectCacheBytes was deprecated, and renamed to datomic.objectCacheMax.
In 0.8.4110, the defaults for datomic.objectCacheMax, datomic.memoryIndexThreshold, and datomic.memoryIndexMax were removed on the transactor, so that the transactor properties file must now specify values for these properties. Peer defaults remain as described above.
datomic.licenseKey is valid only for Datomic 1.0.6711 version or older.