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

> Learn to set up Gitea with MySQL, PostgreSQL, MSSQL, or SQLite3. Configure your Gitea database easily for seamless version control hosting by adjusting app.ini or Docker variables.

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

---

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

```go
// 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:

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

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

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

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

```ini
[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`](https://github.com/go-gitea/gitea/blob/main/docker/root/etc/templates/app.ini) that expands environment variables into the configuration file. You can override the backend without editing files directly:

```bash
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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini) by code in [`routers/install/install.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/app.ini).
- Connection strings are built automatically by `DBConnStr()` in [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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`](https://github.com/go-gitea/gitea/blob/main/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.