Brightspot CMS Developer Guide

Database configuration

Database-specific configuration parameters are prefixed with the dari/database/{databaseName}/ namespace, where databaseName is a unique string. Multiple databases can be configured with different databaseName values. You can also set a default database, where data is stored when a database is not specified in an API call.

The following example from a Tomcat context.xml file shows how a namespace is used to identify configuration of a H2 database. In this case, the configuration is identified as tutorial.local; all configuration options for this database share the same namespace.

<!-- Database -->
<Environment name="dari/defaultDatabase" type="java.lang.String" value="tutorial.local"/>
<Environment name="dari/database/tutorial.local/class" type="java.lang.String" value="com.psddev.dari.h2.H2Database"/>
<Environment name="dari/database/tutorial.local/dataSource/class" type="java.lang.String" value="org.h2.jdbcx.JdbcDataSource"/>
<Environment name="dari/database/tutorial.local/dataSource/url" type="java.lang.String" value="jdbc:h2:/Users/rl/brightspot-tutorial/.h2"/>
<Environment name="dari/database/tutorial.local/dataSource/user" type="java.lang.String" value="root"/>
<Environment name="dari/database/tutorial.local/dataSource/password" type="java.lang.String" value=""/>

Dari database classes implement com.psddev.dari.db.Database. Most of the implementations are subclasses of AbstractDatabase. Another implementation, AggregateDatabase, provides the capability to use multiple databases. That is, the class aggregates multiple databases to appear as one database to your application.

Configuration options for frequently used databases are described below. For other supported databases, you can find their configuration options in the Dari Javadoc.

Dari provides the Database Bootstrap tool to migrate database objects from one Brightspot project to another. The tool must be configured to identify export and import databases. For more information, see Exporting and importing between databases.

The following table lists the configuration values for all supported databases.

dari/defaultDatabasejava.lang.StringName of the default database configuration. (For information about default configurations, see Configuration identifiers, key prefixes, and defaults.)
dari/database/{databaseName}/classjava.lang.StringClass name of a com.psddev.dari.db.Database implementation.
dari/database/{databaseName}/readTimeoutjava.lang.DoubleSets the read timeout for this database. The default is 3 seconds.
dari/database/{databaseName}/readTimeoutjava.lang.IntegerNumber of times to retry a transient failure. The default value is 10.
dari/databaseWriteRetryInitialPausejava.lang.IntegerInitial amount of time in milliseconds to wait before retrying a transient failure. The default value is 10ms.
dari/databaseWriteRetryFinalPausejava.lang.IntegerMaximum amount of time in milliseconds to wait before retrying a transient failure. The default value is 1000ms.

Amount of time to adjust the pause between retries so that multiple threads retrying at the same time will stagger. This helps break deadlocks in certain databases such as MySQL. The default value is 0.5.

The pause value is calculated as initialPause + (finalPause - initialPause) * i / (limit - 1). This is then jittered + or - pauseJitter percent. For example, if dari/databaseWriteRetryLimit is 10, dari/databaseWriteRetryFinalPause is 1000ms, and dari/databaseWriteRetryPauseJitter is 0.5, then on the first retry, Dari will wait between 5ms and 15ms. On the second try, Dari will wait between 60ms and 180ms, continuing until the 10th and final try, which will wait between 500ms and 1500ms.

The following table lists the configuration values for SqlDatabase.

dari/database/{databaseName}/classjava.lang.StringSet to com.psddev.dari.db.SqlDatabase for all SQL databases.

Enable or disable compression of Dari object data in the database. Dari uses the Snappy compression library for compression. The default is false. For best performance, enable compression only if your dataset is over 50GB.

To enable compression, you must include Snappy in your pom.xml file as follows:


dari/database/{databaseName}/dataSourceResourceDatabase resource. All writes will go the database configured by dataSource.
dari/database/{databaseName}/readDataSourceResourceOptional. To have reads go to a replica, configure readDataSource.
dari/database/{databaseName}/jdbcUrljava.lang.StringDatabase JDBC URL. All writes will go the database configured by jdbcUrl.
dari/database/{databaseName}/readJdbcUrljava.lang.StringOptional. To have reads to go to a replica, configure readJdbcUrl.
dari/database/{databaseName}/jdbcUserjava.lang.StringDatabase username. All writes will go the database configured by jdbcUser.
dari/database/{databaseName}/readJdbcUserjava.lang.StringOptional. To have reads go to a replica, configure readJdbcUser.
dari/database/{databaseName}/jdbcPasswordjava.lang.StringDatabase password. All writes will go the database configured by jdbcPassword.
dari/database/{databaseName}/readJdbcPasswordjava.lang.StringOptional. To have reads go to a replica, configure readJdbcPassword.
To use Tomcat connection pooling, define a JNDI Resource in context.xml with the name dari/database/{databaseName}/dataSource.

AggregateDatabase is an implementation of com.psddev.dari.db.Database that allows objects to be written to and read from multiple database back ends. Typically this is used to read and write to both MySQL and Solr. This allows normal reads to go to MySQL and full-text search to use Solr.

dari/database/{databaseName}/defaultDelegatejava.lang.StringName of primary database. It will be written to first and should be considered the source of record for all objects. This is usually one of the SQL back ends.

The following snippet mimics an aggregate-database configuration in a Tomcat context.xml file. In this example, AggregateDatabase is configured to read from a MySQL replica and write to a MySQL source. Solr is configured to read and write to the same host.

# Aggregate Database Configuration
dari/defaultDatabase = production
dari/database/production/defaultDelegate = sql
dari/database/production/class = com.psddev.dari.db.AggregateDatabase
dari/database/production/delegate/sql/class = com.psddev.dari.db.SqlDatabase

#Source Configuration
dari/database/production/delegate/sql/jdbcUser = username
dari/database/production/delegate/sql/jdbcPassword = password
dari/database/production/delegate/sql/jdbcUrl = jdbc:msyql://

# Replica Configuration
dari/database/production/delegate/sql/readJdbcUser = username
dari/database/production/delegate/sql/readJdbcPassword = password
dari/database/production/delegate/sql/readJdbcUrl = jdbc:msyql://

# Solr Configuration
dari/database/production/delegate/solr/class = com.psddev.dari.db.SolrDatabase
dari/database/production/delegate/solr/serverUrl =

The following table lists the configuration values for SolrDatabase.

dari/database/{databaseName}/classjava.lang.StringSet to com.psddev.dari.db.SolrDatabase for Solr databases.
dari/database/{databaseName}/serverUrljava.lang.StringURL to the source Solr server.
dari/database/{databaseName}/readServerUrljava.lang.StringOptional. URL to replica Solr server.
dari/database/{databaseName}/commitWithinjava.lang.IntegerMaximum amount of time in seconds to wait before committing to Solr.
dari/database/{databaseName}/saveDatajava.lang.BooleanDetermines if Dari record data (JSON blob) is saved to Solr. Disabling this will reduce the size of the Solr index at the cost of extra reads from the MySQL database. Only enable this if you have another database configured as the primary.
dari/subQueryResolveLimitjava.lang.IntegerBecause Solr does not currently support joins, Dari will execute subqueries separately. This limits the size of the results to prevent generating too large of a query.

You can migrate database objects from one Brightspot environment to another with Dari’s Database Bootstrap tool. The tool must be configured with a source, export database and a destination, import database.

Previous Topic
Configuration identifiers, key prefixes, and defaults
Next Topic
Debug tools
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Apple News