get started/download and install/reference

Install a Database

FusionAuth requires a database that meets the System Requirements. This page explains how to install a supported database.

Install PostgreSQL#

To install PostgreSQL, follow the installation instructions for your platform at postgresql.org. We recommend PostgreSQL 15 or newer.

Install MySQL#

To install MySQL, follow the installation instructions for your platform at dev.mysql.com.

FusionAuth requires the ability to store 4-byte unicode. To store 4-byte unicode, you must configure your MySQL server to use the utf8mb4 character set. If you don’t configure this character set, FusionAuth will fail to start and log an error.

To configure your MySQL instance to use utf8mb4, add the following lines to my.cnf (my.ini on Windows):

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

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

After modifying the configuration file, restart MySQL to load your changes.

This configuration changes the character set for the entire MySQL server. If you share your MySQL server across multiple databases and applications, check to ensure that this change doesn’t impact functionality.

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#

To use MySQL with FusionAuth, you also need the MySQL Connector for Java. This is a manual process due to the way that Oracle licenses MySQL. To get the MySQL Connector into the correct location for FusionAuth:

Download the MySQL Connector version 8.0.23 or newer using the Platform Independent installer from Oracle.
Unzip or untar the archive.
The archive should contain a file named mysql-connector-java-<version>.jar. Copy this file to the FusionAuth app library directory, located in the installation directory at fusionauth-app/lib. For example, a DEB package install on a Debian Linux system would locate the installation directory at /usr/local/fusionauth/fusionauth-app/lib.

Results