Skip to main content

​
Overview

Gitea supports multiple database backends:
  • PostgreSQL (Recommended)
  • MySQL/MariaDB
  • MSSQL (Microsoft SQL Server)
  • SQLite3 (Not recommended for production)

​
Supported Database Types

The supported database types are defined in modules/setting/database.go:19: 
SupportedDatabaseTypes = []string{"mysql", "postgres", "mssql", "sqlite3"}

​
Database Configuration

All database settings are configured in the [database] section of app.ini. PostgreSQL offers the best performance and features for production deployments.

​
Installation

sudo apt update
sudo apt install postgresql postgresql-contrib

​
Database Setup

1

Create Database and User

-- Connect to PostgreSQL as postgres user
sudo -u postgres psql

-- Create database
CREATE DATABASE gitea;

-- Create user with password
CREATE USER gitea WITH PASSWORD 'your-secure-password';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea;
2

Configure app.ini

[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gitea
USER = gitea
PASSWD = your-secure-password
SCHEMA = public
SSL_MODE = disable
3

Test Connection

Start Gitea and verify it connects successfully:
./gitea web

​
PostgreSQL Configuration Options

​
HOST
string
default:"127.0.0.1:5432"
PostgreSQL server address. Can be:
  • hostname:port - TCP connection
  • /var/run/postgresql/ - Unix socket
​
NAME
string
required
Database name
​
USER
string
required
Database user
​
PASSWD
string
Database password. Use quotes for special characters: PASSWD = "p@ssw0rd!"
​
SCHEMA
string
default:"public"
PostgreSQL schema to use
​
SSL_MODE
string
default:"disable"
SSL mode: disable, require, or verify-full

​
PostgreSQL with Unix Socket

[database]
DB_TYPE = postgres
HOST = /var/run/postgresql/
NAME = gitea
USER = gitea
PASSWD =
SSL_MODE = disable

​
MySQL/MariaDB

MySQL and MariaDB are widely supported and well-tested.

​
Installation

sudo apt update
sudo apt install mysql-server

​
Database Setup

1

Run MySQL Secure Installation

sudo mysql_secure_installation
2

Create Database and User

-- Connect to MySQL as root
mysql -u root -p

-- Create database with UTF8 encoding
CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Create user
CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'your-secure-password';

-- Grant privileges
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';
FLUSH PRIVILEGES;
3

Configure app.ini

[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306
NAME = gitea
USER = gitea
PASSWD = your-secure-password
CHARSET_COLLATION = utf8mb4_unicode_ci

​
MySQL Configuration Options

​
HOST
string
default:"127.0.0.1:3306"
MySQL server address. Can be:
  • hostname:port - TCP connection
  • /var/run/mysqld/mysqld.sock - Unix socket
​
SSL_MODE
string
default:"false"
Enable TLS connection: false, true, or skip-verify
​
CHARSET_COLLATION
string
Character set collation. Gitea will auto-detect a case-sensitive collation if empty. Recommended: utf8mb4_unicode_ci or utf8mb4_bin

​
MySQL with Unix Socket

[database]
DB_TYPE = mysql
HOST = /var/run/mysqld/mysqld.sock
NAME = gitea
USER = gitea
PASSWD = your-secure-password

​
SQLite

SQLite is simple to set up but not recommended for production or multi-user environments.

​
Configuration

[database]
DB_TYPE = sqlite3
PATH = data/gitea.db
SQLITE_TIMEOUT = 500
SQLITE_JOURNAL_MODE = WAL

​
SQLite Configuration Options

​
PATH
string
default:"data/gitea.db"
Path to SQLite database file. Relative paths are resolved from APP_DATA_PATH.
​
SQLITE_TIMEOUT
number
default:"500"
Query timeout in milliseconds
​
SQLITE_JOURNAL_MODE
string
Journal mode: DELETE, TRUNCATE, PERSIST, MEMORY, or WAL (recommended)

​
SQLite Limitations

  • Limited concurrent write performance
  • No built-in replication
  • Single file can become large
  • Not suitable for high-traffic sites

​
Microsoft SQL Server (MSSQL)

​
Database Setup

-- Create database
CREATE DATABASE gitea;
GO

-- Create login and user
CREATE LOGIN gitea WITH PASSWORD = 'your-secure-password';
GO

USE gitea;
GO

CREATE USER gitea FOR LOGIN gitea;
GO

ALTER ROLE db_owner ADD MEMBER gitea;
GO

​
Configuration

[database]
DB_TYPE = mssql
HOST = 127.0.0.1:1433
NAME = gitea
USER = gitea
PASSWD = your-secure-password
CHARSET_COLLATION = Latin1_General_CS_AS

​
MSSQL Configuration Options

​
HOST
string
default:"127.0.0.1:1433"
MSSQL server address. Format: hostname:port or hostname,port
​
CHARSET_COLLATION
string
Character set collation. Use a case-sensitive collation like Latin1_General_CS_AS

​
Common Database Settings

These settings apply to all database types and are configured in modules/setting/database.go:27-52:
​
LOG_SQL
boolean
default:"false"
Log all SQL queries (useful for debugging, not recommended for production)
​
MAX_IDLE_CONNS
number
default:"2"
Maximum number of idle database connections in the pool
​
MAX_OPEN_CONNS
number
default:"0"
Maximum number of open database connections (0 = unlimited)
​
CONN_MAX_LIFETIME
duration
default:"0"
Maximum lifetime of database connections (MySQL: 3s, others: 0)
​
DB_RETRIES
number
default:"10"
Number of database connection retry attempts on startup
​
DB_RETRY_BACKOFF
duration
default:"3s"
Time to wait between connection retry attempts
​
ITERATE_BUFFER_SIZE
number
default:"50"
Buffer size for iterating database results
​
AUTO_MIGRATION
boolean
default:"true"
Automatically run database migrations on startup
​
SLOW_QUERY_THRESHOLD
duration
default:"5s"
Log queries that take longer than this threshold

​
Connection String Format

Gitea builds connection strings based on the configured database type (see modules/setting/database.go:95-136): 
postgres://username:password@host:port/database?sslmode=disable

​
Database Maintenance

​
Backup Database

See Backup and Restore for complete backup procedures.

​
Check Database Connection

gitea doctor check --run db-version

​
View Database Statistics

gitea manager show-config | grep -A 20 "\[database\]"

​
Performance Tuning

​
PostgreSQL

[database]
MAX_IDLE_CONNS = 10
MAX_OPEN_CONNS = 100
CONN_MAX_LIFETIME = 3600s

​
MySQL

[database]
MAX_IDLE_CONNS = 10
MAX_OPEN_CONNS = 100
CONN_MAX_LIFETIME = 3s

​
Troubleshooting

​
Connection Issues

1

Verify Database is Running

# PostgreSQL
sudo systemctl status postgresql

# MySQL
sudo systemctl status mysql
2

Test Connection Manually

# PostgreSQL
psql -h 127.0.0.1 -U gitea -d gitea

# MySQL
mysql -h 127.0.0.1 -u gitea -p gitea
3

Check Firewall Rules

Ensure the database port is accessible from the Gitea server
4

Review Gitea Logs

tail -f /var/log/gitea/gitea.log | grep -i database

​
Migration Issues

# Check migration status
gitea doctor check --run check-db-version

# Run migrations manually
gitea migrate

​
Best Practices

  • Use PostgreSQL for production deployments
  • Separate Database Server for large installations
  • Regular Backups - automate database backups
  • Connection Pooling - tune MAX_IDLE_CONNS and MAX_OPEN_CONNS
  • Monitor Performance - watch for slow queries
  • Use SSL/TLS for database connections
  • Secure Passwords - use strong, unique passwords

Build docs developers (and LLMs) love

Get started for freeTalk to us