Hasura 常用命令与工具详解

目标：详解 Hasura 命令行工具链的全套用法——hasura CLI 的 init/metadata/migrate/seed/console/plugins/actions/scripts/completion 子命令与引擎 graphql-engine serve 启动参数，以及 Metadata API 的 curl 直调方法，所有命令与回显均来自 v2.51.1 实测环境。已在 Ubuntu 22.04.5（CLI 2.51.1 + 引擎 v2.51.1）实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
hasura CLI：v2.51.1（cli-hasura-linux-amd64，29,743,520 字节，来自 GitHub Releases cli/v2.51.1 标签）
引擎：Hasura GraphQL Engine v2.51.1（部署于同网段另一台服务器，http://hasura-2.51.1-engine-2404:8080）
CLI 工作目录：/root/hasura-project（hasura init 创建的 v3 结构项目）
管理密钥：q1w2e3r4（示例值）
部署方式参考：《Ubuntu 22.04 安装 Hasura GraphQL Engine 指南》；配置参数见《Hasura 配置参数详解》

二、工具概览

Hasura 的日常操作由三件工具分工完成，先建立全局认识再逐个详解：

工具	形态	职责	典型入口
`hasura` CLI	单文件二进制（约 29.7 MB）	项目化管理：元数据导出/应用、数据库迁移、种子数据、本地 Console	`hasura init` 后按项目工作
`graphql-engine serve`	引擎二进制	启动服务进程，参数即配置（与环境变量等价）	systemd `ExecStart` / 手工运行
Metadata API	HTTP JSON API（`/v1/metadata`、`/v1/query`）	绕过 CLI 直接读写元数据，CI/CD 与自动化集成	`curl`

CLI 与引擎的版本对应关系：CLI 发布标签为 cli/v2.51.1（与引擎 v2.51.1 同仓库同节奏发版；历史独立仓库 hasura/cli 已不再出 Release）。安装方法见安装指南方案 A 第 4.3 节，下载后放 /usr/local/bin/hasura 赋执行权限即可。版本确认（实测回显）：

hasura version --skip-update-check 2>&1 | grep -E 'version'

{"level":"info","msg":"hasura cli is up to date","time":"2026-10-22T11:54:03Z","version":"2.51.1"}
{"level":"info","msg":"hasura cli","time":"2026-10-22T11:54:03Z","version":"v2.51.1"}

CLI 顶层命令全景（hasura --help 实测）：

Available Commands:
  actions     Manage Hasura Actions
  completion  Generate auto-completion code
  console     Open the Console to manage the database and try out APIs
  deploy      (PREVIEW) Utility command to apply Hasura Metadata & database migrations to graphql-engine
  help        Help about any command
  init        Initialize a new Hasura GraphQL Engine project
  metadata    Manage Hasura GraphQL Engine Metadata saved in the database
  migrate     Manage migrations on the database
  plugins     Manage plugins for the CLI
  scripts     Execute helper scripts to manage Hasura Projects
  seed        Manage seed data
  update-cli  Update the CLI to latest or a specific version
  version     Print the CLI version

Flags:
      --envfile string      .env filename to load ENV vars from (default ".env")
  -h, --help                help for hasura
      --log-level string    log level (DEBUG, INFO, WARN, ERROR, FATAL) (default "INFO")
      --no-color            do not colorize output (default: false)
      --project string      directory where commands are executed (default: current dir)
      --skip-update-check   skip automatic update check on command execution

全局参数说明：--project 指定项目目录（默认当前目录）；--skip-update-check 跳过启动时的版本检查（内网环境建议加上，减少联网等待）；--log-level 调 CLI 自身日志；--envfile 加载 .env 文件。

三、前置条件

已安装 hasura CLI（/usr/local/bin/hasura，可执行）；
引擎已部署且 /healthz 可达（本篇用 http://hasura-2.51.1-engine-2404:8080）；
具备管理密钥；引擎未设置密钥时 CLI 命令需省略 --admin-secret；
本地无特殊依赖（CLI 是自包含二进制；唯一例外是 hasura seed create 需要 $EDITOR 编辑器，见 6.3 实测）。

四、项目初始化：hasura init

init 创建 CLI 项目目录（config v3 结构），一次性建好元数据、迁移、种子三类工作区，并自动导出当前引擎元数据。实测：

hasura init hasura-project --endpoint http://hasura-2.51.1-engine-2404:8080 --admin-secret q1w2e3r4 --skip-update-check

{"level":"info","msg":"Exporting metadata...","time":"2026-10-22T11:54:24Z"}
{"level":"info","msg":"Metadata exported","time":"2026-10-22T11:54:25Z"}
{"level":"info","msg":"Creating migrations for source: default","time":"2026-10-22T11:54:25Z"}
{"level":"info","msg":"Created Migrations","time":"2026-10-22T11:54:25Z"}
{"level":"info","msg":"migrations applied","time":"2026-10-22T11:54:25Z"}
{"level":"info","msg":"directory created. execute the following commands to continue:\n\n  cd /root/hasura-project\n  hasura console\n\nFor a console-free metadata and migration workflow, see AGENTS.md.\n","time":"2026-10-22T11:54:25Z"}

生成的目录结构（实测 find 节选）：

/root/hasura-project
├── AGENTS.md
├── config.yaml
├── metadata
│   ├── actions.graphql
│   ├── actions.yaml
│   ├── allow_list.yaml
│   ├── api_limits.yaml
│   ├── backend_configs.yaml
│   ├── cron_triggers.yaml
│   ├── databases
│   │   ├── databases.yaml
│   │   └── default
│   │       ├── tables
│   │       │   ├── public_products.yaml
│   │       │   └── tables.yaml
│   ├── graphql_schema_introspection.yaml
│   ├── inherited_roles.yaml
│   └── metrics_config.yaml
├── migrations
└── seeds

config.yaml 内容（实测原样）：

endpoint: http://hasura-2.51.1-engine-2404:8080
admin_secret: q1w2e3r4
version: 3
metadata_directory: metadata
actions:
  kind: synchronous
  handler_webhook_baseurl: http://localhost:3000

要点：version: 3 即 config v3 结构（多源元数据 + 每库迁移/种子子目录）；endpoint/admin_secret 可被命令行参数覆盖；AGENTS.md 是 v2.51.1 起新增的无 Console 工作流说明文件。hasura scripts update-project-v3 可把 v1/v2 老项目升级为该结构（hasura scripts --help 实测列出 update-project-v2/update-project-v3 两个子命令）。

五、元数据管理：hasura metadata

元数据（Metadata）是引擎的"配置大脑"：跟踪了哪些表、权限规则、事件触发器、远程 schema 都在里面。CLI 把它物化为 metadata/ 下的 YAML 文件，实现版本化。子命令清单（hasura metadata --help 实测）：

Available Commands:
  apply              Apply Hasura Metadata on a database
  apply-data-sources Apply only the data sources (connection configuration) from the project metadata
  clear              Clear Hasura GraphQL Engine Metadata on the database
  codemod            Run codemods on Hasura Metadata
  diff               (PREVIEW) Show a highlighted diff of the Hasura Metadata
  export             Export Hasura GraphQL Engine Metadata from the database
  inconsistency      Manage inconsistent objects in the Hasura Metadata
  reload             Reload Hasura GraphQL Engine schema to pick up changes in any underlying data sources

以下在 /root/hasura-project 内执行。

5.1 export / clear / apply 全回路

export（引擎 → 本地 YAML）：hasura metadata export --skip-update-check，实测输出 Exporting metadata... → Metadata exported。导出后 metadata/databases/default/tables/public_products.yaml 即表跟踪定义。

clear（清空引擎元数据）：实测输出 Clearing metadata... → Metadata cleared。清空后引擎 schema 立即缩水——实测查询立刻找不到表：

curl -s -X POST http://hasura-2.51.1-engine-2404:8080/v1/graphql -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"query":"{ products { id } }"}'

{"errors":[{"message":"field 'products' not found in type: 'query_root'","extensions":{"path":"$.selectionSet.products","code":"va

apply（本地 YAML → 引擎）：实测输出 Applying metadata... → Metadata applied。应用后同一查询恢复返回数据（实测 {"data":{"products":[{"id":1}, ...]}}）。这一"export → clear → apply"回路是元数据灾备演练的标准动作：任何时候元数据丢失，只要有 export 的 YAML 即可完整恢复。

5.2 reload 与 inconsistency

reload：底层库表结构被外部（如手工 DDL）变更后，让引擎重新拉取源 schema：hasura metadata reload。等价的 API 直调（实测回显）：

curl -s -X POST http://hasura-2.51.1-engine-2404:8080/v1/metadata -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"type":"reload_metadata","args":{"reload_remote_schemas":true,"reload_sources":true}}'

{"is_consistent":true,"message":"success"}

inconsistency：元数据一致性检查与修复（实测回显）：

hasura metadata inconsistency status --skip-update-check
hasura metadata inconsistency drop --skip-update-check

{"level":"info","msg":"metadata is consistent","time":"2026-10-22T12:10:06Z"}
{"level":"info","msg":"Dropping inconsistent metadata...","time":"2026-10-22T12:10:08Z"}
{"level":"info","msg":"all inconsistent objects removed from metadata","time":"2026-10-22T12:10:08Z"}

status 报告一致性状态；出现不一致对象（如引用了已删除的表）时 drop 移除它们让引擎恢复可用，再用 metadata export/apply 补回正确版本。

六、数据库迁移与种子：hasura migrate / seed

migrate 管理数据库 schema 的版本化 SQL（建表、改列等 DDL），与元数据配合形成完整可重放的部署单元；seed 是初始化数据。

6.1 migrate status

查看每个迁移的本地与数据库状态（实测回显）：

hasura migrate status --database-name default --skip-update-check

{"level":"info","msg":"Fetching migration status...","time":"2026-10-22T11:55:20Z"}

Database: default
VERSION        NAME           SOURCE STATUS  DATABASE STATUS
1792670065058  init           Present        Present
1792670107457  init_products  Present        Present

⚠️ 注意：--database-name 是必填参数，缺省会直接报错（实测：level=fatal msg="--database-name flag is required"），这是 v2 CLI 的一个易踩点。

6.2 migrate create 与 apply

从当前数据库状态反向生成迁移文件（把线上 schema 固化为版本）：

hasura migrate create init_products --from-server --database-name default --skip-update-check

{"level":"info","msg":"Creating migration files...","time":"2026-10-22T11:55:07Z"}
{"level":"info","msg":"Created Migrations","time":"2026-10-22T11:55:07Z"}
{"level":"info","msg":"migrations applied","time":"2026-10-22T11:55:07Z"}
{"level":"info","msg":"Migrations files created","name":"init_products","time":"2026-10-22T11:55:07Z","version":1792670107457}

生成 migrations/default/1792670107457_init_products/ 目录（版本号是毫秒时间戳），内含 up.sql/down.sql（本例 from-server 只生成 up.sql）。正向写法是手工编写 SQL 后 hasura migrate apply --database-name default 应用到目标库；migrate squash（PREVIEW）可把多个迁移合并，migrate delete 清除迁移记录。

6.3 seed create 与 apply

坑实录：hasura seed create products_seed --database-name default 不带 SQL 文件参数时会打开 $EDITOR 让你编辑——容器/精简系统常无 vi，实测直接报错：

time="2026-10-22T11:55:46Z" level=fatal msg="cannot find default editor from env: exec: \"vi\": executable file not found in $PATH"

解决：按 CLI 约定手工放置种子文件到 seeds/<database>/（文件名 时间戳_名称.sql），内容实测：

INSERT INTO products (name, price) VALUES ('Dock', 399.00);

应用并验证（实测回显）：

hasura seed apply --database-name default --skip-update-check
curl -s -X POST http://hasura-2.51.1-engine-2404:8080/v1/graphql -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"query":"{ products(order_by:{id:desc}, limit:1) { id name price } }"}'

{"level":"info","msg":"Applying seeds...","time":"2026-10-22T11:56:26Z"}
{"level":"info","msg":"Seeds planted","time":"2026-10-22T11:56:26Z"}
{"data":{"products":[{"id":4,"name":"Dock","price":399.00}]}}

种子会重复插入（无幂等保护），只用于新环境初始化数据。

七、本地 Console：hasura console

console 启动本地 Web 控制台，可视化编辑元数据并代理迁移/元数据 API。实测启动：

cd /root/hasura-project && hasura console --skip-update-check

实测日志（无图形环境的典型输出）：

{"level":"info","msg":"Opening console using default browser...","time":"2026-10-22T11:56:44Z"}
{"error":"exec: \"xdg-open\": executable file not found in $PATH","level":"warning","msg":"Error opening browser, try to open the url manually?","time":"2026-10-22T11:56:44Z"}
{"level":"info","msg":"console running at: http://localhost:9695/","time":"2026-10-22T11:56:44Z"}

要点解读：Console UI 固定在 9695（--console-port 默认 9695），迁移 API 代理在 9693（--api-port），引擎数据 API 仍是 8080——三个端口各司其职；无浏览器环境（服务器）会警告 xdg-open 缺失，正常现象，用本地电脑端口转发（ssh -L 9695:localhost:9695）访问。实测 9695 返回 Console 页面（HTTP 200，页面 window.__env 内含 cliVersion: "v2.51.1" 与数据 API 地址）。常用参数（hasura console --help 实测节选）：

Flags:
      --address string                 address to serve console and migration API from (default "localhost")
      --admin-secret string            admin secret for Hasura GraphQL Engine (env "HASURA_GRAPHQL_ADMIN_SECRET")
      --api-port string                port for serving migrate api (default "9693")
      --console-port string            port for serving console (default "9695")
      --no-browser                     do not open the browser automatically

服务端托管的 Console（引擎 8080 /console）由 HASURA_GRAPHQL_ENABLE_CONSOLE 控制，与本命令无关（见《Hasura 配置参数详解》第十章）。

八、插件、Actions 与补全

plugins 管理 CLI 插件（连接器扩展等，实测 hasura plugins list 节选）：

NAME             DESCRIPTION                                      VERSION         INSTALLED
cli-ext          Hasura CLI extension                             v2.0.0-alpha.4  no
clickhouse       CLI plugin for Hasura ndc-clickhouse             v1.1.2          no
ndc-postgres     CLI plugin for Hasura ndc-postgres               v2.1.1          no
ndc-mongodb      CLI plugin for Hasura ndc-mongodb                v1.8.4          no
pro              CLI plugin for Hasura Pro                        v2.31.0         no
upgrade-from-v2  V2 Upgrade Plugin for Hasura V3                  20240320        no

安装用 hasura plugins install <名称>，卸载 uninstall。v2 纯 Postgres 工作流无需任何插件；接 MongoDB/ClickHouse 等其他数据源时安装对应 ndc-* 插件。

actions 管理 Hasura Actions（把外部 REST 端点封装进 GraphQL schema），实测子命令：create（交互式定义 Action）、codegen（生成脚手架代码）、use-codegen（切换代码生成配置）。

completion 生成 shell 补全：hasura completion bash > /etc/bash_completion.d/hasura 后重开 shell 生效（实测输出为标准 bash-completion 脚本）。

update-cli / deploy：update-cli 自升级 CLI（支持 --version 固定版本）；deploy（PREVIEW）一条命令应用元数据 + 迁移，适配 CI/CD。

九、引擎启动参数：graphql-engine serve

引擎二进制除 serve 外还有 version 等子命令，顶层帮助（实测节选）：

Usage: graphql-engine [--retries NO OF RETRIES]
                      [--database-url <DATABASE-URL> | [--host <HOST>]
                        [-p|--port <PORT>] [-u|--user <USER>]
                        [--password <PASSWORD>] [-d|--dbname <DBNAME>]
                        [-o|--pg-connection-options <DATABASE-OPTIONS>]]
                      [--metadata-database-url <METADATA-DATABASE-URL>] COMMAND

serve 的完整参数即全部配置项（graphql-engine serve --help 实测 770 行），与 HASURA_GRAPHQL_* 环境变量一一对应（映射表见《Hasura 配置参数详解》第四章）。手工前台启动示例（元数据库与数据源均以参数指定，等价于环境变量写法）：

graphql-engine serve --database-url 'postgres://postgres:q1w2e3r4@127.0.0.1:5432/hasuradb' --metadata-database-url 'postgres://postgres:q1w2e3r4@127.0.0.1:5432/hasura_metadata' --admin-secret q1w2e3r4 --server-port 8080

生产上推荐 systemd + 环境变量文件承载（见安装指南 4.5 节），命令行参数留给临时验证与容器入口脚本。

十、Metadata API 的 curl 直调

CLI 的每个 metadata 动作背后都是引擎的 HTTP API，自动化集成可直接调 API。认证统一用请求头 X-Hasura-Admin-Secret: q1w2e3r4。

新版端点 /v1/metadata（v2.51.1 实测）：类型作 JSON 字段传入。跟踪表：

curl -s -X POST http://127.0.0.1:8080/v1/metadata -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"type":"pg_track_table","args":{"source":"default","table":{"schema":"public","name":"products"}}}'

{"message":"success"}

导出元数据（返回完整 JSON 元数据，节选）：

curl -s -X POST http://127.0.0.1:8080/v1/metadata -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"type":"export_metadata","args":{}}'

{"version":3,"sources":[{"name":"default","kind":"postgres","tables":[{"table":{"name":"products","schema":"public"}}],"configuration":{"connection_info":{"database_url":{"from_env":"HASURA_GRAPHQL_DATABASE_URL"},"isolat

替换元数据（replace_metadata，请求体为 export 结果整体放入 args，实测返回 {"message":"success"}）、重载（reload_metadata，实测返回 {"is_consistent":true,"message":"success"}）。

旧版端点 /v1/query 同样可用（{"type":"export_metadata","args":{}}），响应与新版一致；新项目建议统一 /v1/metadata。常用 type 速查（均实测可用）：export_metadata（导出）、replace_metadata（全量替换）、reload_metadata（重载）、pg_track_table / pg_untrack_table（表跟踪）、pg_create_insert_permission 等权限类、bulk（批量执行数组）。

验证 API 直调效果：跟踪成功后立即查询（实测回显）：

curl -s -X POST http://127.0.0.1:8080/v1/graphql -H 'Content-Type: application/json' -H 'X-Hasura-Admin-Secret: q1w2e3r4' -d '{"query":"{ products { id name price } }"}'

{"data":{"products":[{"id":1,"name":"Keyboard","price":199.00}, {"id":2,"name":"Mouse","price":89.50}, {"id":3,"name":"Monitor","price":1299.00}]}}

请求日志侧证（引擎 http-log 实测单行，user_vars.x-hasura-role 显示 admin）：

{"detail":{"http_info":{"method":"POST","status":200,"url":"/v1/graphql"},"operation":{"query_execution_time":7.97007e-4,"request_id":"9eaccf58-e2dd-483d-8e73-0437e852cd52","user_vars":{"x-hasura-role":"admin"}}},"level":"info","type":"http-log"}

十一、注意事项

CLI 与引擎版本配对：CLI 2.51.1 配引擎 v2.51.1 实测无兼容性问题；跨大版本（如老 CLI 对新引擎）可能报元数据版本不兼容，升级时二者同升。
--skip-update-check：CLI 每次执行默认联网检查更新（输出 Checking for update...），内网/批量脚本环境务必加该参数减少延迟。
项目目录约定：--project 或 cd 到项目根执行，否则 CLI 找不到 config.yaml 报错。
migrate/seed 都要 --database-name：多源项目里缺省会 fatal（6.1 实测）。
seed 重复执行会重复插数：种子无幂等标记，重放前清理目标表或改用迁移。
Console 三端口：本地 Console 9695 / 迁移代理 9693 / 引擎 8080，防火墙与转发按此放行。
API 错误是 200 + errors：脚本判断成败要看响应体 errors 字段而非 HTTP 状态码（access-denied 等错误实测状态码 200）。

十二、常见问题（FAQ）

Q1：hasura metadata apply 报连接被拒绝？ 核对 config.yaml 的 endpoint 与引擎实际地址端口；引擎未启动或防火墙拦截 8080 时即此错。用 curl <endpoint>/healthz 先行探测。

Q2：apply 后 GraphQL 仍找不到表？ 检查 metadata/databases/default/tables/tables.yaml 是否包含目标表条目；表被跟踪但无权限时对当前角色不可见（用 admin 角色请求验证）。

Q3：seed create 报 cannot find default editor？ 系统无 $EDITOR。安装编辑器（apt-get install -y vim-tiny）或直接按 6.3 的文件约定手工创建种子文件。

Q4：migrate status 报 --database-name flag is required？ v2 CLI 的必填参数，显式传 --database-name default（与元数据中的源名一致）。

Q5：console 打不开（9695 无响应）？ 确认命令仍在运行（前台进程被挂断即停）；服务器环境加 --address 0.0.0.0 并用 SSH 隧道访问；注意 9695（Console UI）与 9693（迁移 API）是两个端口。

Q6：plugins list 报网络错误？ 插件索引从 GitHub 拉取，内网环境需为 CLI 配置代理（export HTTPS_PROXY=... 后重试）。

Q7：CLI 提示 hasura cli is up to date 但想固定版本？ 下载对应 cli/vX.Y.Z 标签的二进制替换 /usr/local/bin/hasura；或用 hasura update-cli --version <版本>。

十三、参考链接

CLI 发布标签：https://github.com/hasura/graphql-engine/releases/tag/cli%2Fv2.51.1
官方 CLI 文档（v2）：https://hasura.io/docs/2.x/hasura-cli/hasura-cli-commands/
Metadata API 参考（v2）：https://hasura.io/docs/2.x/deployment/graphql-engine-apis/
站内关联：《Ubuntu 22.04 安装 Hasura GraphQL Engine 指南》、《Hasura 配置参数详解》、《Hasura v2.51.1 介绍与选型指南》