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

> Connect Gitea to MySQL, PostgreSQL, or SQLite by configuring your app.ini file. Learn how to set up your database connection for a smooth Gitea instance.

- Repository: [Gitea/gitea](https://github.com/go-gitea/gitea)
- Tags: how-to-guide
- Published: 2026-03-07

---

**To connect Gitea to a database, configure the `[database]` section in [`app.ini`](https://github.com/go-gitea/gitea/blob/main/app.ini) with your `DB_TYPE`, `HOST`, `NAME`, `USER`, and `PASSWD` values; Gitea's [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini) configuration file and processed at runtime by the settings package in [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini). A template configuration ships with the Docker image at [`docker/root/etc/templates/app.ini`](https://github.com/go-gitea/gitea/blob/main/docker/root/etc/templates/app.ini), which demonstrates the required structure.

Key parameters parsed by [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/routers/install/install.go) (lines 340-350), the installer writes user-supplied connection details directly back to [`app.ini`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini) to [`/data/gitea/conf/app.ini`](https://github.com/go-gitea/gitea/blob/main//data/gitea/conf/app.ini) or modify the template at [`docker/root/etc/templates/app.ini`](https://github.com/go-gitea/gitea/blob/main/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:

```sql
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`](https://github.com/go-gitea/gitea/blob/main/app.ini):

```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

```ini
[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:

```ini
[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`](https://github.com/go-gitea/gitea/blob/main/modules/setting/database.go) reads the `[database]` section from [`app.ini`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini) accepts values `mysql`, `postgres`, `mssql`, or `sqlite3`, with each value triggering a specific driver import in [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini). The [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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.