第 2 章 · CLI 与数据库管理

2.1 安装

# macOS / Linux (推荐)
curl -sSfL https://get.tur.so/install.sh | bash

# Homebrew
brew install tursodatabase/tap/turso

# Windows (WSL)
# 推荐 WSL；原生 Windows 用 npm 包 turso-cli
npm install -g turso-cli

# 验证
turso --version
# turso version v1.x.x

2.2 登录：turso auth

turso auth signup    # 首次注册，浏览器跳转 GitHub OAuth
turso auth login     # 已有账号登录
turso auth whoami    # 看当前身份
turso auth logout    # 登出（清掉 ~/.config/turso/settings.json）

登录态存在 ~/.config/turso/。CI 不用 login，而是用 token（见 §2.7）。

2.3 创建数据库

turso db create my-app
# ✔ Creating database my-app in Amsterdam, Netherlands (ams)

# 指定区域
turso db create my-app --location nrt    # 东京

# 从本地 SQLite 文件导入
turso db create my-app --from-file ./local.db

# 从另一个 Turso 数据库复制
turso db create my-app-staging --from-db production

查看所有区域

turso db locations
# 列出 40+ 区域及其代号：ams fra nrt sin gru hkg ...

2.4 查看与销毁

turso db list                   # 列出所有库
turso db show my-app            # 详细信息（URL、区域、大小）
turso db destroy my-app         # 删除（要确认）
turso db destroy my-app --yes   # 免确认（慎用）

show 输出的关键：

HTTP URL：libsql://my-app-xxx.turso.io——客户端连接地址
regions：primary + 所有 replica
size：当前占用字节

2.5 交互式 shell

turso db shell my-app

打开一个 SQLite 风格的 REPL，可以直接 SELECT * FROM users;。底层走 libSQL HTTP，所以延迟是网络级别（跨洋约 200ms）。适合快速查库、调试 schema。

my-app> .tables                # 列出表
my-app> .schema users          # 看建表 SQL
my-app> .dump > backup.sql     # 导出全库 SQL
my-app> .quit

2.6 副本与 Group

Turso 新版把"单个数据库 + 多区域"的概念提升为Group——一个 Group 是一组互相复制的区域，数据库挂在 Group 下。

# 查看当前 Group
turso group list

# 默认有个 "default" Group，往里加副本
turso group locations add default fra nrt gru

# 新建一个 Group 单独隔离
turso group create edge --location ams
turso group locations add edge fra nrt sin

# 创建数据库时指定 Group
turso db create my-app --group edge

删除副本

turso group locations rm default gru

副本不是白加

每多一个副本就多一份存储 + 复制流量 + 连接费用。通常 3–5 个覆盖你的主要市场就够。加到所有 40 个区域没意义，小流量项目反而容易撞额度。

2.7 Token：服务端连接凭证

客户端连 libsql://... URL 需要带 JWT。用 CLI 签发：

# 长期只读 token
turso db tokens create my-app --expiration none --read-only

# 7 天读写 token
turso db tokens create my-app --expiration 7d

# 吊销所有 token（紧急泄漏）
turso db tokens invalidate my-app

输出是一串 JWT，存到 .env：

# .env
TURSO_DATABASE_URL=libsql://my-app-acme.turso.io
TURSO_AUTH_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9....

2.8 Organization（团队账户）

turso org list
turso org switch acme-inc      # 切到团队账户
turso db list                   # 现在列的是 acme-inc 下的库
turso org members list acme-inc

Turso 的组织提供成员管理、计费归并。个人账号默认也是一个"personal" org。

2.9 CI 里用 CLI

GitHub Actions 常见模式：

- name: Setup Turso
  uses: tursodatabase/setup-turso@v1

- name: Deploy migrations
  env:
    TURSO_API_TOKEN: ${{ secrets.TURSO_API_TOKEN }}
  run: |
    turso db shell production < ./migrations/latest.sql

TURSO_API_TOKEN 不是库 token，而是管理平台的 API Token，在 Dashboard → Settings → API Tokens 生成。

2.10 常用速查

需求	命令
建库	turso db create NAME --group GROUP
导入 .db	turso db create NAME --from-file X.db
查 URL	turso db show NAME --url
生成 token	turso db tokens create NAME
查大小	turso db inspect NAME
查区域	turso db locations
加副本	turso group locations add GROUP REGION
交互查询	turso db shell NAME
dump SQL	turso db shell NAME .dump > out.sql

小结

turso CLI 是所有 Turso 操作的命令中心：auth login 登录、db create 建库、group locations add 加副本、db tokens create 签客户端凭证、db shell 调试查询。记住这五组命令，90% 的运维动作都能完成。下一章进入 JS SDK。