Logo / Docs

Install a Database

Install a Database

If you already have a PostgreSQL database installed that you will be using with FusionAuth, you can skip this section completely. If you are using MySQL and already have MySQL installed, you will still need to install the MySQL Connector to ensure FusionAuth works properly.

In order to use FusionAuth, you need to install a database. The database requirements are provided in the System Requirements. Follow the instructions below to install a supported database.

Install MySQL

IBM Compose for MySQL or other MysQL platforms that utilize MySQL Group Replication are not supported.

Linux

To install MySQL on a Linux system, you can use the apt or yum tools depending on whether or not your Linux distribution is based on Red Hat or Debian. The package name may vary depending on your platform, for example: mysql-server or mysql-server-5.7. Here’s the commands for each:

Red Hat

yum install mysql-server

Debian

sudo apt-get install mysql-server

Windows or macOS

If you are installing MySQL on a platform that does not supports RPM or DEB packages, you will need to download the installer from the MySQL website here: http://dev.mysql.com/downloads/mysql/

MySQL and Unicode

To properly store 4 byte unicode, the character set must be set to utf8mb4.

By default this configuration is enforced during startup. If FusionAuth fails to startup due to this validation the log will contain detailed messages about the MySQL configuration.

It is recommended to ensure you have properly configured MySQL to use utf8mb4 before attempting to startup FusionAuth. Please verify you have the following configuration in your my.cnf file. On Windows the file is called my.ini.

If you need to modify your configuration, restart MySQL for the changes to take effect.

my.cnf

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_bin

This is a system wide configuration option, so be certain that other databases and applications on the same MySQL server won’t be impacted by this change. It is possible not all of these configuration options will be available depending on your database configuration. Once you have configured the available options, if startup still fails due to this validation you may disable this feature. See database.mysql.enforce-utf8mb4 in the Configuration reference.

Install MySQL Connector

In order to use MySQL with FusionAuth, you also need to download and install the MySQL Connector for Java. This is a manual process due to the way that Oracle licenses MySQL. Follow these steps to get the MySQL Connector into the correct location for FusionAuth to use.

  1. Download the MySQL Connector version 8.0.23 or newer using the Platform Independent installer from the Oracle website here: https://dev.mysql.com/downloads/connector/j/8.0.html
  2. Unzip or untar the archive you downloaded
  3. Copy the file from the archive named mysql-connector-java-<version>.jar to the FusionAuth app library directory. This directory is located in the installation directory at fusionauth-app/lib. For example, if you installed using the DEB package on a Debian Linux system, this location will be /usr/local/fusionauth/fusionauth-app/lib

Install PostgreSQL

Linux

To install PostgreSQL on a Linux system, you can use the apt or yum tools depending on whether or not your Linux distribution is based on Red Hat or Debian. The package name may vary depending on your platform.

Red Hat

sudo yum install postgresql-server postgresql
sudo yum install postgresql9-contrib.x86_64

Debian

sudo apt-get install postgresql-server
sudo apt-get install postgresql-contrib

Windows or macOS

If you are installing PostgreSQL on a platform that does not support RPM or DEB packages, you will need to download the installer from the PostgreSQL website here: https://www.postgresql.org