Database Preparation

Forgejo uses a database to store relational data, however not every relational database can be used by Forgejo. Only the following databases are supported:

• MariaDB (>=10.6), using the InnoDB storage engine
• MySQL (>=8.4), using the InnoDB storage engine
• PostgreSQL (>=14)
• SQLite

For a recommendation on which database to use and fits your needs, read the recommendation page.

The remainder of this page will be a guide how to prepare each database type. Also take a look at the database section of the config cheat sheet for a detailed list of options in Forgejo.

SQLite

The binary distributed by the Forgejo project includes SQLite support, meaning you don’t have to install additional dependencies on your system.

Choosing SQLite only requires setting the database type and optionally the path to a database file:

[database]
DB_TYPE = sqlite3
# optional if you want to specify another location
# by default, the database file will be stored relative to other data
PATH = data/forgejo.db

No maintenance is expected by using SQLite; it might be needed to run the VACUUM command if the database size grows too big. This reclaims space that was freed after content was deleted.

MySQL/MariaDB

Install MariaDB or install MySQL on the machine where you want to host the database, this can be on the same machine. It is also perfectly fine to use an existing database installation.

We need to perform several administrative actions on the database. In order to accomplish that you need to get into the database instance as root. If you just installed the database, then that would be done as followed:

mysql -u root -p

Enter the password as prompted.

We will create a new database user that Forgejo will use to connect to the instance. Please, generate a secure password; for this example we use passw0rd as password and forgejo as username.

In the case the instance is on the same machine (if relevant, in the same container):

CREATE USER 'forgejo'@'localhost' IDENTIFIED BY 'passw0rd';

In all other cases you have to figure out from which IP address the Forgejo instance will be communicating from to the database instance. In this example we assume that to be 192.0.2.10.

CREATE USER 'forgejo'@'192.0.2.10' IDENTIFIED BY 'passw0rd';

Now we will create the database that Forgejo will use. Forgejo expects a case-sensitive collation, so we must account for this. utf8mb4_bin is a common collation for MariaDB and MySQL. When Forgejo starts, it will try to find a better collation (utf8mb4_0900_as_cs or uca1400_as_cs) and alter the database if it is possible. If you would like to use another collation, you can set [database].CHARSET_COLLATION in the app.ini file.

In this example we utf8mb4_bin as collation and forgejo as the name to create the database:

CREATE DATABASE forgejo CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';

Last step is to grant privileges to the forgejo user for the forgejo database.

In the case the instance is on the same machine (if relevant, in the same container):

GRANT ALTER, CREATE, DELETE, DROP, INDEX, INSERT, REFERENCES, SELECT, UPDATE ON forgejo.* TO 'forgejo'@'localhost';
FLUSH PRIVILEGES;

In all other cases you have to figure out from which IP address the Forgejo instance will be communicating from to the database instance. In this example we assume that to be 192.0.2.10.

GRANT ALTER, CREATE, DELETE, DROP, INDEX, INSERT, REFERENCES, SELECT, UPDATE ON forgejo.* TO 'forgejo'@'192.0.2.10';
FLUSH PRIVILEGES;

You can now quit the CLI, by executing the exit command.

PostgreSQL

1. Install the PostgreSQL server component on the system you would like to store the database on.

2. Protect the root user with a secure password or disable the login.

3. On the database server, login to the database console as superuser: