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.

Câbler un container de base de données existant avec takuto-cli

Si vous utilisez le CLI Takuto et que votre base tourne dans un container sur cette machine, vous ne traduisez rien à la main. Pendant takuto setup, choisissez « A database container running on this machine (auto-wire it) » et donnez l’URL exactement comme vous l’utiliseriez depuis votre hôte — celle en localhost que vous colleriez dans psql ou un client graphique :

[database]
connection = "postgres://takuto:<DB_PASSWORD>@localhost:5433/takuto"
local_container = true   # posé par l'assistant — indique au CLI de câbler au démarrage

À chaque takuto start, le CLI (1) trouve le container qui publie ce port et son port interne, (2) le rattache au réseau de Takuto sous l’alias stable takuto_db, et (3) écrit une TAKUTO_DATABASE_CONNECTION orientée container (…@takuto_db:5432/…) dans takuto.env, que le moteur utilise au démarrage. Vous continuez à raisonner en localhost ; le CLI fait la traduction de namespace réseau.

La seule exigence : démarrez votre container de base de données avant takuto start. Si rien ne publie ce port, le CLI émet un avertissement et laisse la chaîne inchangée — démarrez la base et relancez takuto start.

Une base distante ou native sur l’hôte, c’est différent : choisissez l’option remote / host-native dans l’assistant et donnez une URL déjà joignable telle quelle.

L’overlay Compose intégré

Si vous faites tourner le moteur depuis Takuto Core avec Docker Compose, la voie prise en charge est l’overlay de base de données fourni. Il ajoute la base sur le bon réseau, injecte la chaîne de connexion à votre place, et attend que la base soit en bonne santé avant que Takuto ne démarre — ce qui contourne à la fois les problèmes de réseau et de course au démarrage décrits plus bas :

# PostgreSQL
docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d
# or: make start BACKEND=postgres

# MariaDB / MySQL
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml up -d
# or: make start BACKEND=mariadb

Surchargez les valeurs par défaut avec POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB (ou les équivalents MARIADB_*) dans votre environnement. L’overlay définit TAKUTO_DATABASE_CONNECTION (qui surcharge [database].connection), vous n’éditez donc aucune chaîne à la main, et un import SQLite → externe en une fois s’exécute au premier démarrage.

Le faire à la main (en lançant le moteur directement)

Si vous lancez Takuto Core vous-même sans le CLI, il n’y a pas de câblage automatique : vous définissez une chaîne de connexion que le container Takuto peut joindre telle quelle. Le reste de cette page couvre ce cas — une base que vous faites tourner séparément, ou une qui vit déjà sur un autre réseau.

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.

Réutiliser un container de base de données que vous avez déjà

Vous faites déjà tourner PostgreSQL (ou MariaDB/MySQL) dans un container — peut-être issu d’un autre projet Compose ? Ne le recréez pas. Mettez-le sur le réseau que le container takuto utilise réellement — celui du sidecar dind — donnez-lui un alias stable, puis construisez la chaîne à partir de cet alias :

# 1. Trouver le réseau du sidecar dind (donc celui de takuto) :
docker inspect takuto-dind | grep -A8 '"Networks"'

# 2. Rattacher votre container DB existant à ce réseau, sous un alias stable :
docker network connect --alias takuto_db <réseau-de-l-étape-1> <votre-container-db>

# 3. Construire la chaîne à partir de l'alias + le port INTERNE de la base, p. ex. :
#    postgresql://<user>:<password>@takuto_db:5432/<db>

Le host est l’alias (takuto_db) — jamais localhost — et le port est le port interne du container (5432 / 3306), pas un port publié via -p. Mettez-la dans [database].connection (étape 2) et redémarrez. Les étapes ci-dessous couvrent plutôt la création d’une base de zéro.

É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.

Quel est le « réseau de Takuto » ? C’est le point qui fait trébucher tout le monde. Quand le sidecar Docker-in-Docker est activé, le container takuto n’a aucun réseau qui lui soit propre — il partage le network namespace du container dind (network_mode: service:dind). Le réseau qui compte est donc celui auquel le container dind est attaché (typiquement le réseau par défaut du projet Compose, par ex. takuto-core_default), pas un réseau nommé d’après Takuto. Trouvez-le avec :

docker inspect <dind-container> | grep -A8 '"Networks"'

Attachez votre base à ce réseau, et référencez-la par son nom/alias sur ce réseau.

Base déjà en train de tourner sur un autre réseau ? Pas besoin de la recréer — reliez-la au réseau de Takuto et donnez-lui l’alias attendu par votre chaîne de connexion :

docker network connect --alias takuto_db <takuto-network> <your-db-container>

Le --alias takuto_db fait que la base se résout en takuto_db sur ce réseau, de sorte qu’une chaîne de connexion comme …@takuto_db:5432/… continue de fonctionner sans changement.

É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).