All of Fedora's persistent content and metadata are stored on disk in an OCFL storage root. For performance reasons, Fedora maintains a cache of system and user metadata in a rebuildable database.

For quickly spinning up Fedora in a testing / experimental context, a default H2 database is available by default.


You can connect to the H2 database by:

  1. Downloading a copy of h2 (needs to match the version used by the version of fedora that you're using, which is 2.1.210 for the latest release): https://mvnrepository.com/artifact/com.h2database/h2/2.1.210

  2. Launch the h2 web console (this should open a webpage in your browser):

    java -jar h2-2.1.210.jar


  3. Open the db by specifying the jdbc url, for example jdbc:h2:/home/jdoe/Downloads/fcrepo/fcrepo-home/data/fcrepo-h2 .
    When you start fedora, there should be a log line like 

    INFO 15:48:22.039 [main] (DatabaseConfig) JDBC URL: jdbc:h2:/Users/psmith/www/fcrepo/ocfl_temp/data/fcrepo-h2;FILE_LOCK=SOCKET

    Copy the value from there.

  4. Remove the default user name
  5. Click "connect"

Note, you can't have fedora running when you connect to the db.


However, for production installations, it is recommended to use a MariaDB,  MySQL or PostgreSQL database.

Fedora currently supports the following versions:

  • PostgresQL 12.3
  • MariaDB 10.5.3
  • MySQL 8.0

Below are the steps to use MySQL, MariaDB or PostgreSQL, as well as Docker instructions if you choose to run your database in a Docker container.

For the full list of database properties, please refer to the Database section of the Properties documentation.

You can find additional information on this wiki about how Fedora rebuilds these caches and the structure of the tables in the database.


Native Database Setup

MariaDB

  1. Install an instance of MariaDB and create a database called fcrepo and a user account that can access it
  2. Run Fedora with the following properties defined either in your properties file or in your JAVA_OPTS:
fcrepo.db.url=jdbc:mariadb://localhost:3306/fcrepo
fcrepo.db.user=<username>
fcrepo.db.password=<password>

Note, the fcrepo database must be manually created, but the tables will be automatically created.

PostgreSQL

  1. Install an instance of PostgreSQL and create a database called fcrepo and a user account that can access it
  2. Run Fedora with the following properties defined either in your properties file or in your JAVA_OPTS:
fcrepo.db.url=jdbc:postgresql://localhost:5432/fcrepo
fcrepo.db.user=<username>
fcrepo.db.password=<password>

Note, the fcrepo database must be manually created, but the tables will be automatically created.

MySQL

  1. Install an instance of MySQL and create a database called fcrepo and a user account that can access it
  2. Run Fedora with the following properties defined either in your properties file or in your JAVA_OPTS:
fcrepo.db.url=jdbc:mysql://localhost:3306/fcrepo
fcrepo.db.user=<username>
fcrepo.db.password=<password>

Note, the fcrepo database must be manually created, but the tables will be automatically created.

Database Initialization

MySQL and MariaDB

To create a new database and user in MySQL, assuming a username of user1 and a password of xyz:

$ mysql -u root -p
> CREATE DATABASE fcrepo CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
> CREATE USER 'user1'@'localhost' IDENTIFIED BY 'xyz';
> GRANT ALL PRIVILEGES ON fcrepo.* to 'user1'@'localhost';
> \q


MySQL and MariaDB use case insensitive collations by default, but resources in Fedora are case sensitive. If you decide to create your database using a case insensitive collation, then Fedora will not be able to handle case appropriately, leading to undefined behavior.

PostgreSQL

To create a new database and user in PostgreSQL, assuming a username of user1 and a password of xyz:

$ sudo -u postgres psql
> CREATE DATABASE fcrepo;
> CREATE USER user1;
> ALTER USER user1 PASSWORD 'xyz';
> GRANT ALL PRIVILEGES ON DATABASE fcrepo TO user1;
> \q


Docker-based Database Setup

The following instructions detail how to run your database in a Docker container.

MariaDB

The following instructions use the database username of "fcrepo-user" and password of "fcrepo-pw". You will want to change these to something more secure.

docker run --name f6-mariadb -e MYSQL_ROOT_PASSWORD=root-pw -e MYSQL_DATABASE=fcrepo -e MYSQL_USER=fcrepo-user -e MYSQL_PASSWORD=fcrepo-pw -p 3306:3306 -d mariadb:10.5.3 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin

..when done with the database:
docker stop f6-mariadb
docker rm f6-mariadb

MariaDB CLI Client

To connect via the command line with the above database, the following command may be used:

docker exec -it f6-mariadb mysql -ufcrepo-user -pfcrepo-pw -Dfcrepo

In order for Fedora to connect with a database configured as above, the Fedora should be started with the following properties:

fcrepo.db.url=jdbc:mariadb://localhost:3306/fcrepo 
fcrepo.db.user=fcrepo-user 
fcrepo.db.password=fcrepo-pw

PostgreSQL

The following instructions use the database username of "fcrepo-user" and password of "fcrepo-pw". You will want to change these to something more secure.

docker run --name f6-postgres -e POSTGRES_USER=fcrepo-user -e POSTGRES_PASSWORD=fcrepo-pw -e POSTGRES_DB=fcrepo -p 5432:5432 -d postgres:12.3

..when done with the database:
docker stop f6-postgres
docker rm f6-postgres

PostgreSQL CLI Client

To connect via the command line with the above database, the following command may be used:

docker exec -it f6-postgres psql -U fcrepo-user -d fcrepo

In order for Fedora to connect with a database configured as above, the Fedora should be started with the following properties:

fcrepo.db.url=jdbc:postgresql://localhost:5432/fcrepo 
fcrepo.db.user=fcrepo-user 
fcrepo.db.password=fcrepo-pw

MySQL

The following instructions use the database username of "fcrepo-user" and password of "fcrepo-pw". You will want to change these to something more secure.

docker run --name f6-mysql -e MYSQL_ROOT_PASSWORD=root-pw -e MYSQL_DATABASE=fcrepo -e MYSQL_USER=fcrepo-user -e MYSQL_PASSWORD=fcrepo-pw -p 3306:3306 -d mysql:8.0  --character-set-server=utf8mb4 --collation-server=utf8mb4_bin

..when done with the database:
docker stop f6-mysql
docker rm f6-mysql

MySQL CLI Client

To connect via the command line with the above database, the following command may be used:

docker exec -it f6-mysql mysql -ufcrepo-user -pfcrepo-pw -Dfcrepo

In order for Fedora to connect with a database configured as above, the Fedora should be started with the following properties:

fcrepo.db.url=jdbc:mysql://localhost:3306/fcrepo 
fcrepo.db.user=fcrepo-user 
fcrepo.db.password=fcrepo-pw