Rust-Postgres

Rust 的原生 PostgreSQL 驱动程序。

文档

您可以通过 crates.io 上的发行版 将 Rust-Postgres 集成到您的项目中

[dependencies]
postgres = "0.15"

概述

Rust-Postgres 是流行的 PostgreSQL 数据库的纯 Rust 前端。

extern crate postgres;

use postgres::{Connection, TlsMode};

struct Person {
    id: i32,
    name: String,
    data: Option<Vec<u8>>,
}

fn main() {
    let conn = Connection::connect("postgres://postgres@localhost:5433", TlsMode::None).unwrap();
    conn.execute("CREATE TABLE person (
                    id              SERIAL PRIMARY KEY,
                    name            VARCHAR NOT NULL,
                    data            BYTEA
                  )", &[]).unwrap();
    let me = Person {
        id: 0,
        name: "Steven".to_string(),
        data: None,
    };
    conn.execute("INSERT INTO person (name, data) VALUES ($1, $2)",
                 &[&me.name, &me.data]).unwrap();
    for row in &conn.query("SELECT id, name, data FROM person", &[]).unwrap() {
        let person = Person {
            id: row.get(0),
            name: row.get(1),
            data: row.get(2),
        };
        println!("Found person {}: {}", person.id, person.name);
    }
}

要求

• Rust - Rust-Postgres 是针对 https://www.rust-lang.net.cn 上可用的 Rust 1.18 版本开发的。它也应该能编译针对更新版本的发行版。

• PostgreSQL 7.4 或更高版本 - Rust-Postgres 使用 PostgreSQL 协议的第三个版本，对应于 7.4 及更高版本。如果您的 Postgres 版本是在过去十年内编译的，那么应该没有问题。

使用方法

连接

使用标准的 URI 格式连接到 Postgres 服务器

let conn = Connection::connect("postgres://user:pass@host:port/database?arg1=val1&arg2=val2",
                               TlsMode::None)?;

pass 如果不需要可以省略。默认情况下，port 为 5432，如果未指定，则默认为 user 的值。该驱动程序支持 trust、password 和 md5 认证。

也可以使用 Unix 域套接字。URI 的 host 部分应设置为包含套接字文件的目录的绝对路径。由于 / 是 URL 中的保留字符，路径应该进行 URL 编码。如果 Postgres 将其套接字文件存储在 /run/postgres 中，那么连接看起来将是这样的

let conn = Connection::connect("postgres://postgres@%2Frun%2Fpostgres", TlsMode::None)?;

包含非 UTF-8 字符的路径可以以不同的方式处理；请参阅文档以获取详细信息。

查询

可以使用 query 和 execute 方法执行 SQL 语句。这两种方法都接受一个查询字符串以及绑定到查询的参数切片。第 i 个查询参数通过查询字符串中的 $i 指定。请注意，查询参数是从 1 开始计数的，而不是更常见的 0 计数。

execute 返回由查询影响的行数（如果不适用则返回 0）

let updates = conn.execute("UPDATE foo SET bar = $1 WHERE baz = $2", &[&1i32, &"biz"])?;
println!("{} rows were updated", updates);

query 返回一个包含从数据库返回的行的可迭代对象。行中的字段可以通过它们的索引或列名访问，尽管通过索引访问更高效。与语句参数不同，结果列是从 0 开始索引的。

for row in &conn.query("SELECT bar, baz FROM foo WHERE buz = $1", &[&1i32])? {
    let bar: i32 = row.get(0);
    let baz: String = row.get("baz");
    println!("bar: {}, baz: {}", bar, baz);
}

语句准备

如果相同的语句将被反复执行（可能带有不同的参数），则显式准备它可以提高性能

let stmt = conn.prepare("UPDATE foo SET bar = $1 WHERE baz = $2")?;
for (bar, baz) in updates {
    stmt.execute(&[bar, baz])?;
}

事务

transaction 方法将启动一个新的事务。它返回一个 Transaction 对象，该对象具有 Connection 的功能以及控制事务结果的方法

let trans = conn.transaction()?;

trans.execute(...)?;
let stmt = trans.prepare(...)?;
// ...

trans.commit()?;

事务将在 Transaction 对象超出作用域时变得活跃。默认情况下，事务将回滚。通过保存点支持嵌套事务。

类型对应关系

Rust-Postgres 强制 Rust 类型与 Postgres 类型之间的严格对应关系。驱动程序目前支持以下转换

Option<T> 实现 FromSql，其中 T: FromSql 和 ToSql，其中 T: ToSql，表示可空 Postgres 值。

&[T] 和 Vec<T> 实现了 ToSql，其中 T: ToSql，并且 Vec<T> 还额外实现了 FromSql，其中 T: FromSql，它们代表一维的Postgres数组。

可以通过实现 ToSql 和 FromSql 特性来定义更多转换。

postgres-derive 包会自动生成枚举、域和复合Postgres类型的 ToSql 和 FromSql 实现。

数组类型的完全支持位于 postgres-array 包中。

范围类型的支持位于 postgres-range 包中。

大对象API的支持位于 postgres-large-object 包中。

可选功能

UUID类型

通过 with-uuid 功能可选提供UUID支持，该功能为 uuid 的 Uuid 类型添加 ToSql 和 FromSql 实现。需要 uuid 版本 0.5。

JSON/JSONB类型

通过 with-rustc-serialize 功能可选提供JSON和JSONB支持，该功能为 rustc-serialize 的 Json 类型添加 ToSql 和 FromSql 实现，以及 with-serde_json 功能，该功能为 serde_json 的 Value 类型添加实现。需要 serde_json 版本 1.0，rustc-serialize 版本 0.3。

TIMESTAMP/TIMESTAMPTZ/DATE/TIME类型

通过 with-time 功能可选提供日期和时间支持，该功能为 time 的 Timespec 类型添加 ToSql 和 FromSql 实现，或者通过 with-chrono 功能，该功能为 chrono 的 DateTime、NaiveDateTime、NaiveDate 和 NaiveTime 类型添加 ToSql 和 FromSql 实现。需要 time 版本 0.1.14。

BIT/VARBIT类型

通过 with-bit-vec 功能可选提供BIT和VARBIT支持，该功能为 bit-vec 的 BitVec 类型添加 ToSql 和 FromSql 实现。需要 bit-vec 版本 0.4。

MACADDR类型

通过 with-eui48 功能可选提供MACADDR支持，该功能为 eui48 的 MacAddress 类型添加 ToSql 和 FromSql 实现。需要 eui48 版本 0.3。

POINT类型

点支持是可选的，由with-geo功能提供，该功能为geo的Point类型添加了ToSql和FromSql实现。需要geo版本0.4。

BOX类型

BOX支持是可选的，由with-geo功能提供，该功能为geo的Bbox类型添加了ToSql和FromSql实现。需要geo版本0.4。

PATH类型

PATH支持是可选的，由with-geo功能提供，该功能为geo的LineString类型添加了ToSql和FromSql实现。从LineString转换的路径始终被视为“开放”路径。需要geo版本0.4。使用pclose几何函数插入闭合路径。

另请参阅

• r2d2-postgres以支持连接池。