版本：bleeding-edge 🩸

💾 Database

Database 实体为程序员提供了一种通过脚本轻松访问 SQL 数据库的方法。

提示

目前 nanos world 开箱即用支持 SQLite (3.50)、MySQL (8.1) 和 PostgreSQL (17.5)。

🎒 示例

Server/Index.lua
-- 创建一个 SQLite 连接，使用名为 'database_filename.db' 的本地文件
local sqlite_db = Database(DatabaseEngine.SQLite, "db=database_filename.db timeout=2")

-- 创建一个表
sqlite_db:Execute([[
	CREATE TABLE IF NOT EXISTS test (
		id INTEGER,
		name VARCHAR(100)
	)
]])

-- 在表中插入值
local affected_rows = sqlite_db:Execute("INSERT INTO test VALUES (1, 'amazing')")
Console.Log("受影响行数：" .. tostring(affected_rows))
-- 将输出: 1

-- 查询数据
local rows = sqlite_db:Select("SELECT * FROM test")
Console.Log(NanosTable.Dump(rows))
-- 将输出包含 'test' 中所有数据的表

-- 带条件过滤查询数据
local rows_filter = sqlite_db:Select("SELECT * FROM test WHERE name = :0", "amazing")
Console.Log(NanosTable.Dump(rows_filter))
-- 将输出 'test' 中 name 匹配 'amazing' 的所有数据表

(Database.Execute) Inserts into database (SQLite)
local affected_rows = my_database:Execute("INSERT INTO MyTable VALUES (:0, :1)", 123, "MyValue")

(Database.Select) Selects from a table (SQLite)
local rows = my_database:Select("SELECT * FROM MyTable WHERE name = :0 AND title = :1", "Val", "AnotherVal")

(Database.SelectAsync) Selects from a table asynchronously (SQLite)
my_database:SelectAsync("SELECT * FROM MyTable WHERE name = :0 AND title = :1", function(rows)
	Console.Log(NanosTable.Dump(rows))
end, "Val", "AnotherVal")

提示

所有请求都是线程安全的！ 🥳

🛠 构造函数

Default Constructor

No description provided

local my_database = Database(database_engine, connection_string, pool_size?)

Parameters

Type	Name	Default	Description
DatabaseEngine	`database_engine`	Required parameter	数据库引擎
string	`connection_string`	Required parameter	用于创建并连接到数据库的连接字符串
integer	`pool_size`	`10`	同时调用多个查询时的连接池大小

备注

初始化数据库连接（构造时）是在主线程上进行的，因此在此期间服务器可能会卡顿几秒钟。

信息

如果数据库连接失败，控制台将输出错误并返回 nil。

🗿 静态函数

This class doesn't have own static functions.

🦠 函数

Returns	Name	Description
	`Close`	关闭数据库
integer, string	`Execute`	同步执行查询，阻塞直到完成。建议优先使用 `ExecuteAsync` 以避免服务器卡住
	`ExecuteAsync`	异步执行查询
table of table, string	`Select`	同步运行 SELECT 查询，阻塞直到完成。建议优先使用 `SelectAsync` 以避免服务器卡住
	`SelectAsync`	异步执行选择查询

Slow

`Close`

关闭数据库

my_database:Close()

Blocking

`Execute`

同步执行查询，阻塞直到完成。建议优先使用 ExecuteAsync 以避免服务器卡住

local ret_1, ret_2 = my_database:Execute(query, parameters...?)

Parameters

Type	Parameter	Default	Description
string	`query`	Required parameter	要执行的查询
any	`parameters...?`	`nil`	要转义到查询中的参数序列

Returns

Type	Description
integer	受影响的行
string	错误（如果有）

Database.Execute Examples

Inserts into database (SQLite)
local affected_rows = my_database:Execute("INSERT INTO MyTable VALUES (:0, :1)", 123, "MyValue")

Optimal

`ExecuteAsync`

异步执行查询

my_database:ExecuteAsync(query, callback?, parameters...?)

Parameters

Type	Parameter	Default	Description
string	`query`	Required parameter	要执行的查询
function	`callback?`	`nil`	回调函数 with this format
any	`parameters...?`	`nil`	要转义到查询中的参数序列

Blocking

`Select`

同步运行 SELECT 查询，阻塞直到完成。建议优先使用 SelectAsync 以避免服务器卡住

local ret_1, ret_2 = my_database:Select(query, parameters...?)

Parameters

Type	Parameter	Default	Description
string	`query`	Required parameter	要执行的查询
any	`parameters...?`	`nil`	要转义到查询中的参数序列

Returns

Type	Description
table of table	获取到的行
string	错误（如果有）

Database.Select Examples

Selects from a table (SQLite)
local rows = my_database:Select("SELECT * FROM MyTable WHERE name = :0 AND title = :1", "Val", "AnotherVal")

Optimal

`SelectAsync`

异步执行选择查询

my_database:SelectAsync(query, callback?, parameters...?)

Parameters

Type	Parameter	Default	Description
string	`query`	Required parameter	要执行的查询
function	`callback?`	`nil`	回调函数 with this format
any	`parameters...?`	`nil`	要转义到查询中的参数序列

Database.SelectAsync Examples

Selects from a table asynchronously (SQLite)
my_database:SelectAsync("SELECT * FROM MyTable WHERE name = :0 AND title = :1", function(rows)
	Console.Log(NanosTable.Dump(rows))
end, "Val", "AnotherVal")

提示

向查询传递参数时，请使用以下语法：:?，其中 ? 是传递给函数的占位符参数（例如 :0）。

有关更详细的示例，参见示例

🧵 连接字符串

每个数据库引擎都有自己的参数，可在 connection_string 构造函数中使用。这些参数由引擎定义并取决于后端，会在创建连接时直接传递给后端。

参数设置格式应为："param1=value1 param2=value2 param3=value3"。

提示

通常不需要显式定义此处描述的所有（或大部分）参数，只需使用对你的需求有用的参数即可。其中某些参数虽然库中有说明，但未在 nanos world 中经过 100% 测试。

▶ SQLite

提示

SQLite 有一个特殊的 connection_string：:memory:。这将在内存中创建一个数据库，该数据库将在服务器关闭时销毁。

参数	默认值	描述
`db/dbname`		数据库名称（如果 *.db 文件不存在，将自动创建）
`timeout`	`0`	设置 sqlite 忙等待超时时间（秒）（链接）
`readonly`	`false`	以只读模式而非默认的读写模式打开数据库（注意此种情况下数据库文件必须已存在，参见文档）
`synchronous`		设置 pragma synchronous 标志（链接）
`shared_cache`		应为 true（链接）
`vfs`		设置用作操作系统接口的 SQLite VFS。在打开连接之前应先注册 VFS，参见文档

▶ MySQL

参数	默认值	描述
`db/dbname`		数据库名称
`user`		用于连接的用户名
`password/pass`		服务器要求密码身份验证时使用的密码
`host`		要连接的主机名
`port`		要在服务器主机上连接的端口号
`unix_socket`
`sslca`
`sslcert`
`local_infile`		应为 `0` 或 `1`，`1` 表示将设置 `MYSQL_OPT_LOCAL_INFILE`
`charset`
`reconnect`	`0`	如果设置为 `1`，在连接断开时将尝试重新连接
`connect_timeout`		应为正整数值，表示对应 `MYSQL_OPT_CONNECT_TIMEOUT` 的秒数
`read_timeout`		应为正整数值，表示对应 `MYSQL_OPT_READ_TIMEOUT` 的秒数
`write_timeout`		应为正整数值，表示对应 `MYSQL_OPT_WRITE_TIMEOUT` 的秒数

▶ PostgreSQL

More parameters and complete information can be found at the PostgreSQL Official Documentation.

参数	默认值	描述
`host`		要连接的主机名
`hostaddr`		要连接的主机的数字 IP 地址
`port`		要在服务器主机上连接的端口号
`user`	与操作系统用户名相同	用于连接的用户名
`dbname`	与用户名相同	数据库名称
`password`		服务器要求密码身份验证时使用的密码
`connect_timeout`	`0`	等待连接的最长时间（秒）
`options`		要发送到服务器的命令行选项

🎒 示例​

🛠 构造函数​

Default Constructor​

Parameters

🗿 静态函数​

🦠 函数​

Close​

Execute​

Parameters

Returns

ExecuteAsync​

Parameters

Select​

Parameters

Returns

SelectAsync​

Parameters

🧵 连接字符串​

▶ SQLite​

▶ MySQL​

▶ PostgreSQL​

🎒 示例

🛠 构造函数

Default Constructor

🗿 静态函数

🦠 函数

`Close`

`Execute`

`ExecuteAsync`

`Select`

`SelectAsync`

🧵 连接字符串

▶ SQLite

▶ MySQL

▶ PostgreSQL