SpacetimeDB 数据库与模块全解析从模块发布到数据库管理的完整实战指南【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB模块Module与数据库Database是 SpacetimeDB 一切开发工作的基石模块是你用 TypeScript、C# 或 Rust 编写的代码数据库则是运行在 SpacetimeDB 主机上的模块实例。本篇指南围绕docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases.md展开系统讲解二者区别、模块的组成要素、支持的语言、数据库命名规则以及使用spacetimeCLI 和 Web 界面完成创建、更新、删除、SQL 查询、日志查看等全生命周期管理操作。读完你将掌握从零创建数据库模块、发布上线到日常运维的完整闭环并能结合本仓库源码理解每个 CLI 命令背后的参数解析与实现原理。模块与数据库代码与实例的区别理解Module模块与Database数据库的区别是使用 SpacetimeDB 最重要的一步模块是你编写的代码。它定义了数据库的schema表结构与业务逻辑reducers、procedures、views。模块会被编译并部署到 SpacetimeDB 上Rust 与 C# 模块编译为 WebAssemblyWASMTypeScript 模块运行在 V8 引擎上。数据库是模块的一个运行实例。它拥有模块的 schema 与逻辑同时包含真实存储的数据与活跃的客户端连接。同一份模块可以部署到多个数据库例如 testing、staging、production 三套独立环境每个数据库各自拥有独立的数据。当你更新模块代码并重新发布re-publish时SpacetimeDB 会更新该数据库的 schema 与逻辑已有的数据会被保留不过对于复杂的 schema 变更你可能需要谨慎处理迁移。关于迁移的细节可参阅 自动迁移 与 增量迁移。事务原子性是理解数据库运行的基础SpacetimeDB 中 reducer 的每次执行都是原子事务相关内容参见 Transactions and Atomicity。模块里有什么一个模块包含以下组成部分表Tables—— 定义数据结构与存储。ReducerReducer—— 以事务方式修改数据的服务端函数。过程Procedures—— 可以执行 HTTP 请求等外部操作并返回结果的函数。视图Views—— 对数据只读的计算查询。服务端逻辑即包含在这三类函数中reducer事务性状态变更、procedure具备外部能力的函数与 view只读查询。仓库中的 templates/basic-rs/spacetimedb/src/lib.rs 是一个完整的 Rust 模块样例直观展示了上述要素如何组合use spacetimedb::{ReducerContext, Table}; #[spacetimedb::table(accessor person, public)] pub struct Person { name: String, } #[spacetimedb::reducer(init)] pub fn init(_ctx: ReducerContext) { // Called when the module is initially published } #[spacetimedb::reducer(client_connected)] pub fn identity_connected(_ctx: ReducerContext) { // Called everytime a new client connects } #[spacetimedb::reducer(client_disconnected)] pub fn identity_disconnected(_ctx: ReducerContext) { // Called everytime a client disconnects } #[spacetimedb::reducer] pub fn add(ctx: ReducerContext, name: String) { ctx.db.person().insert(Person { name }); } #[spacetimedb::reducer] pub fn say_hello(ctx: ReducerContext) { for person in ctx.db.person().iter() { log::info!(Hello, {}!, person.name); } log::info!(Hello, World!); }可见#[spacetimedb::table]定义表结构与存取器#[spacetimedb::reducer]定义业务逻辑其中init、client_connected、client_disconnected属于生命周期 reducerLifecycle Reducers分别在模块发布时、客户端连接时与断开时被系统自动调用。其他语言TypeScript、C#的模块结构与其一一对应只是语法不同。支持的语言SpacetimeDB 模块支持以下三种服务端语言语言运行目标适用场景TypeScriptV8 引擎熟悉 JavaScript/Node.js 生态的开发者C#WebAssemblyWASM使用 Unity 或 .NET 的开发者RustWebAssemblyWASM对性能敏感的应用各语言的快速入门指南TypeScript 快速入门C# 快速入门Rust 快速入门Rust 模块 SDK 的 API 文档可在 docs.rs 上查阅spacetimedbcrate数据库命名规则发布模块时你需要给数据库起一个名字。数据库名称必须匹配正则表达式/^[a-z0-9](-[a-z0-9])*$/即只允许小写 ASCII 字母和数字用短横线-分隔。合法的命名示例my-game-serverchat-app-productiontest123该正则的约束在仓库 CLI 源码中得到了直接印证crates/cli/src/subcommands/publish.rs第 277 行的参数说明中写明了同样的规则Database names must match the regex/^[a-z0-9](-[a-z0-9])*$/且该文件中的validate_name_or_identity第 702 行与validate_name_and_parent第 714 行等函数会在发布前对名称合法性做校验测试用例也覆盖了合法名、带路径名如parent/child与非法名如proc/net/tcp等场景。此外每个数据库在创建时还会获得一个唯一的identity十六进制字符串身份标识。客户端既可以用名称连接也可以用 identity 连接。使用spacetimeCLI 管理数据库模块与数据库均通过spacetimeCLI 工具进行管理。下面逐项讲解最常用的管理命令并补充源码级参数细节。创建与更新数据库spacetime publish发布模块即可创建或更新数据库spacetime publish DATABASE_NAMEpublish的完整工作流在 spacetime publish 指南 中有详细说明其要点如下构建模块若尚未构建——spacetime publish会自动构建无需单独运行spacetime build创建新数据库指定名称或定位已有数据库上传并安装模块运行init生命周期 reducer若已定义开始接受客户端连接。发布成功后 CLI 会输出数据库的identity请妥善保存——后续的管理任务会用到它。向已有数据库重新发布时SpacetimeDB 会自动尝试迁移 schema、原子性地切换到新模块并保持活跃客户端连接不断开。若你的更新包含无法自动迁移的破坏性变更需要显式使用--break-clientsspacetime publish --break-clients DATABASE_NAME⚠️ 警告这会使尚未适配新 schema 的现有客户端连接中断。若要彻底重置数据库并删除所有数据spacetime publish DATABASE_NAME --delete-data⚠️ 警告这会永久删除数据库中的所有数据从源码看--delete-data对应的底层实现是confirm_and_clear函数crates/cli/src/subcommands/publish.rs它会在执行前打印 This will DESTROY the current module, and ALL corresponding data. 并要求用户确认。publish还支持以下实用参数均可在cli()定义中找到--organization NAME_OR_ID别名--org——将数据库创建在指定组织下组织的成员权限将作用于该数据库注意组织只能在创建数据库时指定更新时不可修改--yes[values]-y——跳过确认提示可取值all, remote, migrate, break-clients, skip-login, delete-data多个值用逗号分隔如--yesmigrate,break-clients或重复传参注意值必须用附加--yes my-db会把my-db当作数据库名--env ENV——配置文件分层使用的环境名如dev、staging--no-config——忽略spacetime.json配置--native-aot——对 C# 模块使用 NativeAOT-LLVM 编译实验性支持 Windows以及装有 .NET 10 的 Linux。关于发布选项的完整清单见 CLI 参考手册中的 spacetime publish 一节。删除数据库spacetime delete永久删除数据库及其全部数据spacetime delete DATABASE_NAME命令会提示你确认删除在脚本中使用--yes可跳过确认。:::warning 删除数据库是永久性操作无法撤销所有数据都会丢失。 :::更多选项见 CLI 参考手册中的 spacetime delete 一节。使用 SQL 查询spacetime sql可以直接对数据库执行 SQL 查询spacetime sql DATABASE_NAME SELECT * FROM user所有者权限Owner Privileges以数据库所有者身份执行 SQL 时会绕过表的可见性限制也就是说你可以查询普通客户端无法访问的私有表。若要模拟无特权客户端的视角使用--anonymous标志spacetime sql --anonymous DATABASE_NAME SELECT * FROM user这会以匿名客户端身份执行查询尊重表的可见性规则。从 crates/cli/src/subcommands/sql.rs 的 CLI 定义看spacetime sql还支持--interactive——进入 SQL 交互式命令提示符--format FORMAT——输出格式支持text别名default/txt默认值与json--yes、--no-config——跳过确认 / 忽略spacetime.json配置。更多 SQL 选项见 CLI 参考手册中的 spacetime sql 一节。完整的 SQL 语法能力可参考 SQL Reference。查看日志spacetime logs查看数据库日志spacetime logs DATABASE_NAME实时跟随日志类似tail -fspacetime logs --follow DATABASE_NAME该命令会保持连接打开持续显示新产生的日志条目按 CtrlC 停止跟随。限制输出行数只查看最后 N 行spacetime logs --num-lines 100 DATABASE_NAME从 crates/cli/src/subcommands/logs.rs 的 CLI 定义看spacetime logs还提供--format FORMAT——日志输出格式--level LEVEL——显示的最低日志级别--level-exact LEVEL——只显示精确匹配该级别的日志--server——指定承载数据库的服务器昵称、主机名或 URL。更多日志选项见 CLI 参考手册中的 spacetime logs 一节。在模块中合理使用log::info!等日志宏并配合--level过滤是调试与监控模块运行的关键手段相关实践参见 Logging 指南。列出数据库spacetime list查看与你的身份关联的所有数据库spacetime list该命令会显示数据库的名称、identity 与所在主机服务器host server。从源码 crates/cli/src/subcommands/list.rs 看它同样支持--server参数以指定从中列出数据库的服务器昵称、主机名或 URL。通过 Web 界面管理数据库你也可以通过 SpacetimeDB 的 Web 界面来管理数据库它提供了 CLI 许多操作的图形化入口更便于可视化与运维查看指标View metrics—— 监控数据库性能、连接数与资源使用浏览表Browse tables—— 查看表结构与数据查看日志View logs—— 访问带筛选与搜索的历史日志管理访问权限Manage access—— 控制数据库权限与团队访问监控查询Monitor queries—— 查看订阅查询与 reducer 调用。项目Projects与团队TeamsSpacetimeDB 支持将数据库组织为项目Projects并进行团队级访问管理你可以将相关的数据库分组到一起与团队成员共享访问权限在项目级别管理权限。学习路径入门如果你是 SpacetimeDB 新手推荐按以下顺序学习创建你的第一个数据库模块—— 用spacetime init或spacetime dev搭建模块项目构建与发布—— 编译并部署模块定义表—— 用表、列与索引组织数据编写 Reducer—— 编写修改数据库的事务性函数连接客户端—— 构建连接到数据库的客户端应用。其中spacetime dev是最快的起步方式它提供交互式引导项目名 → 项目路径 → 选择客户端类型React / 使用模板 / 纯服务端并自带热重载能力——保存模块代码后自动重新构建并重新发布也可用spacetime init --lang typescript|csharp|rust --project-path ./my-project my-project手动创建项目。仓库中的 templates 目录如basic-ts、basic-cs、basic-rs、chat-react-ts等正是spacetime dev可选的各类内置模板。核心概念掌握基础之后继续探索这些关键主题错误处理Error Handling—— 在 reducer 中优雅地处理错误生命周期 ReducerLifecycle Reducers—— 响应初始化、客户端连接等系统事件自动迁移Automatic Migrations—— 理解 schema 变更如何生效日志Logging—— 用日志调试与监控模块。高级特性进一步提升可深入研究这些高级能力过程Procedures—— 发起 HTTP 请求、与外部服务交互视图Views—— 创建可计算、可订阅的查询调度表Schedule Tables—— 在指定时间调度 reducer 运行增量迁移Incremental Migrations—— 处理复杂 schema 变更SQL 查询SQL Queries—— 用 SQL 查询数据库。部署上线准备上线时部署到 MainCloud—— 将数据库托管到 SpacetimeDB 托管服务自托管Self-Hosting—— 运行自己的 SpacetimeDB 实例仓库中的 crates/standalone 即自托管服务端实现可直接构建运行。下一步阅读 表Tables 来定义你的数据库 schema创建 Reducer 修改数据库状态理解 订阅Subscriptions 实现实时数据同步查阅 CLI 参考手册 了解全部可用命令。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考