> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```go theme={null}
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

<CodeGroup>
  ```bash Ubuntu/Debian theme={null}
  sudo apt update
  sudo apt install postgresql postgresql-contrib
  ```

  ```bash RHEL/CentOS theme={null}
  sudo yum install postgresql-server postgresql-contrib
  sudo postgresql-setup initdb
  sudo systemctl start postgresql
  sudo systemctl enable postgresql
  ```

  ```bash macOS theme={null}
  brew install postgresql
  brew services start postgresql
  ```
</CodeGroup>

### Database Setup

<Steps>
  <Step title="Create Database and User">
    ```sql theme={null}
    -- 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;
    ```
  </Step>

  <Step title="Configure app.ini">
    ```ini theme={null}
    [database]
    DB_TYPE = postgres
    HOST = 127.0.0.1:5432
    NAME = gitea
    USER = gitea
    PASSWD = your-secure-password
    SCHEMA = public
    SSL_MODE = disable
    ```
  </Step>

  <Step title="Test Connection">
    Start Gitea and verify it connects successfully:

    ```bash theme={null}
    ./gitea web
    ```
  </Step>
</Steps>

### PostgreSQL Configuration Options

<ParamField path="HOST" type="string" default="127.0.0.1:5432">
  PostgreSQL server address. Can be:

  * `hostname:port` - TCP connection
  * `/var/run/postgresql/` - Unix socket
</ParamField>

<ParamField path="NAME" type="string" required>
  Database name
</ParamField>

<ParamField path="USER" type="string" required>
  Database user
</ParamField>

<ParamField path="PASSWD" type="string">
  Database password. Use quotes for special characters: `PASSWD = "p@ssw0rd!"`
</ParamField>

<ParamField path="SCHEMA" type="string" default="public">
  PostgreSQL schema to use
</ParamField>

<ParamField path="SSL_MODE" type="string" default="disable">
  SSL mode: `disable`, `require`, or `verify-full`
</ParamField>

### PostgreSQL with Unix Socket

```ini theme={null}
[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

<CodeGroup>
  ```bash Ubuntu/Debian theme={null}
  sudo apt update
  sudo apt install mysql-server
  ```

  ```bash RHEL/CentOS theme={null}
  sudo yum install mysql-server
  sudo systemctl start mysqld
  sudo systemctl enable mysqld
  ```

  ```bash macOS theme={null}
  brew install mysql
  brew services start mysql
  ```
</CodeGroup>

### Database Setup

<Steps>
  <Step title="Run MySQL Secure Installation">
    ```bash theme={null}
    sudo mysql_secure_installation
    ```
  </Step>

  <Step title="Create Database and User">
    ```sql theme={null}
    -- 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;
    ```
  </Step>

  <Step title="Configure app.ini">
    ```ini theme={null}
    [database]
    DB_TYPE = mysql
    HOST = 127.0.0.1:3306
    NAME = gitea
    USER = gitea
    PASSWD = your-secure-password
    CHARSET_COLLATION = utf8mb4_unicode_ci
    ```
  </Step>
</Steps>

### MySQL Configuration Options

<ParamField path="HOST" type="string" default="127.0.0.1:3306">
  MySQL server address. Can be:

  * `hostname:port` - TCP connection
  * `/var/run/mysqld/mysqld.sock` - Unix socket
</ParamField>

<ParamField path="SSL_MODE" type="string" default="false">
  Enable TLS connection: `false`, `true`, or `skip-verify`
</ParamField>

<ParamField path="CHARSET_COLLATION" type="string">
  Character set collation. Gitea will auto-detect a case-sensitive collation if empty.
  Recommended: `utf8mb4_unicode_ci` or `utf8mb4_bin`
</ParamField>

### MySQL with Unix Socket

```ini theme={null}
[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

```ini theme={null}
[database]
DB_TYPE = sqlite3
PATH = data/gitea.db
SQLITE_TIMEOUT = 500
SQLITE_JOURNAL_MODE = WAL
```

### SQLite Configuration Options

<ParamField path="PATH" type="string" default="data/gitea.db">
  Path to SQLite database file. Relative paths are resolved from `APP_DATA_PATH`.
</ParamField>

<ParamField path="SQLITE_TIMEOUT" type="number" default="500">
  Query timeout in milliseconds
</ParamField>

<ParamField path="SQLITE_JOURNAL_MODE" type="string">
  Journal mode: `DELETE`, `TRUNCATE`, `PERSIST`, `MEMORY`, or `WAL` (recommended)
</ParamField>

### 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

```sql theme={null}
-- 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

```ini theme={null}
[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

<ParamField path="HOST" type="string" default="127.0.0.1:1433">
  MSSQL server address. Format: `hostname:port` or `hostname,port`
</ParamField>

<ParamField path="CHARSET_COLLATION" type="string">
  Character set collation. Use a case-sensitive collation like `Latin1_General_CS_AS`
</ParamField>

## Common Database Settings

These settings apply to all database types and are configured in `modules/setting/database.go:27-52`:

<ParamField path="LOG_SQL" type="boolean" default="false">
  Log all SQL queries (useful for debugging, not recommended for production)
</ParamField>

<ParamField path="MAX_IDLE_CONNS" type="number" default="2">
  Maximum number of idle database connections in the pool
</ParamField>

<ParamField path="MAX_OPEN_CONNS" type="number" default="0">
  Maximum number of open database connections (0 = unlimited)
</ParamField>

<ParamField path="CONN_MAX_LIFETIME" type="duration" default="0">
  Maximum lifetime of database connections (MySQL: 3s, others: 0)
</ParamField>

<ParamField path="DB_RETRIES" type="number" default="10">
  Number of database connection retry attempts on startup
</ParamField>

<ParamField path="DB_RETRY_BACKOFF" type="duration" default="3s">
  Time to wait between connection retry attempts
</ParamField>

<ParamField path="ITERATE_BUFFER_SIZE" type="number" default="50">
  Buffer size for iterating database results
</ParamField>

<ParamField path="AUTO_MIGRATION" type="boolean" default="true">
  Automatically run database migrations on startup
</ParamField>

<ParamField path="SLOW_QUERY_THRESHOLD" type="duration" default="5s">
  Log queries that take longer than this threshold
</ParamField>

## Connection String Format

Gitea builds connection strings based on the configured database type (see `modules/setting/database.go:95-136`):

<CodeGroup>
  ```text PostgreSQL theme={null}
  postgres://username:password@host:port/database?sslmode=disable
  ```

  ```text MySQL theme={null}
  username:password@tcp(host:port)/database?parseTime=true&tls=false
  ```

  ```text SQLite theme={null}
  file:path/to/gitea.db?cache=shared&mode=rwc&_busy_timeout=500
  ```

  ```text MSSQL theme={null}
  server=host; port=1433; database=gitea; user id=username; password=password;
  ```
</CodeGroup>

## Database Maintenance

### Backup Database

See [Backup and Restore](/admin/backup-restore) for complete backup procedures.

### Check Database Connection

```bash theme={null}
gitea doctor check --run db-version
```

### View Database Statistics

```bash theme={null}
gitea manager show-config | grep -A 20 "\[database\]"
```

## Performance Tuning

### PostgreSQL

```ini theme={null}
[database]
MAX_IDLE_CONNS = 10
MAX_OPEN_CONNS = 100
CONN_MAX_LIFETIME = 3600s
```

### MySQL

```ini theme={null}
[database]
MAX_IDLE_CONNS = 10
MAX_OPEN_CONNS = 100
CONN_MAX_LIFETIME = 3s
```

## Troubleshooting

### Connection Issues

<Steps>
  <Step title="Verify Database is Running">
    ```bash theme={null}
    # PostgreSQL
    sudo systemctl status postgresql

    # MySQL
    sudo systemctl status mysql
    ```
  </Step>

  <Step title="Test Connection Manually">
    ```bash theme={null}
    # PostgreSQL
    psql -h 127.0.0.1 -U gitea -d gitea

    # MySQL
    mysql -h 127.0.0.1 -u gitea -p gitea
    ```
  </Step>

  <Step title="Check Firewall Rules">
    Ensure the database port is accessible from the Gitea server
  </Step>

  <Step title="Review Gitea Logs">
    ```bash theme={null}
    tail -f /var/log/gitea/gitea.log | grep -i database
    ```
  </Step>
</Steps>

### Migration Issues

```bash theme={null}
# 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](/admin/configuration)
* [Backup and Restore](/admin/backup-restore)
* [Command-Line Tools](/admin/command-line)