Database Configuration

Configure and manage Gitea’s database backend

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 (Recommended)

PostgreSQL offers the best performance and features for production deployments.

Installation

Ubuntu/Debian

sudo apt update
sudo apt install postgresql postgresql-contrib

sudo yum install postgresql-server postgresql-contrib
sudo postgresql-setup initdb
sudo systemctl start postgresql
sudo systemctl enable postgresql

brew install postgresql
brew services start postgresql

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

Ubuntu/Debian

sudo apt update
sudo apt install mysql-server

sudo yum install mysql-server
sudo systemctl start mysqld
sudo systemctl enable mysqld

brew install mysql
brew services start mysql

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):

PostgreSQL

postgres://username:password@host:port/database?sslmode=disable

username:password@tcp(host:port)/database?parseTime=true&tls=false

file:path/to/gitea.db?cache=shared&mode=rwc&_busy_timeout=500

server=host; port=1433; database=gitea; user id=username; password=password;

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

Related Resources

• Configuration
• Backup and Restore
• Command-Line Tools