---
title: "Configuring MySQL 5.7"
source: https://dev.pageseeder.com/guide/installation/configuring_mysql_5.7.html
description: "This guide provides comprehensive instructions for configuring MySQL 5.7 for PageSeeder, including installation steps, data storage configuration, JDBC driver setup, UTF-8mb4 character set configuration, and database backup/restore procedures."
last_updated: 2026-08-11T16:07:17+10:00
tokens: ~1749
---

# Configuring MySQL

## Install MySQL 5.7

PageSeeder supports MySQL 5.7 or higher but if this is a new installation, it’s generally best to install the latest release of version 8.4 (see [Configuring MySQL](/guide/installation/mysql.md)).

- On Linux use commands (CentOS 6) like:

```shell
# rpm -Uvh https://dev.mysql.com/get/mysql57-community-release-el6-7.noarch.rpm
```

- Or (CentOS 7)

```shell
# rpm -Uvh https://dev.mysql.com/get/mysql57-community-release-el7-7.noarch.rpm
```

```shell
# yum install mysql-server
```

- Or (CentOS 8) disable the MySQL 8 repository and enable MySQL 5.7 using steps similar to [these](https://computingforgeeks.com/install-mysql-5-7-on-centos-rhel-linux/).

### Changing where data is stored

On Linux, MySQL usually stores data under `/var/lib/mysql`, but if you want to use mounted storage for PageSeeder (for example storage mapped to the `/opt` folder), you can configure MySQL to store data there as well. To do this, follow these steps:

Stop MySQL by entering:

```shell
# service mysqld stop
```

Move the existing MySQL data to the new location:

```shell
# mv /var/lib/mysql /opt/mysql
```

Edit the `/etc/my.cnf` file as follows:

```ini
[mysqld]
...
datadir=/opt/mysql
socket=/opt/mysql/mysql.sock
...
[client]
socket=/opt/mysql/mysql.sock
```

Start MySQL by entering:

```shell
# service mysqld start
```

> **Note:** If MySQL doesn’t start after changing the data location, SELinux might need to be configured to allow access to the new location by entering the following (see [Troubleshooting](/guide/installation/configuring_a_proxy.md) for more info): ```shell # semanage fcontext -a -t mysqld_db_t '/opt/mysql(/.*)?' # restorecon -Rv /opt/mysql ```

### Upgrading 5.6 to 5.7

Upgrading from MySQL 5.6 to 5.7 requires adding (or modify) the following line in `my.ini` or `my.cnf`:

```properties
sql-mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
```

Also ensure that `mysql-connector-java-8.0.23.jar` or newer (`mysql-connector-java-5.1.39.jar` or newer for PageSeeder v5) is in `pageseeder/webapp/WEB-INF/lib` and `drivers` folders.

**Only** if using `mysql-connector-java-5.x.x.jar` edit the following file:

```text
pageseeder/webapp/WEB-INF/config/database.properties
```

To the end of the `DBURL` add:

```text
?useSSL=false
```

For example:

```properties
DBURL=jdbc:mysql://localhost/pageseeder?useSSL=false
```

**Restart MySQL and then PageSeeder after making these changes.**

## Install the JDBC driver

The PageSeeder app requires a JDBC driver to communicate with MySQL. Download the latest version of MySQL Connector/J (JDBC Driver) for your MySQL and extract it on your server.

> **Warning:** On PageSeeder v6 or higher do not use Connector/J v5 due to a security issue, instead use Connector/J v8.0.23 or higher. On PageSeeder v5 Connector/J v5 must be used.

- On Windows, it can be downloaded from [https://www.mysql.com](http://www.mysql.com/) . Subject to Oracle/MySQL website changes, Connector/J is under ‘MySQL Community Downloads’ and older versions are listed under ‘Archive’.
- On Linux, use the following commands *(URL and version might have changed)*:

```shell
$ wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.49.tar.gz
$ tar xzvf mysql-connector-j-5.1.49.tar.gz
```

*The PageSeeder installer asks for the location of the JDBC driver JAR file to be identified.*

## Use UTF-8mb4 character set

To correctly process special characters—MySQL must be configured for UTF-8mb4. To do this, edit the following:

- On Windows *(to see the ProgramData folder might require showing “hidden” items):*

```text
\ProgramData\MySQL\MySQL Server 5.7\my.ini
```

- On Linux:

```text
/etc/my.cnf
```

> **Warning:** When saving edits, do NOT change the file encoding from `ascii`. Doing so might prevent MySQL from starting.

After `[mysqld]` (add it if it doesn’t exist), add or modify the following line:

```properties
character-set-server=utf8mb4
```

Change any other **character-set** properties to **utf8mb4.**

Add (or modify) the following line as shown:

```properties
sql-mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
```

**If spare RAM is available** increase the InnoDB buffer to 75% of total RAM, minus what is used by other processes (PageSeeder/java can use 20% more than its configured `-Xmx` heap size). For example, with 6GB total RAM and PageSeeder 2GB heap, the InnoDB buffer could be set to 2GB ( 6 x .75 - 2.4)  by adding:

```properties
innodb-buffer-pool-size=2048M
```

or:

```properties
innodb-buffer-pool-size=2G
```

On Windows restart MySQL using the **Services Control Panel,** on Linux type:

```shell
# service mysqld restart
```

Or

```shell
# service mysql restart
```

> **Warning:** On Amazon RDS, the only value that MUST be set using DB parameter groups is: ```properties character-set-server=utf8mb4 ```

> **Note:** To increase the number of Database connections, see [Database Properties](/guide/configuration/properties/database_properties.md).

## Backup and restore

> **Warning:** When manually creating a PageSeeder database, DO NOT use `uft8mb4`, DO use `utf8` as shown in the following command. However, to backup use `--default-character-set=utf8mb4` and `-r` flag.

To backup the PageSeeder database on Linux use a command like this:

```shell
$ mysqldump --single-transaction -u root -p --default-character-set=utf8mb4 -r ps.sql pageseeder
```

Optionally compress the backup:

```shell
$ gzip ps.sql
```

### Restore with overwrite

To overwrite an existing database, first drop it, then recreate it using commands like this:

```shell

$ mysql -u root -p
drop database pageseeder;
create database pageseeder character set utf8;
grant all on pageseeder.* to pageseeder@localhost;
quit
```

To restore the PageSeeder database, use a command like this:

```shell

$ mysql -u pageseeder -p pageseeder < ps.sql
```

or if the backup is compressed:

```shell

$ gunzip -c ps.sql.gz | mysql -u pageseeder -p pageseeder
```

### Restore with create

If no database or user exists, create them using commands like this:

```shell

$ mysql -u root -p
create database pageseeder character set utf8;
create user pageseeder@localhost identified by '<password>';
grant all on pageseeder.* to pageseeder@localhost;
quit
```

To restore the PageSeeder database use a command like this:

```shell

$ mysql -u pageseeder -p pageseeder < ps.sql
```

or if the backup is compressed:

```shell

$ gunzip -c ps.sql.gz | mysql -u pageseeder -p pageseeder
```

> **Note:** If PageSeeder is running on a different server to MySQL, replace `@localhost` with `@"%"`

> **Note:** On Linux, if you get an error `ERROR 2006 (HY000) at line 207: MySQL server has gone away` while restoring, add `max_allowed_packet=32M` under `[mysqld]`in the `/etc/my.cnf` file and restart MySQL before trying again.