# Gitea Database Performance Tuning: Configuration Options and Best Practices

> Optimize Gitea database performance with nine key app.ini tuning options. Enhance connection pooling, query buffering, and retry logic for faster throughput and reduced latency.

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

---

**Gitea provides nine distinct database tuning options controlled via [`app.ini`](https://github.com/go-gitea/gitea/blob/main/app.ini) that optimize connection pooling, query buffering, retry logic, and logging overhead to improve throughput and reduce latency.**

Gitea’s database layer relies on XORM to manage persistence across MySQL, PostgreSQL, MSSQL, and SQLite3 backends. Administrators can fine-tune performance characteristics through specific configuration keys defined in [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/modules/setting/database.go) and applied during engine initialization in [`models/db/engine_init.go`](https://github.com/go-gitea/gitea/blob/main/models/db/engine_init.go). Understanding these settings allows you to match Gitea’s resource consumption to your infrastructure capacity and workload patterns.

## Connection Pool Optimization

The most impactful Gitea database performance tuning controls govern the XORM connection pool. These settings prevent resource exhaustion and reduce connection churn overhead.

### MAX_IDLE_CONNS and MAX_OPEN_CONNS

**`MAX_IDLE_CONNS`** defines how many idle database connections Gitea maintains in the pool for reuse. The default value is `2`, which minimizes memory overhead but may cause connection creation latency under burst loads. **`MAX_OPEN_CONNS`** sets the absolute ceiling on simultaneous open connections; it defaults to `0` (unlimited), which risks overwhelming the database server during traffic spikes.

In [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/modules/setting/database.go) (lines 43‑44 and 78), these values are loaded from the `[database]` section and passed to XORM in [`models/db/engine_init.go`](https://github.com/go-gitea/gitea/blob/main/models/db/engine_init.go) at lines 70‑71:

```go
xe.SetMaxOpenConns(setting.Database.MaxOpenConns)
xe.SetMaxIdleConns(setting.Database.MaxIdleConns)

```

### CONN_MAX_LIFETIME

**`CONN_MAX_LIFETIME`** specifies the maximum duration a connection remains valid before forced recycling. This defaults to `3s` for MySQL to prevent stale connection issues, and `0` (no limit) for other databases. Adjusting this in [`app.ini`](https://github.com/go-gitea/gitea/blob/main/app.ini) helps mitigate MySQL’s tendency to drop long-lived idle connections.

## Query Execution and Buffering Controls

Fine-tuning how Gitea buffers results and logs queries prevents memory bloat and I/O bottlenecks.

### ITERATE_BUFFER_SIZE

When Gitea iterates over large result sets—such as during repository indexing or audit log exports—**`ITERATE_BUFFER_SIZE`** controls the internal buffer size. The default of `50` balances memory usage against round-trip latency. Increasing this to `200` or higher reduces database round-trips for bulk operations but increases per-query memory allocation.

### SLOW_QUERY_THRESHOLD and LOG_SQL

**`SLOW_QUERY_THRESHOLD`** (default `5s`) triggers XORM warnings for queries exceeding the duration, helping identify indexing deficiencies without the overhead of full SQL logging. **`LOG_SQL`** enables comprehensive SQL statement logging for debugging, but defaults to `false` because it adds significant disk I/O and log volume overhead in production environments.

These parameters are loaded at lines 86‑91 of [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/modules/setting/database.go) and influence the XORM engine behavior globally.

## Connection Resilience and Startup Behavior

Gitea database performance tuning also encompasses failure recovery and migration control.

### DB_RETRIES and DB_RETRY_BACKOFF

If the database is unreachable at startup or during a transaction, **`DB_RETRIES`** (default `10`) determines how many times Gitea attempts reconnection. **`DB_RETRY_BACKOFF`** (default `3s`) inserts a sleep duration between attempts, preventing thundering-herd scenarios against a recovering database server.

### AUTO_MIGRATION

**`AUTO_MIGRATION`** (default `true`) controls whether Gitea executes schema migrations automatically on startup. Disabling this setting speeds up application initialization in read-only or horizontally scaled deployments where schema changes are managed externally, though it requires manual migration coordination during upgrades.

## Configuring Database Settings in app.ini

All tuning options reside in the `[database]` section of [`custom/conf/app.ini`](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.ini). The following example demonstrates production-ready values for a high-throughput MySQL deployment:

```ini
[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306
NAME = gitea
USER = gitea
PASSWD = secure_password

; Connection pooling
MAX_IDLE_CONNS = 10
MAX_OPEN_CONNS = 100
CONN_MAX_LIFETIME = 30s

; Performance tuning
ITERATE_BUFFER_SIZE = 200
SLOW_QUERY_THRESHOLD = 2s

; Diagnostics (disable in production)
LOG_SQL = false

; Resilience
DB_RETRIES = 10
DB_RETRY_BACKOFF = 3s
AUTO_MIGRATION = true

```

Reference the full configuration schema in [`custom/conf/app.example.ini`](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini) for additional context on these keys.

## Summary

- **Connection limits** (`MAX_IDLE_CONNS`, `MAX_OPEN_CONNS`, `CONN_MAX_LIFETIME`) prevent resource exhaustion and connection staleness, configured in [`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/modules/setting/database.go) and applied in [`models/db/engine_init.go`](https://github.com/go-gitea/gitea/blob/main/models/db/engine_init.go).
- **Buffer and logging controls** (`ITERATE_BUFFER_SIZE`, `SLOW_QUERY_THRESHOLD`, `LOG_SQL`) balance memory usage against observability needs.
- **Resilience settings** (`DB_RETRIES`, `DB_RETRY_BACKOFF`) ensure graceful recovery from transient database unavailability.
- **Startup behavior** (`AUTO_MIGRATION`) can be disabled to accelerate initialization in controlled deployment environments.

## Frequently Asked Questions

### How do I prevent "too many connections" errors in Gitea?

Set **`MAX_OPEN_CONNS`** in [`app.ini`](https://github.com/go-gitea/gitea/blob/main/app.ini) to a value below your database server’s connection limit. For MySQL, this typically means configuring `MAX_OPEN_CONNS = 100` or lower, depending on your `max_connections` setting and other applications sharing the instance.

### What is the optimal CONN_MAX_LIFETIME for MySQL backends?

While Gitea defaults to `3s` for MySQL, production deployments often benefit from `30s` to `60s` to reduce connection churn, provided your MySQL `wait_timeout` exceeds this value significantly. Monitor for "gone away" errors to find the stable maximum for your network topology.

### Does enabling LOG_SQL impact Gitea performance?

Yes. **`LOG_SQL = true`** forces XORM to write every SQL statement to disk, which introduces substantial I/O overhead and log volume. Enable it only during debugging sessions and ensure **`SLOW_QUERY_THRESHOLD`** is configured for production monitoring instead.

### Where are database settings parsed in the Gitea source code?

Configuration parsing occurs in **[`modules/setting/database.go`](https://github.com/go-gitea/gitea/blob/main/modules/setting/database.go)** within the `LoadDBSetting` function (lines 78‑91), where values are mapped to the `Database` struct. These values are then applied to the XORM engine in **[`models/db/engine_init.go`](https://github.com/go-gitea/gitea/blob/main/models/db/engine_init.go)** (lines 70‑73) via setter methods like `SetMaxOpenConns`.