How to Connect Gitea to a Database: Configuration Guide for MySQL, PostgreSQL, and SQLite

To connect Gitea to a database, configure the [database] section in app.ini with your DB_TYPE, HOST, NAME, USER, and PASSWD values; Gitea's modules/setting/database.go parses these settings at startup to initialize the XORM engine and establish the connection.

Gitea stores all persistent data—including users, repositories, issues, and pull requests—in a relational database backend. According to the go-gitea/gitea source code, the connection logic is driven by the app.ini configuration file and processed at runtime by the settings package in modules/setting/database.go.

Supported Database Types

Gitea supports four database backends through distinct drivers selected via the DB_TYPE configuration key:

• MySQL/MariaDB (mysql) — Uses github.com/go-sql-driver/mysql
• PostgreSQL (postgres) — Uses github.com/lib/pq
• Microsoft SQL Server (mssql) — Uses github.com/denisenkom/go-mssqldb
• SQLite3 (sqlite3) — Uses the built-in SQLite driver for single-file deployments

Configuration Methods

Manual Configuration via app.ini

The primary method for connecting Gitea to a database involves editing the [database] section of app.ini. A template configuration ships with the Docker image at docker/root/etc/templates/app.ini, which demonstrates the required structure.

Key parameters parsed by modules/setting/database.go include:

• DB_TYPE — The database driver (mysql, postgres, mssql, sqlite3)
• HOST — Server address with port (e.g., 127.0.0.1:3306 or localhost:5432)
• NAME — Database name
• USER — Database username
• PASSWD — Database password
• SSL_MODE — SSL configuration (required for PostgreSQL, optional for others)

Web Installation Wizard

For fresh installations, the web installer at /install handles database configuration automatically. According to routers/install/install.go (lines 340-350), the installer writes user-supplied connection details directly back to app.ini, eliminating the need for manual file editing during initial setup.

Docker and Containerized Deployments

When running Gitea in Docker, mount a custom app.ini to /data/gitea/conf/app.ini or modify the template at docker/root/etc/templates/app.ini before building. The container entrypoint processes these settings before starting the Gitea service.

Step-by-Step Connection Examples

MySQL/MariaDB Setup

Create the database and user first:

CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'gitea'@'%' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'%';
FLUSH PRIVILEGES;

Configure app.ini:

[database]
DB_TYPE  = mysql
HOST     = 127.0.0.1:3306
NAME     = gitea
USER     = gitea
PASSWD   = secure_password
SSL_MODE = false
CHARSET  = utf8mb4

PostgreSQL Configuration

[database]
DB_TYPE  = postgres
HOST     = localhost:5432
NAME     = gitea
USER     = gitea
PASSWD   = secure_password
SSL_MODE = disable

For production PostgreSQL instances, set SSL_MODE to require or verify-full instead of disable.

SQLite3 for Testing

For development or small deployments, SQLite requires no external server:

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

Ensure the data/ directory is writable by the Gitea process.

Internal Architecture and Source Code

Understanding the initialization flow helps troubleshoot connection issues. The process implemented in go-gitea/gitea follows this sequence:

1. Configuration Parsing — modules/setting/database.go reads the [database] section from app.ini and populates the global Database struct, converting DB_TYPE to a DatabaseType enum.

2. Driver Selection — Based on Database.Type, Gitea imports the appropriate database driver package and constructs a connection string.

3. Engine Initialization — The application creates a global xorm.Engine instance using xorm.NewEngine, which manages all subsequent database interactions for models defined in models/user.go and related files.

4. Schema Migration — On first startup, Gitea runs automatic migrations to create tables and indexes. Check logs for the "Database connection successful" message to verify proper initialization.

Summary

• Configure the [database] section in app.ini with DB_TYPE, HOST, NAME, USER, and PASSWD to define your connection parameters.
• Choose from MySQL/MariaDB, PostgreSQL, MSSQL, or SQLite3 backends; each requires specific SSL_MODE settings.
• Leverage the web installer at /install (handled by routers/install/install.go) to automate configuration file generation for new instances.
• Verify connectivity by checking application logs for successful XORM engine initialization and completed schema migrations.

Frequently Asked Questions

What database types does Gitea support?

Gitea supports MySQL (and MariaDB), PostgreSQL, Microsoft SQL Server (MSSQL), and SQLite3. The DB_TYPE setting in app.ini accepts values mysql, postgres, mssql, or sqlite3, with each value triggering a specific driver import in modules/setting/database.go.

Can I change the database type after installation?

Migrating between database types (e.g., from SQLite to MySQL) requires dumping data from the existing database and importing it into the new backend; Gitea does not provide an automatic conversion tool. You must update DB_TYPE and all connection parameters in app.ini, then restart the service.

Where is the database configuration stored in Gitea?

All database connection parameters reside in the [database] section of app.ini. The modules/setting/database.go file defines the struct that holds these values at runtime, parsing the configuration when Gitea starts.

How do I configure Gitea to use SQLite instead of MySQL?

Set DB_TYPE = sqlite3 and specify PATH = data/gitea.db in the [database] section of app.ini. Unlike MySQL or PostgreSQL, SQLite requires no HOST, USER, or PASSWD values, as it operates on a local file. Ensure the Gitea process has write permissions to the directory containing the database file.

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