MySQL 查询协议

文本协议

MySQL 文本协议在 Queryable::query* 方法中实现，并且在 prelude::Query 特性中实现，如果查询是 prelude::AsQuery。当您的查询没有参数时，这很有用。

注意：服务器将所有文本协议结果集的值编码为字符串，因此 from_value 转换可能会导致额外的解析成本。

二进制协议和预编译语句。

MySQL二进制协议在exec*方法集中实现，这些方法定义在prelude::Queryable特性和prelude::Query特性中，如果查询是QueryWithParams。预编译语句是传递Rust值到MySQL服务器的唯一方式。MySQL使用?符号作为参数占位符。

注意：只能在期望单个MySQL值的地方使用参数，即不能执行类似SELECT ... WHERE id IN ?的操作，其中参数是一个向量。你需要构建一个看起来像SELECT ... WHERE id IN (?, ?, ...)的查询，并将每个向量元素作为参数传递。

命名参数

MySQL本身不支持命名参数，因此客户端实现了它。应使用:name作为命名参数的占位符语法。命名参数使用以下命名约定

• 参数名称必须以_或a..z开头
• 参数名称可以继续使用_、a..z和0..9

注意：这些规则意味着，例如，语句SELECT :fooBar将被转换为SELECT ?Bar，因此请务必小心。

命名参数可以在语句中重复使用，例如SELECT :foo, :foo将需要一个单个的命名参数foo，该参数将在语句执行期间在相应的位置重复。

应使用params!宏来构建执行参数。

注意：在单个语句中不能混合位置参数和命名参数。

语句

在MySQL中，每个预编译语句都属于特定的连接，不能在另一个连接上执行。尝试这样做将导致错误。驱动程序不会以任何方式将语句绑定到其连接，但可以通过查看包含在Statement结构中的连接ID来进行检查。

LOCAL INFILE处理器

警告：您应该注意LOAD DATA LOCAL的安全注意事项。

存在两种LOCAL INFILE处理器 - 全局和局部。

如果服务器请求LOCAL INFILE，驱动程序将尝试为其找到一个处理器

1. 如果连接上安装了任何局部处理器，它将尝试使用该处理器；
2. 如果提供了任何，它将尝试使用通过OptsBuilder::local_infile_handler指定的全局处理器；
3. 如果没有找到处理器，将发出 LocalInfileError::NoHandler 错误。

处理器（局部 或 全局）的目的是返回 InfileData。

全局 LOCAL INFILE 处理器

请参阅 prelude::GlobalHandler。

简单来说，全局处理器是一个异步函数，它接受一个文件名（作为 &[u8]）并返回 Result<InfileData>。

您可以使用 OptsBuilder::local_infile_handler 来设置它。如果没有为连接安装 局部 处理器，服务器将使用它。此处理器可能会被多次调用。

示例

1. WhiteListFsHandler 是一个 全局 处理器。
2. 每个 T: Fn(&[u8]) -> BoxFuture<'static, Result<InfileData, LocalInfileError>> 都是一个 全局 处理器。

局部 LOCAL INFILE 处理器。

简单来说，局部处理器是一个返回 Result<InfileData> 的未来。

这是一个一次性处理器 - 使用后就会被消耗。您可以使用 Conn::set_infile_handler 来设置它。此处理器的优先级高于 全局 处理器。

需要注意的是

1. impl Drop for Conn 将清除 局部 处理器，即处理器将在连接返回到 Pool 时被删除。
2. Conn::reset 将清除 局部 处理器。

示例

#
let pool = mysql_async::Pool::new(database_url);

let mut conn = pool.get_conn().await?;
"CREATE TEMPORARY TABLE tmp (id INT, val TEXT)".ignore(&mut conn).await?;

// We are going to call `LOAD DATA LOCAL` so let's setup a one-time handler.
conn.set_infile_handler(async move {
    // We need to return a stream of `io::Result<Bytes>`
    Ok(stream::iter([Bytes::from("1,a\r\n"), Bytes::from("2,b\r\n3,c")]).map(Ok).boxed())
});

let result = r#"LOAD DATA LOCAL INFILE 'whatever'
    INTO TABLE `tmp`
    FIELDS TERMINATED BY ',' ENCLOSED BY '\"'
    LINES TERMINATED BY '\r\n'"#.ignore(&mut conn).await;

match result {
    Ok(()) => (),
    Err(Error::Server(ref err)) if err.code == 1148 => {
        // The used command is not allowed with this MySQL version
        return Ok(());
    },
    Err(Error::Server(ref err)) if err.code == 3948 => {
        // Loading local data is disabled;
        // this must be enabled on both the client and the server
        return Ok(());
    }
    e @ Err(_) => e.unwrap(),
}

// Now let's verify the result
let result: Vec<(u32, String)> = conn.query("SELECT * FROM tmp ORDER BY id ASC").await?;
assert_eq!(
    result,
    vec![(1, "a".into()), (2, "b".into()), (3, "c".into())]
);

drop(conn);
pool.disconnect().await?;

测试

测试使用以下环境变量

• DATABASE_URL - 默认为 mysql://root:[email protected]:3307/mysql
• COMPRESS - 设置为 1 或 true 以启用测试的压缩
• SSL - 设置为 1 或 true 以启用测试的 TLS

您可以使用 doker 运行一个测试服务器。请注意，有关最大允许数据包、本地文件和二进制日志的参数对于正确运行测试是必需的（请参阅 azure-pipelines.yml）

docker run -d --name container \
    -v `pwd`:/root \
    -p 3307:3306 \
    -e MYSQL_ROOT_PASSWORD=password \
    mysql:8.0 \
    --max-allowed-packet=36700160 \
    --local-infile \
    --log-bin=mysql-bin \
    --log-slave-updates \
    --gtid_mode=ON \
    --enforce_gtid_consistency=ON \
    --server-id=1

变更日志

在此 处 可用

许可

许可协议如下之一

• Apache License, Version 2.0, (LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0)
• MIT 协议 (LICENSE-MIT 或 https://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确声明，否则根据 Apache-2.0 许可证定义的，您有意提交以包含在作品中的任何贡献，将按上述方式双许可，不附加任何额外条款或条件。