配合 Takuto 使用外部数据库

默认情况下，Takuto 把数据存放在一个本地 SQLite 文件里（数据目录下的 takuto.db）。 若是多用户部署或生产使用，你可以改为把 Takuto 指向一个外部的 PostgreSQL、 MariaDB 或 MySQL 数据库。

最要紧的一条规则

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          # 数据库不可达时中止启动（推荐）
import_from_sqlite = true # 首次连接时迁移已有的本地 SQLite 数据

为你的引擎使用对应的 scheme 和内部端口，并以数据库的 container 名作为主机：

MariaDB 和 MySQL 都使用 mysql:// scheme。注意这里是内部端口（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] 参考。