Gitea Database Performance Tuning: Configuration Options and Best Practices

Gitea provides nine distinct database tuning options controlled via 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 and applied during engine initialization in 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 (lines 43‑44 and 78), these values are loaded from the [database] section and passed to XORM in models/db/engine_init.go at lines 70‑71:

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 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 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. The following example demonstrates production-ready values for a high-throughput MySQL deployment:

[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 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 and applied in 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 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 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 (lines 70‑73) via setter methods like SetMaxOpenConns.

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