Takuto で外部データベースを使う

デフォルトでは、Takuto はデータをローカルの SQLite ファイル（データディレクトリ内の takuto.db）に保存します。マルチユーザー構成や本番運用では、代わりに外部の PostgreSQL、 MariaDB、MySQL データベースに Takuto を向けることができます。

何より大事な唯一のルール

config.toml の接続文字列は、Takuto container 自身 が使います。したがって、その文字列 の中のホストは、その container の内側から 到達できなければなりません:

• ✅ データベースを 別の container として動かしているなら、その container/サービス名 と 内部ポート を使い、両方の container が同じネットワークを共有していることを確かめてください。
• ❌ localhost や 127.0.0.1 は 使わないでください — Takuto container の内側では、 それはデータベースではなく Takuto 自身を指してしまいます。
• ❌ ホスト側に公開したポート（例: -p 5433:5432 のマッピング）も 使わないでください。 そのポートはホストマシン上にしか存在せず、container ネットワーク上にはありません。

目安: localhost:<published-port> は、ホストマシン から接続するためのもの（psql や GUI クライアント）。<container-name>:<internal-port> は、Takuto のためのものです。

ステップ 1 — Takuto のネットワーク上でデータベース container を動かす

Takuto の container 群は Docker/Podman のネットワークを共有します（Compose で起動した場合は プロジェクトのデフォルトネットワーク、例: <project>_default）。データベースをその 同じ ネットワーク に載せてください。いちばん簡単なのは、同じ Compose ファイルにデータベースを サービスとして追加して自動的に参加させる方法です。あるいは、単体で動かしてネットワークに アタッチすることもできます。

各エンジンでは、初回起動時にデータベースとアプリケーションユーザーを作成する必要があります:

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

永続化: 上記の -v takuto_db-data:/… という名前付きボリュームこそが、container を 作り直してもデータが生き残るようにするものです。これがないと、container を削除した時点で データも消えます。

ステップ 2 — config.toml に接続文字列を設定する

.takuto/config.toml の [database] セクションを編集します:

[database]
connection = "<CONNECTION_STRING>"
fail_fast = true          # DB に到達できなければ起動を中断する（推奨）
import_from_sqlite = true # 初回接続時に既存のローカル SQLite データを移行する

エンジンに応じた スキームと内部ポート を使い、ホストにはデータベースの container 名 を 指定します:

MariaDB と MySQL はどちらも mysql:// スキームを使います。内部 ポート（5432 / 3306）に 注意してください — -p で公開したポートではありません。

ステップ 3 — Takuto を再起動する

Takuto は起動時に config.toml を読み込むので、変更を適用するには再起動します:

takuto restart

ステップ 4 — 確認する

Takuto のログを確認します。接続に成功すると、次のようなログが出ます:

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

fail_fast = true のとき、設定が誤っていたり到達できないデータベースだと、起動は SQLite に 黙ってフォールバックするのではなく、エラーで 中断 します — つまり、きれいに起動できたなら 外部データベースが使われているということです。Takuto の egress 層も、ホストを認識すると Allowing database sidecar: takuto_db:5432 をログに出します。データベースに接続して、 Takuto のテーブル（users、sessions、credentials、repositories、…）が作成されている ことを確認することもできます。

ホストマシンから接続する（任意）

ローカルのクライアントでデータベースを覗くには、公開した ポート（-p）を使い、localhost 経由で接続します:

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

ここが localhost で正しい唯一の場所です — Takuto container の内側からではなく、ホストから 接続しているからです。

トラブルシューティング

キーの全一覧（プールのサイジング、タイムアウト、SQLite インポート）は [database] リファレンス を参照してください。