快速开始

欢迎使用 Sleet ORM！本指南将帮助您在几分钟内快速上手 Sleet。

什么是 Sleet ORM？

Sleet 将 Drizzle ORM 的 Schema 即代码 理念带入 FiveM 的 Lua 脚本环境。告别裸 SQL 字符串，用 Lua 定义表结构，让 Sleet 生成干净的参数化查询。

核心特性

• Schema 即代码 — 在 Lua 里定义表结构，无需 SQL 字符串
• 链式查询构建器 — SELECT / INSERT / UPDATE / DELETE 全部支持点号链式调用
• 完整类型推断 — 运行 sleet generate 后，LuaLS 无需任何手写 ---@type 即可推断 XxxRecord[]
• 列注释 — .comment('描述') 同步到 IDE hover 提示和 SQL COMMENT 子句
• 安全 — 所有值使用 ? 参数占位符，彻底防止 SQL 注入
• 透明 — 每个查询都有 .toSQL() 调试方法
• 原始 SQL 转义口 — sl.sql() 用于 COUNT(*) 等聚合表达式和原子更新
• 零运行时依赖 — 仅需 oxmysql

前置要求

• FiveM 服务器
• oxmysql 资源
• Lua 和 SQL 基础知识

安装

1. 下载 Sleet

git clone https://github.com/SleetCo/sleet-orm [sleet]/sleet

2. 配置 server.cfg

ensure oxmysql
ensure your_sleet_user_resource

3. 你的资源 fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

server_scripts {
    '@oxmysql/lib/MySQL.lua',
    '@sleet/sleet.lua',    -- 注入全局 Sleet + 安装 package/require shim
    'server/main.lua',     -- 在脚本内用 require 'server.schema' 加载 schema
}

你的第一个 Schema

创建一个 schema 文件来定义数据库结构：

-- server/schema.lua
local sl = Sleet  -- @sleet/sleet.lua 注入的全局变量

local players = sl.table('players', {
    id         = sl.serial().primaryKey().comment('玩家自增ID'),
    identifier = sl.varchar(64).notNull().unique().comment('Steam / Discord 标识符'),
    name       = sl.varchar(255).notNull().comment('玩家名称'),
    money      = sl.int().default(500).comment('现金'),
    bank       = sl.int().default(2500).comment('银行余额'),
    is_admin   = sl.boolean().default(false).comment('管理员标志'),
    metadata   = sl.json().comment('扩展数据'),
    last_seen  = sl.timestamp().defaultNow().comment('最后在线时间'),
})

-- return 后可在其他脚本通过 require 'server.schema' 获取
return { players = players }

你的第一个查询

现在你可以使用 schema 进行数据库操作：

-- server/main.lua
local sl = Sleet
local s  = require 'server.schema'
local db = sl.connect()

-- SELECT — 运行 `sleet generate` 后 LuaLS 自动推断 PlayersRecord[]
local rows = db.select()
    .from(s.players)
    .where(sl.eq(s.players.identifier, identifier))
    .limit(1)
    .execute()

local player = rows[1]  -- player: PlayersRecord ✓

-- INSERT — 返回 insertId
local newId = db.insert(s.players)
    .values({ identifier = 'steam:xxx', name = GetPlayerName(source) })
    .execute()

-- UPDATE — 返回受影响行数
db.update(s.players)
    .set({ money = sl.sql('`money` + 500') })
    .where(sl.eq(s.players.id, player.id))
    .execute()

-- DELETE
db.delete(s.players)
    .where(sl.eq(s.players.id, newId))
    .execute()

启用类型推断

要获得完整的类型推断支持：

1. 安装 CLI 工具 (参见 CLI 文档)
2. 生成类型：

   sleet generate server/schema.lua
   # → .sleet/types.lua

3. 配置 LuaLS 包含生成的类型文件

完成设置后，你将获得完整的类型安全和智能提示支持！

接下来做什么？

• 安装指南 - 详细安装说明
• 基础用法 - 学习核心概念
• API 参考 - 完整 API 文档
• 示例 - 实际应用示例

需要帮助？

• 查看我们的 示例 了解实际用例
• 在 GitHub 上加入社区讨论
• 在我们的 GitHub 仓库 上报告问题
• 加入 QQ 群 914053352 获取中文技术支持