How to Set Up Gitea with Different Database Backends: MySQL, PostgreSQL, MSSQL, and SQLite3

You can configure Gitea to use MySQL/MariaDB, PostgreSQL, Microsoft SQL Server, or SQLite3 by setting the DB_TYPE and connection parameters in the [database] section of app.ini, or via Docker environment variables that populate the configuration template.

Gitea is a self-hosted Git service that persists all repository metadata, user accounts, and issues in a relational database. According to the go-gitea/gitea source code, the backend is determined by the setting.LoadDBSetting() function in modules/setting/database.go, which parses the DB_TYPE configuration value and maps it to internal driver-specific connection strings.

How Gitea Loads Database Settings

When Gitea starts, the setting.LoadDBSetting() function reads the [database] section from the configuration root. The code extracts the DB_TYPE key and converts it to an internal enum:

// modules/setting/database.go (lines 61-63)
sec := rootCfg.Section("database")
Database.Type = DatabaseType(sec.Key("DB_TYPE").String())

The supported values are defined in the SupportedDatabaseTypes slice and DatabaseTypeNames map:

// modules/setting/database.go (lines 18-20)
SupportedDatabaseTypes = []string{"mysql", "postgres", "mssql"}
DatabaseTypeNames = map[string]string{
    "mysql":    "MySQL",
    "postgres": "PostgreSQL",
    "mssql":    "MSSQL",
    "sqlite3":  "SQLite3",
}

SQLite3 support requires the sqlite3 build tag (controlled by the EnableSQLite3 flag) to be enabled during compilation. The official Docker image includes this support by default.

Database Connection String Formats

After parsing the type, the DBConnStr() function in modules/setting/database.go (lines 94-134) constructs a driver-specific DSN based on the backend:

• MySQL: user:passwd@tcp(host)/name?parseTime=true&tls=…
• PostgreSQL: postgres://user:passwd@host:port/name?sslmode=…
• MSSQL: server=host; port=port; database=name; user id=user; password=passwd;
• SQLite3: file:path/to/gitea.db?cache=shared&mode=rwc…

The function automatically handles host parsing—for MySQL, it uses tcp unless the host string starts with a slash indicating a Unix socket.

Configuring MySQL or MariaDB

To use MySQL or MariaDB, set DB_TYPE = mysql and provide the host, credentials, and TLS settings:

[database]
DB_TYPE  = mysql
HOST     = 127.0.0.1:3306
NAME     = gitea
USER     = gitea
PASSWD   = secret
SSL_MODE = disable

Set SSL_MODE to true to enable TLS encryption for the connection.

Configuring PostgreSQL

For PostgreSQL backends, use DB_TYPE = postgres and specify the SSL mode:

[database]
DB_TYPE  = postgres
HOST     = 127.0.0.1:5432
NAME     = gitea
USER     = gitea
PASSWD   = secret
SSL_MODE = disable

Valid SSL_MODE values include disable, require, and verify-full, depending on your server’s TLS configuration.

Configuring Microsoft SQL Server

MSSQL connections use a semicolon-delimited connection string format:

[database]
DB_TYPE  = mssql
HOST     = 127.0.0.1:1433
NAME     = gitea
USER     = gitea
PASSWD   = secret

The host can also be specified as host,port syntax instead of the colon-separated format.

Configuring SQLite3

SQLite3 requires no running server and stores data in a local file. It is the default for Docker deployments:

[database]
DB_TYPE = sqlite3
PATH    = /data/gitea/gitea.db

Important: SQLite3 support is only available if Gitea was compiled with the sqlite3 build tag. Pre-built binaries from the official Docker image include this support; custom builds may not.

Docker Environment Variable Configuration

The official Gitea Docker image uses a template at docker/root/etc/templates/app.ini that expands environment variables into the configuration file. You can override the backend without editing files directly:

docker run -d \
  -e DB_TYPE=postgres \
  -e DB_HOST=127.0.0.1:5432 \
  -e DB_NAME=gitea \
  -e DB_USER=gitea \
  -e DB_PASSWORD=secret \
  -v $(pwd)/gitea:/data \
  gitea/gitea:latest

The container entrypoint processes these variables and generates the [database] section before starting the application.

Changing Database Backends After Installation

To migrate an existing Gitea instance to a different backend:

1. Stop the Gitea service (systemctl stop gitea or docker stop <container>).
2. Edit custom/conf/app.ini (or the path mounted in Docker) and replace the [database] section with the new backend configuration.
3. Ensure the target database exists and is accessible.
4. Start Gitea—migrations run automatically on startup to initialize the schema.

When using the web installer for initial setup, the form values are persisted back to app.ini by code in routers/install/install.go (lines 47-55), which sets keys including DB_TYPE, HOST, NAME, USER, and PASSWD.

Summary

• Gitea supports MySQL/MariaDB, PostgreSQL, Microsoft SQL Server, and SQLite3 backends.
• Configuration is controlled by the DB_TYPE key in the [database] section of app.ini.
• Connection strings are built automatically by DBConnStr() in modules/setting/database.go based on the selected driver.
• SQLite3 requires the sqlite3 build tag and stores data in a file specified by the PATH key.
• Docker deployments can switch backends using environment variables that populate docker/root/etc/templates/app.ini.

Frequently Asked Questions

What databases are officially supported by Gitea?

Gitea officially supports MySQL (and MariaDB), PostgreSQL, Microsoft SQL Server, and SQLite3. These are defined in the SupportedDatabaseTypes slice in modules/setting/database.go. SQLite3 requires specific build flags, while the other three are supported in standard builds.

Can I switch from SQLite3 to PostgreSQL without losing data?

Changing the DB_TYPE on an existing installation requires migrating data manually because Gitea does not automatically transfer data between different database engines. You must export your data (using Gitea’s backup tools or database dumps), create the new database, update app.ini, and import the data into the new backend.

Why is SQLite3 unavailable in my Gitea binary?

SQLite3 support is conditionally compiled using the sqlite3 build tag. If you built Gitea from source without this tag, or downloaded a binary compiled without EnableSQLite3, the sqlite3 option will not appear in SupportedDatabaseTypes. Use the official Docker image or ensure your build includes the SQLite3 tags.

How does the Gitea installer save database settings?

During the web-based installation flow, the code in routers/install/install.go (lines 47-55) writes the form values directly to the configuration file. It updates the [database] section keys including DB_TYPE, HOST, NAME, USER, PASSWD, SCHEMA, SSL_MODE, and PATH, then reloads the settings to establish the initial connection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}