Database Configuration documentation for the dotCMS Content Management System

While dotCMS does cache aggressively and will attempt to limit database traffic on the front end of your site, the database is an important part of your overall dotCMS system and your database performance is vital to dotCMS, especially in the authoring environment.

Supported Databases

The following table lists all of the databases supported by dotCMS, the versions of dotCMS each database is supported in, and official links for each database.

DatabasedotCMS VersionsOfficial Links
PostgreSQLAll versions (Community and Enterprise)Main site / Documentation / Download
MySQL (deprecated)All versions (Community and Enterprise)Main site / Documentation / Download
Microsoft SQL ServerEnterprise onlyMain site / Documentation
OracleEnterpriseMain site / Documentation

To see the section of this document specific to each database, click the link for that database in the first column. To view an official site for a database, click the appropriate link in the last column. Please see the dotCMS features list for more information on features supported in different dotCMS versions.

Supported Versions

New dotCMS installations should always use the most recent release of the selected database - except for MySQL (deprecated), which requires MySQL 5.7.x. Support for older database versions is provided only to customers with dotCMS support contracts in place before new database versions are released.

For a complete list of the current versions of each database supported, please see the Database portion of the dotCMS Technology Requirements documentation.

Configuration

The Data source can be initialized in multiple different ways - we always recommend using environmental variables to configure your datasource. Any of the following methods can be used, and these sources will be checked in the order they are listed here:

Database Configuration File (db.properties)

Database configuration should be done using environmental variables.

The db.properties file contains parameters you can modify to change how dotCMS connects to your database.

Note: Previous versions of dotCMS allowed configuration of the database through the context.xml file in the WEB-INF folder. This file is still supported for backward compatibility, but is deprecated, and will stop being supported in a future release.

System Variables

The following system variables can be set to initialize a datasource using this option:

System EnvironmentDefault Value
connection_db_driverorg.postgresql.Driver
connection_db_base_urljdbc:postgresql://localhost/dotcms
connection_db_username 
connection_db_password 
connection_db_max_total60
connection_db_max_idle10
connection_db_max_wait60000
connection_db_validation_querySELECT 1
connection_db_leak_detection_threshold60000
connection_db_default_transaction_isolation 
DOT_POSTGRES_PUBSUB_JDBC_URLif primary datasource is postgres, dotCMS attempts to use the same datasource for the PUB/SUB connection. Setting this env variable allows you to override this default behavior.

PostgreSQL

dotCMS uses Postgres by default and for our internal cloud infrastructure as well. There are some caveats:

  • dotCMS does not support AWS Aurora Postgres Serverless
  • dotCMS does not test against AWS Aurora Postgres or other cloud provider's managed Postgres services
  • dotCMS recommends using AWS Postgres RDS.

Database Specific Requirements and Known Issues

The following sections cover the specific requirements and known issues for each specific database supported by dotCMS.

MySQL

MySQL Support has been deprecated in dotCMS and will be removed in a future version.

Important First Steps

  • dotCMS only supports MySQL 5.3.x
  • When creating the dotCMS table, make sure to create it with the UTF-8 char set and the DEFAULT UTF-8 collation. e.g.
    create database dotcms_zip default character set = utf8 default collate = utf8_general_ci;
    
  • If MySQL is running with log-bin enabled set:
    1. Place the following in your my.cnf file (for Unix/Mac) or my.ini file (for Windows):
      log-bin = /path/to/log-bin/file
      binlog-format=row
      lower_case_table_names=1
      
    2. Restart the MySQL Service and dotCMS Server

Backup (mysqldump)

mysqldump will back up all the triggers but NOT the stored procedures/functions. There are 2 mysqldump parameters that control this:

  • routines (FALSE by default, backs up the stored procedures)
  • triggers (TRUE by default, backs up the triggers)

To ensure that dotCMS stored procedures are included in the dump/backup, you must pass the -routines argument to the mysqldump command:

mysqldump  --routines > outputfile.sql

For more information, please see the mysqldump documentation.

MS SQL Server

Note: Use of the MS SQL Server database is only supported in dotCMS Enterprise Professional and Enterprise Prime editions. Please see the list of dotCMS versions for more information on features supported in different version of dotCMS.

Important First Steps

Authentication

Important: You must use SQL user authentication and not Windows User (integrated) authentication. There are no longer any supported open source tools to provide authentication of SQL Server databases using integrated Windows authentication.

The database user which is used to create the dotCMS database should have the db_owner role on the dotcms database

Transaction Locking

Microsoft SQL Server databases can experience issues with transaction locking. Make sure to run the following command on your db BEFORE running dotCMS or establishing any connections to the dotCMS database.

ALTER DATABASE dotcms SET READ_COMMITTED_SNAPSHOT ON;
GO

ALTER DATABASE dotcms SET ALLOW_SNAPSHOT_ISOLATION ON;
GO

Note:

  • Make sure to replace “dotcms” in the above commands with the name of your own SQL server database.

For more information on these commands, please see the MS SQL ALTER DATABASE documentation.

Checking Existing SQL Server Settings

If you wish to find out what your current settings are, run the following query:

SELECT sd.is_read_committed_snapshot_on,sd.snapshot_isolation_state_desc
FROM sys.databases AS sd
WHERE sd.[name] = 'dotcms';

Notes:

  • If you need more information on SQLServer regarding row locking and isolation levels see the Microsoft SQL Server 2005 Row Versioning-Based Transaction Isolation document.
  • If you need to execute SQL queries which might lock a table or row while others are connected to the database, make sure you run SET TRANSACTION ISOLATION LEVEL SNAPSHOT first.
    • If you are writing a dotCMS plugin and you get your connection from the DBConnection factory this will already be done for you.

Oracle

Note: Use of the Oracle database is only supported in dotCMS Enterprise Prime edition. Please see the dotCMS features table for more information on features supported in dotCMS versions.

Important First Steps

Character Set

The character set for your dotCMS Oracle database must be AL32UTF8. Please reference the following statement from the Oracle web site:

Oracle recommends AL32UTF8 as the database character set. AL32UTF8 is Oracle's name for the UTF-8 encoding of the Unicode standard. The Unicode standard is the universal character set that supports most of the currently spoken languages of the world. The use of the Unicode standard is indispensable for any multilingual technology, including database processing.
Database Permissions

The following Oracle commands grant the permissions that are needed to start dotCMS in Oracle.

Note:

  • These are the permissions dotCMS uses to test with Oracle.
  • These might be more permissive than necessary, but you can be sure that Oracle will start if your user has these permissions.
CREATE USER "DOTCMS_SENDER" PROFILE "DEFAULT" IDENTIFIED BY "XXXXXXXX" ACCOUNT UNLOCK;

GRANT "CONNECT" TO "DOTCMS_SENDER";
GRANT "EXP_FULL_DATABASE" TO "DOTCMS_SENDER";
GRANT "GATHER_SYSTEM_STATISTICS" TO "DOTCMS_SENDER";
GRANT "IMP_FULL_DATABASE" TO "DOTCMS_SENDER";
GRANT "OEM_ADVISOR" TO "DOTCMS_SENDER";
GRANT "OEM_MONITOR" TO "DOTCMS_SENDER";
GRANT "RESOURCE" TO "DOTCMS_SENDER";

ALTER USER "DOTCMS_SENDER" DEFAULT ROLE ALL;
EXIT

Known Issues

Oracle 11G R2.0 and most Oracle Express versions have a known issue that may cause errors similar to the following when trying to pull templates:

ORA-00600: internal error code, arguments: [rwoirw: check ret val], [], [], [], [], [], [], [], [], [], [], [] 
00600. 00000 -  "internal error code, arguments: [%s], [%s], [%s], [%s], [%s], [%s], [%s], [%s]"

Solution

If you see these types of errors, you may workaround this issue by adding a database trigger to the Role and Policy Modeler Oracle database to set the Oracle parameter _replace_virtual_columns=false.

To do this, run the following from a SQL*Plus session connected to the Role and Policy Modeler Oracle database with administrative privilege (that is, as SYSTEM or SYS):

-- BEGIN
CREATE OR REPLACE TRIGGER WORKAROUNDORA9965278 AFTER
LOGON ON DATABASE BEGIN
EXECUTE IMMEDIATE 'ALTER SESSION SET "_replace_virtual_columns"=false';
END;
/
-- END

For more information on Oracle database configuration, please see the Oracle documentation.