Datasette 0.65.5 常用 CLI 命令与工具详解

Datasette 0.65.5 命令行逐条实测：serve 全参数、--get 冒烟验证、inspect 库摘要、plugins/install/uninstall 插件管理、package 打包与 publish 发布（含 0.65.x 内置目标仅剩 cloudrun/heroku 的版本差异）。

DatasetteDatasetteSQLitePython2026/10/25

Datasette 0.65.5 常用 CLI 命令与工具详解

目标：把 Datasette 0.65.5 命令行工具的每个子命令讲透——serve、inspect、plugins、install、uninstall、package、publish 及全局选项，逐条给出实测命令与真实回显，覆盖日常启动、冒烟验证、插件管理与打包发布全场景。已在 Ubuntu 22.04（Python 3.10.12、Datasette 0.65.5）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Python：3.10.12；Datasette：0.65.5（pipx 与 venv 两种形态并存实测）
  • 演示数据：sales.db（orders 5000 行、customers 300 行，含 customers_fts 全文检索表）、inventory.db（products 5 行），位于 /srv/datasette/app/
  • 命令形态：pipx 安装的在 ~/.local/bin/datasette；venv 安装的在 /opt/datasette/venv/bin/datasette，二者子命令完全一致

二、工具概览

Datasette 只有一个主命令 datasette，全部功能收敛在 7 个子命令里。datasette --help 实测输出：

datasette --help

Usage: datasette [OPTIONS] COMMAND [ARGS]...

  Datasette is an open source multi-tool for exploring and publishing data

  About Datasette: https://datasette.io/
  Full documentation: https://docs.datasette.io/

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  serve*     Serve up specified SQLite database files with a web UI
  inspect    Generate JSON summary of provided database files
  install    Install plugins and packages from PyPI into the same...
  package    Package SQLite files into a Datasette Docker container
  plugins    List currently installed plugins
  publish    Publish specified SQLite database files to the internet...
  uninstall  Uninstall plugins and Python packages from the Datasette...

子命令职责速览：

子命令职责典型场景
serve（默认命令，可省略）启动 Web 服务日常运行、调试、对外发布
inspect生成库结构 JSON 摘要配合不可变模式加速启动
plugins列出已装插件及钩子排障「插件到底装没装上」
install / uninstall从 PyPI 装/卸插件与包扩展能力管理
package把库打包成可分发的运行体交付给运维的制品
publish一键发布到托管平台cloudrun / heroku

💡 说明：serve 后面的 * 表示它是默认命令——datasette sales.db 等价于 datasette serve sales.db。

三、前置条件

  • 已安装 Datasette 0.65.5（pipx 或 venv 形态均可，见《Ubuntu 22.04 安装 Datasette 0.65.5 指南》）；
  • 本文命令均可独立执行；涉及演示库的示例以 /srv/datasette/app/ 下的 sales.db、inventory.db 为例，换成你自己的 .db 文件路径即可。

四、serve：启动 Web 服务（核心命令）

4.1 完整参数速查

serve 是日常用得最多的子命令，先把实测的完整参数表沉淀下来。datasette serve --help 实测输出：

datasette serve --help

Usage: datasette serve [OPTIONS] [FILES]...

  Serve up specified SQLite database files with a web UI

Options:
  -i, --immutable PATH            Database files to open in immutable mode
  -h, --host TEXT                 Host for server. Defaults to 127.0.0.1 which
                                  means only connections from the local
                                  machine will be allowed. Use 0.0.0.0 to
                                  listen to all IPs and allow access from
                                  other machines.
  -p, --port INTEGER RANGE        Port for server, defaults to 8001. Use -p 0
                                  to automatically assign an available port.
                                  [0<=x<=65535]
  --uds TEXT                      Bind to a Unix domain socket
  --reload                        Automatically reload if code or metadata
                                  change detected - useful for development
  --cors                          Enable CORS by serving Access-Control-Allow-
                                  Origin: *
  --load-extension PATH:ENTRYPOINT?
                                  Path to a SQLite extension to load, and
                                  optional entrypoint
  --inspect-file TEXT             Path to JSON file created using "datasette
                                  inspect"
  -m, --metadata FILENAME         Path to JSON/YAML file containing
                                  license/source metadata
  --template-dir DIRECTORY        Path to directory containing custom
                                  templates
  --plugins-dir DIRECTORY         Path to directory containing custom plugins
  --static MOUNT:DIRECTORY        Serve static files from this directory at
                                  /MOUNT/...
  --memory                        Make /_memory database available
  --config CONFIG                 Deprecated: set config option using
                                  configname:value. Use --setting instead.
  --setting SETTING...            Setting, see
                                  docs.datasette.io/en/stable/settings.html
  --secret TEXT                   Secret used for signing secure values, such
                                  as signed cookies
  --root                          Output URL that sets a cookie authenticating
                                  the root user
  --get TEXT                      Run an HTTP GET request against this path,
                                  print results and exit
  --version-note TEXT             Additional note to show on /-/versions
  --help-settings                 Show available settings
  --pdb                           Launch debugger on any errors
  -o, --open                      Open Datasette in your web browser
  --create                        Create database files if they do not exist
  --crossdb                       Enable cross-database joins using the
                                  /_memory database
  --nolock                        Ignore locking, open locked files in read-
                                  only mode
  --ssl-keyfile TEXT              SSL key file
  --ssl-certfile TEXT             SSL certificate file
  --help                          Show this message and exit.

重点参数解读（默认值均为实测回显原文）：

  • -h/--host 默认 127.0.0.1，只有本机能访问；对外须改 0.0.0.0 或走反向代理；
  • -p/--port 默认 8001，-p 0 自动分配空闲端口；
  • -i/--immutable 以不可变模式打开库（启用启动期计数缓存，适合发布后不再变动的数据）；
  • --setting 覆盖运行时参数（可多次使用），旧版 --config 已标记 Deprecated；
  • --get 启动后对指定路径发一次 GET、打印结果并退出，是脚本化冒烟验证的利器；
  • --root 在启动日志输出一次性 root 登录链接（签名 cookie 认证流程实测见《Datasette 0.65.5 配置参数详解》第七节）。

4.2 基本启动与多库挂载

启动一个库（默认 127.0.0.1:8001）：

datasette serve sales.db

同时挂多个库、改端口、开跨域（生产常用组合）：

datasette serve sales.db inventory.db --host 127.0.0.1 --port 8002 --cors

传目录则进入配置目录模式（目录内 .db、settings.json、metadata.json 自动识别）：

datasette serve /srv/datasette/app

启动成功后的日志（实测）：

INFO:     Started server process [6384]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8006 (Press CTRL+C to quit)

4.3 --get：一条命令完成冒烟验证

--get 让进程启动、请求、打印、退出一次完成，非常适合 CI 或安装后自检：

cd /srv/datasette/demo
datasette serve demo.db --port 8006 --get /demo/notes.json

实测回显（节选）：

{"database": "demo", "table": "notes", "is_view": false, "human_description_en": "", "rows": [[1, "第一条笔记", "2026-10-25 10:35:24"], [2, "第二条笔记", "2026-10-25 10:35:24"]], "truncated": false, "filtered_table_rows_count": 2, ...}

返回了表数据 JSON，说明服务、路由、SQL 执行全链路正常。

4.4 不可变模式与 --inspect-file 加速

数据发布后不再变动时，用 -i 标记不可变，并配合第五节的 inspect 摘要跳过启动期的全表计数：

datasette inspect sales.db inventory.db > inspect-data.json
datasette serve -i sales.db -i inventory.db --inspect-file inspect-data.json

大库场景下这能把启动耗时从「逐表 count(*)」降为「读一个 JSON」。

五、inspect：生成库结构摘要

inspect 输出每个库文件的哈希、大小与各表行数，主要用于配合 --inspect-file。

cd /srv/datasette/app
datasette inspect sales.db inventory.db

实测回显：

{
  "sales": {
    "hash": "143055484b172a612a84e4e4ab1b61d996bb002b92530628811432e9bd779d6a",
    "size": 278528,
    "file": "sales.db",
    "tables": {
      "customers": {
        "count": 300
      },
      "orders": {
        "count": 5000
      },
      "customers_fts": {
        "count": 300
      },
      "customers_fts_data": {
        "count": 3
      },
      "customers_fts_idx": {
        "count": 1
      },
      "customers_fts_docsize": {
        "count": 300
      },
      "customers_fts_config": {
        "count": 1
      }
    }
  },
  "inventory": {
    "hash": "31e4a63e16d703523345e15a18c322fd3de59a499792a451109d333038b9bada",
    "size": 8192,
    "file": "inventory.db",
    "tables": {
      "products": {
        "count": 5
      }
    }
  }
}

解读：hash 是内容哈希（库文件变了哈希就变，可用于缓存失效判断）；customers_fts* 是全文检索虚表及其影子表，行数一并列出。日常巡检用它快速确认「库是不是我以为的那份数据」。

六、plugins / install / uninstall：插件管理三件套

6.1 plugins：查看已装插件

未装任何插件时输出空数组：

datasette plugins

[]

6.2 install：从 PyPI 安装插件

以 datasette-json-html（把 JSON 列渲染成可折叠树）为例：

datasette install datasette-json-html

实测回显（节选）：

Using cached datasette_json_html-1.0.1-py3-none-any.whl (9.8 kB)
Installing collected packages: datasette-json-html
Successfully installed datasette-json-html-1.0.1

装完复查：

datasette plugins

[
    {
        "name": "datasette-json-html",
        "static": false,
        "templates": false,
        "version": "1.0.1",
        "hooks": [
            "prepare_connection",
            "render_cell"
        ]
    }
]

解读：输出里最有价值的是 hooks 字段——该插件实现了 prepare_connection 与 render_cell 两个钩子；排障「插件没生效」时先看它是否出现在这里、钩子是否符合预期。插件实际装进了当前 datasette 命令所属的 Python 环境（pipx 形态装进 pipx 的隔离 venv，venv 形态装进对应 venv）。

6.3 uninstall：卸载插件

datasette uninstall datasette-json-html -y

Uninstalling datasette-json-html-1.0.1:
  Successfully uninstalled datasette-json-html-1.0.1

复查：

datasette plugins

[]

⚠️ 注意：-y 跳过确认提示，脚本里必加；交互终端可省略。插件变更后需重启运行中的服务实例才生效。

七、package：打包为可分发运行体

package 把库文件、元数据、插件与 Datasette 本体打成一个标准化分发制品（制品类型与运行要求以官方帮助原文为准，见下方实测输出），交付给具备对应运行能力的平台。datasette package --help 实测输出：

Usage: datasette package [OPTIONS] FILES...

  Package SQLite files into a Datasette Docker container

Options:
  -t, --tag TEXT            Name for the resulting Docker container, can
                            optionally use name:tag format
  -m, --metadata FILENAME   Path to JSON/YAML file containing metadata to
                            publish
  --extra-options TEXT      Extra options to pass to datasette serve
  --branch TEXT             Install datasette from a GitHub branch e.g. main
  --template-dir DIRECTORY  Path to directory containing custom templates
  --plugins-dir DIRECTORY   Path to directory containing custom plugins
  --static MOUNT:DIRECTORY  Serve static files from this directory at
                            /MOUNT/...
  --install TEXT            Additional packages (e.g. plugins) to install
  --spatialite              Enable SpatialLite extension
  --version-note TEXT       Additional note to show on /-/versions
  --secret TEXT             Secret used for signing secure values, such as
                            signed cookies
  -p, --port INTEGER RANGE  Port to run the server on, defaults to 8001
                            [1<=x<=65535]
  --title TEXT              Title for metadata
  --license TEXT            License label for metadata
  --license_url TEXT        License URL for metadata
  --source TEXT             Source label for metadata
  --source_url TEXT         Source URL for metadata
  --about TEXT              About label for metadata
  --about_url TEXT          About URL for metadata
  --help                    Show this message and exit.

典型用法（目标环境需具备与该制品匹配的运行能力，属于可选分发手段）：

datasette package sales.db inventory.db \
  -m metadata.json \
  --install datasette-json-html \
  --title "销售数据探索平台" \
  -t my-registry/datasette-sales:0.65.5

要点：-m 打元数据、--install 追加插件、--title/--license/--source 系列选项直接生成元数据字段、-t 指定制品标签。

八、publish：一键发布到托管平台

publish 把库文件连同 Datasette 运行体直接发布到云托管。datasette publish --help 实测输出：

Usage: datasette publish [OPTIONS] COMMAND [ARGS]...

  Publish specified SQLite database files to the internet along with a
  Datasette-powered interface and API

Options:
  --help  Show this message and exit.

Commands:
  cloudrun  Publish databases to Datasette running on Cloud Run
  heroku    Publish databases to Datasette running on Heroku

⚠️ 注意（版本差异）：0.65.5 内置的发布目标只有 cloudrun 与 heroku 两个；早期版本支持的 Vercel、Fly.io 已拆分为独立插件（datasette-publish-vercel、datasette-publish-fly），需要先用 datasette install 装上才会出现在子命令列表里。以你本机 datasette publish --help 的实际输出为准。

典型用法：

datasette publish cloudrun sales.db --service datasette-sales

执行后按提示完成云平台认证与项目选择即可；该路径依赖对应云平台的 CLI 与账号，本文不展开实测。

九、全局选项：--version 与 --help-settings

版本查询：

datasette --version

datasette, version 0.65.5

全部运行时参数及默认值速查（配 --setting 使用）：

datasette --help-settings

实测输出（节选，完整 20 项逐项详解见《Datasette 0.65.5 配置参数详解》）：

Settings:
  default_page_size            Default page size for the table view
                               (default=100)
  max_returned_rows            Maximum rows that can be returned from a table
                               or custom query (default=1000)
  num_sql_threads              Number of threads in the thread pool for
                               executing SQLite queries (default=3)
  sql_time_limit_ms            Time limit for a SQL query in milliseconds
                               (default=1000)
  ...

实例运行环境详情（Python/SQLite/uvicorn 版本与编译选项）不在 CLI 里，而是访问运行中实例的 /-/versions.json 端点：

curl -s http://127.0.0.1:8001/-/versions.json

实测回显（节选）：

{"python": {"version": "3.10.12", "full": "3.10.12 (main, Aug 31 2026, 10:18:17) [GCC 11.4.0]"}, "datasette": {"version": "0.65.5"}, "asgi": "3.0", "uvicorn": "0.54.0", "sqlite": {"version": "3.37.2", "fts_versions": ["FTS5", "FTS4", "FTS3"], ...}}

十、注意事项

  1. 改插件必重启：install/uninstall 只改环境，运行中的实例要重启才加载/卸载插件。
  2. --config 已废弃：老教程里的 --config default_page_size:50 在 0.65.5 上被标记 Deprecated，统一改 --setting default_page_size 50。
  3. --host 0.0.0.0 前三思权限：默认配置下任何人都可执行只读 SQL 并下载库文件，对外发布先收紧权限（见《Datasette 0.65.5 配置参数详解》第七节）。
  4. 不可变模式别挂错库：-i 适合发布后不再变的库；会写的库用不可变模式会导致行数缓存失真。
  5. pipx 与 venv 形态插件不共享：datasette install 装进「当前命令所属环境」，给 systemd 实例装插件要用该实例的 venv 路径（如 /opt/datasette/venv/bin/datasette install ...）。

十一、常见问题（FAQ）

Q1：datasette publish 怎么没有 vercel 子命令？ 0.65.x 起 Vercel/Fly.io 发布能力拆成插件。执行 datasette install datasette-publish-vercel 后再看 datasette publish --help（见第八节）。

Q2：插件装了但页面没变化？ 三步排查：datasette plugins 确认在列表里 → 看 hooks 是否包含你期望的能力 → 重启运行实例。

Q3：怎么在脚本里验证 Datasette 起没起好？ 用 serve --get /<库>/<表>.json：进程启动、请求、打印、退出一气呵成，退出码与输出可直接断言（见 4.3）。

Q4：datasette serve 报 Address already in use？ 默认端口 8001 被占。ss -ltnp | grep 8001 找占用进程，或 -p 0 让系统自动分配空闲端口（分配结果看启动日志里的 Uvicorn 行）。

Q5：datasette inspect 的 hash 有什么用？ 内容级哈希：库文件任何变化都会改变它。发布流水线里可用它做缓存键或变更检测，配合 --inspect-file 让不可变实例秒级启动。

十二、参考链接