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
H2 DatabaseAll versions, for demonstration and testing only.Main site / Documentation
PostgreSQLAll versions (Community and Enterprise)Main site / Documentation / Download
MySQLAll versions (Community and Enterprise)Main site / Documentation / Download
Microsoft SQL ServerEnterprise Professional and Enterprise Prime onlyMain site / Documentation
OracleEnterprise Prime onlyMain 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 table 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. 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.


Database Configuration File

Database configuration is done in the /dotserver/tomcat-X.xx/webapps/ROOT/META-INF/context.xml file via ROOT folder plugin. There are four different database definition sections in the context.xml file, but only one section may be uncommented at a time. In the url parameter, the correct server name, port number, and instance or database name must be specified to match the installed database. The parameters for username and password must also be defined.

The context.xml contains parameters you can modify to change how dotCMS connects to your database.

Note: It is strongly recommended that all changes to the context.xml file be made through a ROOT folder plugin.

allowLinking Flag

This flag determines whether symlinks (symbolic links) inside the dotCMS distribution folders are allowed to point to resources outside the dotCMS base path. If the value of this flag is true, symlinks will be allowed; if the value of this flag is not specified, the default value is false.


The allowLinking flag must not be enabled on Windows; as noted in the Apache Tomcat Configuration Reference:

This flag MUST NOT be set to true on the Windows platform (or any other Operating System which does not have a case sensitive filesystem), as it will disable case sensitivity checks, allowing JSP source code disclosure, among other security problems.

Database Connection Pool

You can configure the number of connections dotCMS will maintain in its pool. A pool of connections is kind of like a holding tank of connections. Every time dotCMS needs a connection it goes to its pool and gets one, and then returns the connection when it's no longer being used. If there are no connections available in the pool then dotCMS must wait until an existing task finished and returns a connection to the pool.

Additional Configuration Options

The context.xml file supports a number of additional options for each configured database, including options to control caching and define multiple resources. For more information, please see the Apache Tomcat Configuration Reference.

Example Configuration

Below is an example context.xml file configuration for Postgres:

  <Resource name="jdbc/dotCMSPool" auth="Container"
      type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
      username="postgres" password="xxxxxx" maxTotal="60" maxIdle="10" maxWaitMillis="60000"
      removeAbandonedOnBorrow="true" removeAbandonedOnMaintenance="true" removeAbandonedTimeout="60" logAbandoned="true" 
      timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1" testOnBorrow="true" testWhileIdle="true"/>

The maxTotal attribute specifies the total number of connections that the pool can have.

  • If you have a large dotCMS site you will want to increase this number.
  • When possible it is a good idea to keep this number close to your number of maxthreads configured on your connectors in the server.xml file.
    • This guarantees a connection for every potential connected user.

Database Specific Requirements and Known Issues

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

H2 Database

By default, dotCMS ships with an H2 database engine. After downloading the latest release, dotCMS is ready to start up without any configuration or database installation. However, the H2 database is recommended for DEMONSTRATION AND EVALUATION purposes only and should not be used in a working, development or production environment.


Important First Steps

Postgres does not support procedural languages “out-of-the-box”. To enable procedural languages, run the following command in postgres before creating your dotCMS database:

createlang plpgsql template1

For more information, please see the PostgreSQL createlang documentation.


Important First Steps

  • 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
    2. Restart the MySQL Service and dotCMS Server

Backup (mysqldump)

Since MySQL version 5, by default 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.

Known Issues

When upgrading mySQL to a new version, the following permissions issue may appear:

ERROR reindex.ReindexThread: Unable to index record
com.dotmarketing.exception.DotDataException: User does not have access to metadata required to determine stored procedure parameter types. If rights can not be granted, configure connection with "noAccessToProcedureBodies=true" to have driver generate parameters that represent INOUT strings irregardless of actual parameter types.
at com.dotmarketing.common.db.DotConnect.loadResult(
at com.dotmarketing.common.db.DotConnect.loadObjectResults(
at com.dotmarketing.common.reindex.ReindexThread.fillRemoteQ(
at com.dotmarketing.common.reindex.ReindexThread.getNextDocToIndex(
Caused by: java.sql.SQLException: User does not have access to metadata required to determine stored procedure parameter types. If rights can not be granted, configure connection with "noAccessToProcedureBodies=true" to have driver generate param 

In MySQL, the user running the DB needs special permissions to use the metadata stored procedure in the mysql.procedure table. Therefore, one of the following steps needs to be taken:

  • Make sure the MySQL db user configured in the dotCMS context.xml file is a MySQL super user.
  • In MySQL, extend the db users permissions configured in dotCMS context.xml (that is not a super user), to have access to the mysql.procedure table.
    grant select on mysql.proc to 'dotcms'@'localhost';
    flush privileges; 
  • Set the noAccessToProcedureBodies property in the dotCMS context.xml file to true.
    • Setting this property works around the inability of a limited db user to access the mysql.procedure table.

For more information on these commands, please see the MySQL Users and Privileges, GRANT command, and JDBC connectors 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


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.




  • 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';


  • 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.


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.


  • 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.



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]"


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):

EXECUTE IMMEDIATE 'ALTER SESSION SET "_replace_virtual_columns"=false';
-- END

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