Utiliser une base de données externe avec Takuto

Par défaut, Takuto stocke ses données dans un fichier SQLite local (takuto.db dans le répertoire de données). Pour des déploiements multi-utilisateurs ou une mise en production, vous pouvez plutôt pointer Takuto sur une base PostgreSQL, MariaDB ou MySQL externe.

La règle qui compte le plus

La chaîne de connexion dans config.toml est utilisée par le container Takuto lui-même. L’hôte dans cette chaîne doit donc être joignable depuis l’intérieur de ce container :

• ✅ Si votre base tourne comme un autre container, utilisez son nom de container/de service et son port interne, et assurez-vous que les deux containers partagent un réseau.
• ❌ N’utilisez pas localhost ni 127.0.0.1 — à l’intérieur du container Takuto, cela pointe vers Takuto, pas vers votre base.
• ❌ N’utilisez pas le port publié sur l’hôte (par ex. un mappage -p 5433:5432). Ce port n’existe que sur votre machine hôte, pas sur le réseau des containers.

Règle générale : localhost:<port-publié> sert à se connecter depuis votre machine hôte (psql, un client graphique). <nom-du-container>:<port-interne> sert à Takuto.

Étape 1 — Faire tourner un container de base de données sur le réseau de Takuto

Les containers de Takuto partagent un réseau Docker/Podman (au démarrage via Compose, c’est le réseau par défaut du projet, par ex. <project>_default). Placez votre base sur ce même réseau. L’approche la plus simple est d’ajouter la base comme service dans le même fichier Compose pour qu’elle le rejoigne automatiquement ; sinon, faites-la tourner en standalone et attachez-la au réseau.

Chaque moteur a besoin qu’une base de données et un utilisateur applicatif soient créés au premier démarrage :

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

Persistance : le volume nommé -v takuto_db-data:/… ci-dessus est ce qui permet à vos données de survivre à une recréation du container. Sans lui, supprimer le container efface les données.

Étape 2 — Définir la chaîne de connexion dans config.toml

Éditez la section [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

Utilisez le schéma et le port interne de votre moteur, avec le nom de container de la base comme hôte :

MariaDB et MySQL utilisent tous deux le schéma mysql://. Notez bien les ports internes (5432 / 3306) — pas ceux publiés via -p.

Étape 3 — Redémarrer Takuto

Takuto lit config.toml au démarrage : redémarrez-le donc pour appliquer le changement :

takuto restart

Étape 4 — Vérifier

Consultez les logs de Takuto. Une connexion réussie logge quelque chose comme :

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

Avec fail_fast = true, une base mal configurée ou injoignable fait avorter le démarrage avec une erreur plutôt que de retomber silencieusement sur SQLite — un démarrage propre signifie donc que la base externe est bien utilisée. La couche d’egress de Takuto logge aussi Allowing database sidecar: takuto_db:5432 lorsqu’elle reconnaît l’hôte. Vous pouvez également vous connecter à la base et confirmer que les tables de Takuto (users, sessions, credentials, repositories, …) ont bien été créées.

Se connecter depuis votre machine hôte (optionnel)

Pour inspecter la base avec un client local, utilisez le port publié (-p) et connectez-vous via localhost :

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

C’est le seul endroit où localhost est correct — parce que vous vous connectez depuis l’hôte, pas depuis l’intérieur du container Takuto.

Dépannage

Voir la référence de [database] pour l’ensemble complet des clés (dimensionnement du pool, timeouts, import SQLite).