Hasura GraphQL Engine CLI Migrations v2 镜像在 Docker 启动时自动应用迁移与元数据【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine导读本指南围绕 Hasura GraphQL Engine 官方发布的cli-migrations-v2Docker 镜像展开它解决了一个典型部署难题如何在不暴露迁移权限的前提下让数据库 schema 迁移migrations与 Hasura 元数据metadata随容器启动自动完成。读完本文你将掌握该镜像的工作原理、Dockerfile 与 Heroku 两种部署方式以及全部 7 个可调环境变量的含义与优先级从而把手工执行hasura migrate apply/hasura metadata apply从发布流程中彻底移除。镜像的设计思路临时服务器 安全重启cli-migrations-v2是 packaging 目录下与hasura/graphql-engine一同发布的一组镜像变体镜像标签格式为version.cli-migrations-v2另有latest.cli-migrations-v2。它并非一个独立程序而是在标准 graphql-engine 镜像之上叠加了一个自定义入口脚本 docker-entrypoint.sh把整个启动过程编排为三个阶段临时启动一个仅限本机访问的 graphql-engine 实例入口脚本先在容器内部启动一个只开放metadataAPI 的临时服务器监听于localhost默认端口 9691外部网络无法触达因此迁移/元数据 API 不会暴露给公网。执行迁移与元数据脚本借助内置的hasura-cli指向该临时实例依次执行hasura migrate apply与hasura metadata apply把migrations/与metadata/目录中的内容应用到数据库。关闭临时服务器并正常启动迁移完成后脚本杀掉临时进程exec $将控制权交给用户在CMD中定义的正式 graphql-engine 启动命令此时引擎以生产模式对外提供 GraphQL 服务不再包含迁移相关能力。这种临时开启、事后关闭的模式正是该镜像的安全根基迁移所需的权限只存在于容器生命周期的前几秒且绑定在回环地址上。基础用法在 Dockerfile 中继承镜像官方推荐的用法是在你自己的 Dockerfile 中以此为基底只保留运行命令FROM hasura/graphql-engine:version.cli-migrations-v2 CMD graphql-engine \ --database-url $DATABASE_URL \ serve \ --server-port $PORT \ --enable-consoleversion替换为你需要固定的引擎版本例如v2.42.0具体以 packaging/README.md 中声明的标签规范为准。CMD中的参数会被入口脚本原样透传脚本在完成迁移后会执行exec $将这条命令作为容器的主进程拉起。迁移与元数据目录可以通过两种方式进入镜像挂载卷如docker run -v ./migrations:/hasura-migrations或构建期拷入在FROM之后追加COPY migrations /hasura-migrations。基底镜像 Dockerfile 本身还做了两件与生产环境密切相关的事创建/.hasura目录并赋予组可写权限chgrp -R 0 /.hasura chmod -R gu /.hasura保证像 OpenShift 这类以随机非 root UID 运行容器的平台也能正常写入 CLI 缓存预设HASURA_GRAPHQL_SHOW_UPDATE_NOTIFICATIONfalse与HASURA_GRAPHQL_CLI_ENVIRONMENTserver-on-docker抑制 CLI 的更新提示并标记自身运行环境。本地使用目录约定与自动应用本地使用时把migrations/与metadata/目录准备好分别挂载到默认路径/hasura-migrations与/hasura-metadata再配合下文 Configuration 一节中的环境变量即可。入口脚本的行为是目录存在才执行、不存在则跳过例如只有migrations/而没有任何 metadata 时脚本会打印directory /hasura-metadata does not exist, skipping metadata后继续。仓库自带的测试夹具展示了标准的目录结构可直接作为本地实践的参照迁移文件packaging/cli-migrations/v2/test/migrations/1586823136625_create_table_public_test/up.sql 演示了带时间戳前缀的迁移目录 up.sql/down.sql这一 Hasura 迁移约定目录名1586823136625_create_table_public_test即时间戳_描述格式元数据文件packaging/cli-migrations/v2/test/metadata/ 内含tables.yaml、actions.yaml、cron_triggers.yaml、allow_list.yaml等 Hasura 元数据 v2 格式的清单。Heroku 部署一条命令完成建库与迁移对于 Heroku 这类 PaaS 平台可以利用其 Docker manifest 能力让应用创建、数据库开通、迁移执行全流程自动化全程无需人工干预。在仓库根目录编写heroku.ymlsetup: addons: - plan: heroku-postgresql as: DATABASE config: HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VAR: DATABASE_URL build: docker: web: Dockerfile关键点说明setup.addons声明依赖heroku-postgresql附加组件并以DATABASE别名注入连接信息setup.config中HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VAR: DATABASE_URL告诉入口脚本从名为DATABASE_URL的环境变量里读取迁移目标数据库地址该变量的值由 Heroku 在附加组件开通后自动注入指向刚创建的 PostgreSQL 实例build.docker.web指定用于构建 web 服务的 Dockerfile。开通Provision使用--manifest参数创建应用Heroku 会按照heroku.yml的setup段自动附加数据库并写入环境变量heroku create heroku-migration-tester --manifest部署Deploy将代码推送到 Heroku 远程仓库即可触发构建与部署export HEROKU_GIT_REMOTEhttps://git.heroku.com/heroku-migration-tester.git git init git add . git commit -m first commit git remote add heroku HEROKU_GIT_REMOTE git push heroku master推送完成后容器入口脚本会在首次启动时自动完成 schema 迁移与元数据应用应用即处于可用状态。配置全部环境变量详解下表汇总了该镜像支持的所有环境变量随后逐项展开说明环境变量默认值必填性作用HASURA_GRAPHQL_MIGRATIONS_DIR/hasura-migrations可选迁移文件目录HASURA_GRAPHQL_METADATA_DIR/hasura-metadata可选元数据文件目录HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VARnull三者至少其一指向存有数据库 URL 的环境变量名HASURA_GRAPHQL_MIGRATIONS_DATABASE_URLnull三者至少其一迁移专用数据库 URLHASURA_GRAPHQL_DATABASE_URLnull三者至少其一常规数据库 URL可兼作迁移目标HASURA_GRAPHQL_MIGRATIONS_SERVER_PORT9691可选临时服务器监听端口HASURA_GRAPHQL_MIGRATIONS_SERVER_TIMEOUT30s可选等待服务器就绪的超时阈值Migrations Directory可选HASURA_GRAPHQL_MIGRATIONS_DIR默认/hasura-migrations迁移目录的路径。迁移文件要么挂载进容器要么在构建镜像时内置只有存放在非默认位置时才需要显式配置。Metadata Directory可选HASURA_GRAPHQL_METADATA_DIR默认/hasura-metadata元数据目录的路径用法与迁移目录一致。Database三者必须至少配置其一数据库相关变量按求值顺序排列入口脚本从上到下逐项检查命中第一项后即停止因此配置顺序决定了实际生效者HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VAR默认null一个指向环境变量名的指针。例如设置HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VARDATABASE_URL脚本会读取名为DATABASE_URL的环境变量的值作为迁移数据库 URL。Heroku 部署正是利用它间接引用平台注入的连接串。HASURA_GRAPHQL_MIGRATIONS_DATABASE_URL默认null直接指定迁移专用的数据库 URL允许它与提供 GraphQL 查询服务的数据库不同。典型场景是主库 只读从库架构只对主库执行迁移从库通过复制保持同步查询流量打到从库。格式形如HASURA_GRAPHQL_MIGRATIONS_DATABASE_URLpostgres://username:passwordhost:port/database_nameHASURA_GRAPHQL_DATABASE_URL默认null常规数据库 URL。当上面两个变量都未设置时脚本回退使用它作为迁移目标。格式同上。入口脚本 docker-entrypoint.sh 中对应的解析逻辑为先判断HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VAR是否设置若设置则通过printenv取出其指向的值否则若HASURA_GRAPHQL_MIGRATIONS_DATABASE_URL未被显式设置则回退为HASURA_GRAPHQL_DATABASE_URL。注意无论走哪条分支脚本最终都会把解析结果同时作为临时服务器的HASURA_GRAPHQL_DATABASE_URL传入。GraphQL Server可选以下两个变量控制迁移期间临时服务器的行为HASURA_GRAPHQL_MIGRATIONS_SERVER_PORT默认9691临时 graphql-engine 实例的监听端口。建议不要使用可能对外暴露的端口如 80/443默认值一般无需改动。若容器网络环境中 9691 被占用可在此覆盖入口脚本注释也提示了这一点。HASURA_GRAPHQL_MIGRATIONS_SERVER_TIMEOUT默认30s等待服务器就绪的超时阈值。入口脚本的wait_for_port函数会以 1 秒为间隔探测端口连通性nc -z localhost $PORT连续探测失败达到该秒数后直接退出并报错提示调大此变量。入口脚本源码级剖析迁移究竟如何发生理解 docker-entrypoint.sh 的执行顺序有助于排查镜像没有按预期应用迁移一类问题。完整流程如下解析迁移数据库按上一节的优先级链解析出HASURA_GRAPHQL_MIGRATIONS_DATABASE_URL。确定端口与超时未显式设置时分别回退到9691与30。拉起临时服务器关键命令行参数值得注意HASURA_GRAPHQL_DATABASE_URL$HASURA_GRAPHQL_MIGRATIONS_DATABASE_URL \ HASURA_GRAPHQL_DISABLE_EVENT_PROCESSINGtrue \ $HGE_BINARY serve --enabled-apismetadata \ --server-port${HASURA_GRAPHQL_MIGRATIONS_SERVER_PORT} --enabled-apismetadata让临时实例只开放 metadata API其余 GraphQL/迁移 API 全部关闭最小化暴露面HASURA_GRAPHQL_DISABLE_EVENT_PROCESSINGtrue在应用迁移期间暂停事件处理事件触发器、cron 触发器、定时事件与异步 action 都不会被投递避免与迁移任务争抢数据库资源、防止在 schema 尚未稳定时发送事件与完全禁用 eventing 不同它保留了事件子系统因此源目录迁移仍会创建事件目录表这对在全新数据库上应用含事件触发器的元数据是必需的。等待端口就绪wait_for_port以 1 秒间隔用nc探测超时即退出。应用迁移若$HASURA_GRAPHQL_MIGRATIONS_DIR存在则将其内容复制到临时工程目录/tmp/hasura-project/migrations/生成指向临时实例的config.yamlversion: 2endpoint: http://localhost:port执行hasura-cli migrate apply。应用元数据若$HASURA_GRAPHQL_METADATA_DIR存在同样复制到临时工程目录的metadata/下写入带metadata_directory: metadata的config.yaml执行hasura-cli metadata apply。清理与接管kill $PID终止临时服务器最后exec $启动正式的 graphql-engine 主进程。脚本全程使用结构化的 JSON 日志输出timestamp/level/type/detailkind取值包括migrations-startup、migrations-apply、migrations-shutdown便于在容器日志中检索迁移各阶段的进展。测试与验证镜像行为如何被保障仓库为cli-migrations-v2镜像提供了完整的集成测试可作为理解其行为的参考packaging/cli-migrations/v2/test/test.sh 的验证流程为先启动 PostgreSQL 与目标镜像容器把migrations/、metadata/分别docker cp进容器的/hasura-migrations、/hasura-metadata待服务器就绪后通过export_metadata与查询hdb_catalog.schema_migrations两种方式断言迁移结果与 validation/metadata.json、validation/schema_migrations.json做 diffpackaging/cli-migrations/v2/test/docker-compose.yaml 展示了最小运行环境一个postgres:14数据库 待测镜像通过HASURA_GRAPHQL_DATABASE_URL直连test-upgrade-from-latest-release.sh 还覆盖了基于最新已发布镜像做升级的场景。这一测试链印证了镜像的两个核心事实入口脚本确实在正式服务启动前完成了迁移与元数据应用且这些操作对最终运行态是可观测、可校验的。使用建议与常见注意点目录未挂载不会报错迁移/元数据目录缺失时脚本仅打日志跳过因此部署时务必确认目录确实进入了镜像或卷否则会出现容器正常启动但 schema 未迁移的静默失败。临时端口避免冲突默认 9691 是回环端口一般安全但若容器网络特殊或与其他进程冲突通过HASURA_GRAPHQL_MIGRATIONS_SERVER_PORT调整同时确认HASURA_GRAPHQL_MIGRATIONS_SERVER_TIMEOUT足以覆盖冷启动时间。数据库选择按需隔离需要迁移与查询分离如主从架构时使用HASURA_GRAPHQL_MIGRATIONS_DATABASE_URL仅单库场景直接使用HASURA_GRAPHQL_DATABASE_URL即可在 PaaS 上则优先使用HASURA_GRAPHQL_MIGRATIONS_DATABASE_ENV_VAR间接引用平台注入的连接变量。与 v3 镜像的差异仓库同时提供cli-migrations-v3变体见 packaging/cli-migrations/v3/README.md其 Dockerfile 示例引入了--metadata-database-url参数面向带独立元数据数据库的部署模型。选择 v2 还是 v3 应取决于你使用的引擎版本与元数据数据库拓扑二者在入口脚本层面共享同一套临时服务器 CLI 应用的设计范式。【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考