Usar una base de datos externa con Takuto

Por defecto, Takuto guarda sus datos en un archivo SQLite local (takuto.db en el directorio de datos). Para configuraciones multiusuario o uso en producción, puedes apuntar Takuto a una base de datos externa PostgreSQL, MariaDB o MySQL en su lugar.

La regla que más importa

La cadena de conexión de config.toml la usa el propio container de Takuto. Así que el host de esa cadena debe ser alcanzable desde dentro de ese container:

• ✅ Si tu base de datos corre como otro container, usa su nombre de container/servicio y su puerto interno, y asegúrate de que ambos containers comparten una red.
• ❌ No uses localhost ni 127.0.0.1 — dentro del container de Takuto eso apunta de vuelta a Takuto, no a tu base de datos.
• ❌ No uses el puerto publicado en el host (p. ej. un mapeo -p 5433:5432). Ese puerto solo existe en tu máquina host, no en la red de containers.

Regla práctica: localhost:<puerto-publicado> es para conectarte desde tu máquina host (psql, un cliente GUI). <nombre-container>:<puerto-interno> es para Takuto.

Paso 1 — Ejecuta un container de base de datos en la red de Takuto

Los containers de Takuto comparten una red de Docker/Podman (cuando se arrancan vía Compose, es la red por defecto del proyecto, p. ej. <project>_default). Pon tu base de datos en esa misma red. Lo más sencillo es añadir la base de datos como un servicio en el mismo archivo de Compose para que se una automáticamente; como alternativa, ejecútala de forma autónoma y conéctala a la red.

Cada motor necesita una base de datos y un usuario de aplicación creados en el primer arranque:

PostgreSQL

docker run -d --name takuto_db --network <takuto-network> \
  -e POSTGRES_USER=takuto \
  -e POSTGRES_PASSWORD='<DB_PASSWORD>' \
  -e POSTGRES_DB=takuto \
  -v takuto_db-data:/var/lib/postgresql/data \
  -p 5433:5432 \
  postgres:16-alpine

MariaDB

docker run -d --name takuto_db --network <takuto-network> \
  -e MARIADB_ROOT_PASSWORD='<ROOT_PASSWORD>' \
  -e MARIADB_DATABASE=takuto \
  -e MARIADB_USER=takuto \
  -e MARIADB_PASSWORD='<DB_PASSWORD>' \
  -v takuto_db-data:/var/lib/mysql \
  -p 3306:3306 \
  mariadb:11

MySQL

docker run -d --name takuto_db --network <takuto-network> \
  -e MYSQL_ROOT_PASSWORD='<ROOT_PASSWORD>' \
  -e MYSQL_DATABASE=takuto \
  -e MYSQL_USER=takuto \
  -e MYSQL_PASSWORD='<DB_PASSWORD>' \
  -v takuto_db-data:/var/lib/mysql \
  -p 3306:3306 \
  mysql:8

Persistencia: el volumen con nombre -v takuto_db-data:/… de arriba es lo que hace que tus datos sobrevivan a la recreación del container. Sin él, eliminar el container borra los datos.

Paso 2 — Fija la cadena de conexión en config.toml

Edita la sección [database] de .takuto/config.toml:

[database]
connection = "<CONNECTION_STRING>"
fail_fast = true          # abort startup if the DB is unreachable (recommended)
import_from_sqlite = true # migrate existing local SQLite data on first connect

Usa el esquema y el puerto interno de tu motor, con el nombre del container de la base de datos como host:

Tanto MariaDB como MySQL usan el esquema mysql://. Fíjate en los puertos internos (5432 / 3306) — no en los publicados con -p.

Paso 3 — Reinicia Takuto

Takuto lee config.toml al arrancar, así que reinícialo para aplicar el cambio:

takuto restart

Paso 4 — Verifica

Revisa los logs de Takuto. Una conexión correcta registra algo como:

Multi-user database initialized (external backend)  backend="postgres"  url="postgresql://takuto:****@takuto_db:5432/takuto"

Con fail_fast = true, una base de datos mal configurada o inalcanzable hace que el arranque aborte con un error en lugar de recurrir silenciosamente a SQLite — así que un arranque limpio significa que la base de datos externa está en uso. La capa de egress de Takuto también registra Allowing database sidecar: takuto_db:5432 cuando reconoce el host. También puedes conectarte a la base de datos y confirmar que se crearon las tablas de Takuto (users, sessions, credentials, repositories, …).

Conectarte desde tu máquina host (opcional)

Para inspeccionar la base de datos con un cliente local, usa el puerto publicado (-p) y conéctate vía localhost:

postgresql://takuto:<DB_PASSWORD>@localhost:5433/takuto
mysql://takuto:<DB_PASSWORD>@localhost:3306/takuto

Este es el único sitio donde localhost es correcto — porque te conectas desde el host, no desde dentro del container de Takuto.

Solución de problemas

Consulta la referencia de [database] para el conjunto completo de claves (tamaño del pool, timeouts, importación desde SQLite).