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协议的第3版，对应于7.4及更高版本。如果您的Postgres版本是在过去十年内编译的，那么应该没有问题。

用法

连接

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

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

pass可能被省略，如果不需要的话。 port默认为5432，如果未指定，则database默认为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 返回一个包含从数据库返回的行的可迭代对象。行中的字段可以通过索引或列名访问，尽管通过索引访问更高效。与语句参数不同，结果列是零索引的。

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，这些表示一维 PostgreSQL 数组。

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

postgres-derive 包将合成枚举、域和复合 PostgreSQL 类型的 ToSql 和 FromSql 实现。

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

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

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

可选特性

UUID 类型

UUID 支持是通过 with-uuid 特性提供的，该特性为 uuid 的 Uuid 类型添加了 ToSql 和 FromSql 实现。需要 uuid 版本 0.5。

JSON/JSONB 类型

JSON 和 JSONB 支持是通过 with-rustc-serialize 特性提供的，该特性为 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 类型

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

MACADDR 类型

MACADDR 支持是通过 with-eui48 特性提供的，该特性为 eui48 的 MacAddress 类型添加了 ToSql 和 FromSql 实现。需要 eui48 版本 0.3。

POINT 类型

通过with-geo功能可选支持POINT，该功能为geo的Point类型添加了ToSql和FromSql实现。需要geo版本0.4。

BOX类型

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

PATH类型

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

参见

• r2d2-postgres用于连接池支持。