1.3Preparing and connecting to MariaDB / MySQL

Although cmsWorks comes with a fully configured and ready-to-use built-in in-memory database, one of the first things you probably want to do is to change this built in database to a "standalone" database. The in-memory database is useful for first steps and testing cases, but when storing bigger amounts of content it is recommended that a MariaDB / MySQL database is used, the configuration of these two should be pretty similar.

Preparing MariaDB / MySQL

cmsWorks takes heavy use of the UTF8 encoding to ensure the correct output in international languages. MySQL should therefore be prepared for this encoding - feel free to use other encodings like utf8mb4.

Depending on your database configuration, you should insert the following lines into your my.cnf / my.ini file on the database server into the [mysqld] section (or similar configurations for MariaDB depending on it's version):

skip-character-set-client-handshake=1
collation-server=utf8_general_ci
character-set-server=utf8

Additionally, MySQL has to be prepared for larger packet sizes to store bigger BLOB entries. Add the following line into the [mysqld] section, too (or similar configuration for MariaDB depending on it's version):

max_allowed_packet=32M

In case you want to store larger BLOB entries into the database, feel free to set a higher value. After the changes were done, the MySQL-server has to be restarted.

Creating a database (MySQL example)

Connect to your database (i.e. via mysql -u root if the database server is on the same machine you are working on) and execute the following lines to create the database and database user:

CREATE DATABASE cmsworksdb DEFAULT CHARACTER SET = UTF8;
CREATE USER 'cmsworks'@'%' IDENTIFIED BY 'cmspass';
GRANT ALL ON cmsworksdb.* TO 'cmsworks'@'%';
FLUSH PRIVILEGES;

In case you use MariaDB adapt that to your needs. It is essential that you use your own database name, user an password, adjust them in the database.properties file accordingly.

Creating standard tables and the needed data to a newly created database

In case you have a standard MySQL dump for an empty cmsWorks database for your DB-flavour you are able to import a database using i.e. the mysql command line program provided by MySQL:

mysql -u root --default-character-set=utf8 cmsworksdb < cmsworksdb.dmp

If you do not have such a database dump please refer to the packaged bin-tools (database tools of cmsWorks) to create the tables and fill them with standard values.

Connecting cmsWorks to the database

cmsWorks internally uses a database service that stores the user, password, servername etc. of the database and provides the system with database connections to that database.

A description of how to set the database parameters and configure the database connection pool of cmsWorks will be found in chapter The database connection service.

cmsWorks database tools

The following commands uses the existing database, creates the tables therein and prefills rows with the standard values.

dbinitcms.sh <connection protocol> <server/ip> <port> <database name> <user> <password>

To initially fill root folder, admin user, groups and more use

dbexecscript.sh <script path> <connection protocol> <server/ip> <port> <database name> <user> <password>

Attention! In case you use MariaDB or MySQL, make sure that the encoding is completely set to UTF-8. You may force this by adding "?useUnicode=true&characterEncoding=utf-8" to the database name in the configuration or while using the database tools.