Bases de Datos en Forgejo

Forgejo soporta tres motores de base de datos: SQLite, PostgreSQL y MySQL/MariaDB. La eleccion correcta depende del tamano del equipo y los requisitos de disponibilidad.

---

SQLite: cuando es suficiente

SQLite es la opcion predeterminada y funciona bien para:

• Equipos pequenos (menos de 50 usuarios activos)
• Instancias personales o de prueba
• Entornos donde la simplicidad operativa es prioritaria
• Casos donde no se requiere alta disponibilidad ni replicacion

Ventajas de SQLite:

• Sin proceso de base de datos separado
• Un solo archivo para toda la base de datos
• Backup trivial: copiar el archivo es suficiente
• Cero configuracion adicional

Desventajas:

• No soporta escrituras concurrentes con buen rendimiento
• No escala horizontalmente
• No es adecuado para alta disponibilidad con failover

Con la configuracion por defecto de Docker Compose, Forgejo usa SQLite y almacena el archivo en el volumen de datos.

---

PostgreSQL: cuando migrar

Considera migrar a PostgreSQL cuando:

• El equipo supera los 50 usuarios activos
• Hay muchas operaciones concurrentes (CI/CD activo, muchos pushes simultaneos)
• Necesitas replicacion para alta disponibilidad
• El tiempo de respuesta de la interfaz web empieza a degradarse

PostgreSQL soporta escrituras concurrentes eficientemente y permite configurar replicas de lectura para distribuir la carga.

---

Configurar PostgreSQL con Docker Compose

El siguiente docker-compose.yml agrega un servicio PostgreSQL junto a Forgejo:

services:
  postgres:
    image: postgres:16-alpine
    container_name: forgejo_db
    restart: unless-stopped
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: contrasena_segura
      POSTGRES_DB: forgejo
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - forgejo_net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U forgejo"]
      interval: 10s
      timeout: 5s
      retries: 5

  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    container_name: forgejo
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=postgres:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=contrasena_segura
    volumes:
      - forgejo_data:/data
    ports:
      - "3000:3000"
      - "2222:22"
    networks:
      - forgejo_net

volumes:
  postgres_data:
  forgejo_data:

networks:
  forgejo_net:

Las variables de entorno con prefijo FORGEJO__seccion__clave sobreescriben la configuracion de app.ini. El formato usa doble guion bajo para separar seccion de clave.

---

Configurar app.ini para PostgreSQL

Si prefieres configurar directamente en app.ini en lugar de variables de entorno:

[database]
DB_TYPE  = postgres
HOST     = localhost:5432
NAME     = forgejo
USER     = forgejo
PASSWD   = contrasena_segura
SSL_MODE = disable
SCHEMA   = public

Para conexiones SSL en produccion:

[database]
SSL_MODE = require

---

Migracion de SQLite a PostgreSQL

El proceso implica crear un dump completo, levantar PostgreSQL y restaurar los datos.

Paso 1: crear el dump desde el contenedor

docker exec -u git forgejo \
  forgejo dump -c /data/gitea/conf/app.ini \
  --type zip \
  -f /tmp/forgejo-dump.zip

docker cp forgejo:/tmp/forgejo-dump.zip ./forgejo-dump.zip

Paso 2: preparar PostgreSQL

Asegurate de que el servicio PostgreSQL esta corriendo y la base de datos forgejo existe:

docker exec -it forgejo_db psql -U postgres -c "CREATE DATABASE forgejo OWNER forgejo;"

Paso 3: actualizar la configuracion

Modifica app.ini o las variables de entorno para apuntar a PostgreSQL antes de iniciar Forgejo.

Paso 4: restaurar el dump

# Detener Forgejo
docker stop forgejo

# Descomprimir el dump
unzip forgejo-dump.zip -d forgejo-restore/

# Iniciar Forgejo con nueva configuracion de DB
# Forgejo ejecuta migraciones automaticamente al iniciar
docker start forgejo

Paso 5: verificar integridad

docker logs forgejo 2>&1 | grep -i "migration\|error\|fatal"

Si no hay errores de migracion, la base de datos se creo correctamente. Verifica accediendo a la interfaz web y comprobando que los repositorios, usuarios y configuraciones son correctos.

---

MySQL y MariaDB

Forgejo tambien soporta MySQL 5.7+ y MariaDB 10.4+. La configuracion en app.ini es:

[database]
DB_TYPE  = mysql
HOST     = localhost:3306
NAME     = forgejo
USER     = forgejo
PASSWD   = contrasena_segura
CHARSET  = utf8mb4

El charset utf8mb4 es obligatorio para soportar correctamente caracteres Unicode, incluyendo emojis en mensajes de commit.

En terminos generales, PostgreSQL es preferible a MySQL para instalaciones nuevas por su mejor manejo de transacciones concurrentes y su soporte de tipos de datos mas avanzados.

---

Siguiente: Capitulo 21: Backups y Actualizaciones