rust-postgres/README.md

286 lines
9.1 KiB
Markdown
Raw Normal View History

2014-08-15 06:05:11 +00:00
# Rust-Postgres
2013-09-03 06:19:03 +00:00
A native PostgreSQL driver for Rust.
2014-10-26 20:11:14 +00:00
Documentation is available at https://sfackler.github.io/doc/postgres
2013-09-30 04:21:00 +00:00
2013-10-08 06:03:05 +00:00
[![Build Status](https://travis-ci.org/sfackler/rust-postgres.png?branch=master)](https://travis-ci.org/sfackler/rust-postgres)
2014-08-15 06:05:11 +00:00
## Overview
2013-09-03 06:19:03 +00:00
Rust-Postgres is a pure-Rust frontend for the popular PostgreSQL database. It
exposes a high level interface in the vein of JDBC or Go's `database/sql`
package.
```rust
extern crate postgres;
2014-03-09 07:37:31 +00:00
extern crate time;
2013-09-03 06:19:03 +00:00
2014-03-09 07:37:31 +00:00
use time::Timespec;
2013-10-01 07:01:54 +00:00
2014-11-01 23:31:06 +00:00
use postgres::{Connection, NoSsl};
2013-09-03 06:19:03 +00:00
struct Person {
id: i32,
2014-05-26 03:39:06 +00:00
name: String,
2013-10-01 07:01:54 +00:00
time_created: Timespec,
2014-04-08 16:59:45 +00:00
data: Option<Vec<u8>>
2013-09-03 06:19:03 +00:00
}
fn main() {
2014-11-01 23:38:52 +00:00
let conn = Connection::connect("postgres://postgres@localhost", &NoSsl)
.unwrap();
2013-09-03 06:19:03 +00:00
conn.execute("CREATE TABLE person (
2013-10-01 07:01:54 +00:00
id SERIAL PRIMARY KEY,
name VARCHAR NOT NULL,
time_created TIMESTAMP NOT NULL,
data BYTEA
)", []).unwrap();
2013-09-03 06:19:03 +00:00
let me = Person {
id: 0,
2014-10-18 18:17:12 +00:00
name: "Steven".into_string(),
2013-10-01 07:01:54 +00:00
time_created: time::get_time(),
2013-09-03 06:19:03 +00:00
data: None
};
conn.execute("INSERT INTO person (name, time_created, data)
2013-09-03 06:19:03 +00:00
VALUES ($1, $2, $3)",
&[&me.name, &me.time_created, &me.data]).unwrap();
2013-09-03 06:19:03 +00:00
let stmt = conn.prepare("SELECT id, name, time_created, data FROM person")
.unwrap();
for row in stmt.query([]).unwrap() {
2013-09-03 06:19:03 +00:00
let person = Person {
id: row.get(0),
name: row.get(1),
time_created: row.get(2),
data: row.get(3)
2013-09-03 06:19:03 +00:00
};
2013-10-01 07:01:54 +00:00
println!("Found person {}", person.name);
2013-09-03 06:19:03 +00:00
}
}
```
2014-08-15 06:05:11 +00:00
## Requirements
2013-09-03 06:19:03 +00:00
* **Rust** - Rust-Postgres is developed against the *master* branch of the Rust
2014-05-26 22:21:15 +00:00
repository. It will most likely not build against the versioned releases on
2013-09-03 06:19:03 +00:00
http://www.rust-lang.org.
* **PostgreSQL 7.4 or later** - Rust-Postgres speaks version 3 of the
PostgreSQL protocol, which corresponds to versions 7.4 and later. If your
version of Postgres was compiled in the last decade, you should be okay.
2014-08-15 06:05:11 +00:00
## Usage
2013-09-03 06:19:03 +00:00
2014-08-15 06:05:11 +00:00
### Connecting
2013-09-03 06:19:03 +00:00
Connect to a Postgres server using the standard URI format:
```rust
2014-11-01 23:31:06 +00:00
let conn = try!(Connection::connect("postgres://user:pass@host:port/database?arg1=val1&arg2=val2",
2014-11-01 23:38:52 +00:00
&NoSsl));
2013-09-03 06:19:03 +00:00
```
`pass` may be omitted if not needed. `port` defaults to `5432` and `database`
defaults to the value of `user` if not specified. The driver supports `trust`,
`password`, and `md5` authentication.
2013-09-03 06:19:03 +00:00
Unix domain sockets can be used as well. The `host` portion of the URI should be
set to the absolute path to the directory containing the socket file. Since `/`
is a reserved character in URLs, the path should be URL encoded.
```rust
2014-11-01 23:31:06 +00:00
let conn = try!(Connection::connect("postgres://postgres@%2Frun%2Fpostgres", &NoSsl));
```
Paths which contain non-UTF8 characters can be handled in a different manner;
see the documentation for details.
2014-08-15 06:05:11 +00:00
### Statement Preparation
2013-09-03 06:19:03 +00:00
Prepared statements can have parameters, represented as `$n` where `n` is an
index into the parameter array starting from 1:
```rust
2014-03-28 04:20:04 +00:00
let stmt = try!(conn.prepare("SELECT * FROM foo WHERE bar = $1 AND baz = $2"));
2013-09-03 06:19:03 +00:00
```
2014-08-15 06:05:11 +00:00
### Querying
A prepared statement can be executed with the `query` and `execute` methods.
2013-09-03 06:19:03 +00:00
Both methods take an array of parameters to bind to the query represented as
`&ToSql` trait objects. `execute` returns the number of rows affected by the
2013-09-03 06:19:03 +00:00
query (or 0 if not applicable):
2013-09-03 06:23:58 +00:00
```rust
2014-05-19 04:23:53 +00:00
let stmt = try!(conn.prepare("UPDATE foo SET bar = $1 WHERE baz = $2"));
let updates = try!(stmt.execute(&[&1i32, &"biz"]));
2013-09-03 06:19:03 +00:00
println!("{} rows were updated", updates);
```
2013-11-06 05:31:24 +00:00
`query` returns an iterator over the rows returned from the database. The
2013-12-03 03:53:40 +00:00
fields in a row can be accessed either by their indices or their column names,
though access by index is more efficient. Unlike statement parameters, result
columns are zero-indexed.
2013-09-03 06:19:03 +00:00
```rust
2014-03-28 04:20:04 +00:00
let stmt = try!(conn.prepare("SELECT bar, baz FROM foo"));
for row in try!(stmt.query([])) {
2014-10-26 06:49:13 +00:00
let bar: i32 = row.get(0);
2014-07-24 16:11:53 +00:00
let baz: String = row.get("baz");
2013-09-03 06:19:03 +00:00
println!("bar: {}, baz: {}", bar, baz);
}
```
2014-11-01 23:38:52 +00:00
In addition, `Connection` has a utility `execute` method which is useful if a
statement is only going to be executed once:
2013-09-03 06:19:03 +00:00
```rust
2014-03-28 04:20:04 +00:00
let updates = try!(conn.execute("UPDATE foo SET bar = $1 WHERE baz = $2",
&[&1i32, &"biz"]));
2013-09-03 06:19:03 +00:00
println!("{} rows were updated", updates);
```
2014-08-15 06:05:11 +00:00
### Transactions
2013-10-14 01:58:31 +00:00
The `transaction` method will start a new transaction. It returns a
2014-11-01 23:31:06 +00:00
`Transaction` object which has the functionality of a
`Connection` as well as methods to control the result of the
2013-10-14 01:58:31 +00:00
transaction:
2013-09-03 06:19:03 +00:00
```rust
2014-03-28 04:20:04 +00:00
let trans = try!(conn.transaction());
try!(trans.execute(...));
let stmt = try!(trans.prepare(...));
2013-09-03 06:19:03 +00:00
2013-12-05 05:32:13 +00:00
if the_coast_is_clear {
trans.set_commit();
2013-09-03 06:19:03 +00:00
}
2013-12-05 05:32:13 +00:00
2014-07-26 05:42:24 +00:00
try!(trans.finish());
2013-09-03 06:19:03 +00:00
```
2014-11-01 23:38:52 +00:00
The transaction will be active until the `Transaction` object falls out of
scope. A transaction will roll back by default. Nested transactions are
2013-10-14 01:58:31 +00:00
supported via savepoints.
2013-09-03 06:19:03 +00:00
2014-08-15 06:05:11 +00:00
### Type Correspondence
2013-09-03 06:19:03 +00:00
Rust-Postgres enforces a strict correspondence between Rust types and Postgres
2013-09-16 03:05:32 +00:00
types. The driver currently supports the following conversions:
2013-09-03 06:19:03 +00:00
<table>
<thead>
<tr>
<td>Rust Type</td>
<td>Postgres Type</td>
</tr>
</thead>
<tbody>
<tr>
<td>bool</td>
<td>BOOL</td>
</tr>
<tr>
<td>i8</td>
<td>"char"</td>
</tr>
<tr>
<td>i16</td>
2013-11-06 05:35:07 +00:00
<td>SMALLINT, SMALLSERIAL</td>
2013-09-03 06:19:03 +00:00
</tr>
<tr>
<td>i32</td>
2013-11-06 05:35:07 +00:00
<td>INT, SERIAL</td>
2013-09-03 06:19:03 +00:00
</tr>
<tr>
<td>i64</td>
2013-11-06 05:35:07 +00:00
<td>BIGINT, BIGSERIAL</td>
2013-09-03 06:19:03 +00:00
</tr>
<tr>
<td>f32</td>
2013-11-06 05:35:07 +00:00
<td>REAL</td>
2013-09-03 06:19:03 +00:00
</tr>
<tr>
<td>f64</td>
2013-11-06 05:35:07 +00:00
<td>DOUBLE PRECISION</td>
2013-09-03 06:19:03 +00:00
</tr>
<tr>
2014-05-26 22:21:15 +00:00
<td>str/String</td>
2013-09-03 06:19:03 +00:00
<td>VARCHAR, CHAR(n), TEXT</td>
</tr>
<tr>
2014-04-08 16:59:45 +00:00
<td>[u8]/Vec&lt;u8&gt;</td>
2013-09-03 06:19:03 +00:00
<td>BYTEA</td>
</tr>
<tr>
2014-06-28 03:36:12 +00:00
<td>serialize::json::Json</td>
2013-09-03 06:19:03 +00:00
<td>JSON</td>
</tr>
2013-09-08 20:27:15 +00:00
<tr>
2014-06-28 03:36:12 +00:00
<td>time::Timespec</td>
2013-09-09 04:42:03 +00:00
<td>TIMESTAMP, TIMESTAMP WITH TIME ZONE</td>
2013-09-08 20:27:15 +00:00
</tr>
2013-10-31 05:51:18 +00:00
<tr>
<td>types::range::Range&lt;i32&gt;</td>
<td>INT4RANGE</td>
</tr>
<tr>
<td>types::range::Range&lt;i64&gt;</td>
<td>INT8RANGE</td>
</tr>
<tr>
<td>types::range::Range&lt;Timespec&gt;</td>
<td>TSRANGE, TSTZRANGE</td>
</tr>
2013-12-07 23:39:44 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;bool&gt;&gt;</td>
<td>BOOL[], BOOL[][], ...</td>
</tr>
2013-12-08 02:38:53 +00:00
<tr>
2014-04-08 16:59:45 +00:00
<td>types::array::ArrayBase&lt;Option&lt;Vec&lt;u8&gt;&gt;&gt;</td>
2013-12-08 02:38:53 +00:00
<td>BYTEA[], BYTEA[][], ...</td>
</tr>
2013-12-08 02:49:55 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;i8&gt;&gt;</td>
<td>"char"[], "char"[][], ...</td>
</tr>
2013-12-08 02:58:40 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;i16&gt;&gt;</td>
<td>INT2[], INT2[][], ...</td>
</tr>
2013-12-02 05:09:31 +00:00
<tr>
2013-12-02 05:41:42 +00:00
<td>types::array::ArrayBase&lt;Option&lt;i32&gt;&gt;</td>
2013-12-02 05:09:31 +00:00
<td>INT4[], INT4[][], ...</td>
</tr>
2013-12-08 03:13:21 +00:00
<tr>
2014-05-26 22:21:15 +00:00
<td>types::array::ArrayBase&lt;Option&lt;String&gt;&gt;</td>
2013-12-08 21:58:41 +00:00
<td>TEXT[], CHAR(n)[], VARCHAR[], TEXT[][], ...</td>
2013-12-08 03:13:21 +00:00
</tr>
2013-12-09 00:00:33 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;Json&gt;&gt;</td>
<td>JSON[], JSON[][], ...</td>
</tr>
2013-12-04 06:32:54 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;i64&gt;&gt;</td>
<td>INT8[], INT8[][], ...</td>
</tr>
2013-12-08 22:04:26 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;Timespec&gt;&gt;</td>
2013-12-08 22:08:35 +00:00
<td>TIMESTAMP[], TIMESTAMPTZ[], TIMESTAMP[][], ...</td>
2013-12-08 22:04:26 +00:00
</tr>
2013-12-06 05:51:09 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;f32&gt;&gt;</td>
<td>FLOAT4[], FLOAT4[][], ...</td>
</tr>
2013-12-06 05:58:22 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;f64&gt;&gt;</td>
<td>FLOAT8[], FLOAT8[][], ...</td>
</tr>
2013-12-08 22:37:31 +00:00
<tr>
2013-12-08 23:03:27 +00:00
<td>types::array::ArrayBase&lt;Option&lt;Range&lt;i32&gt;&gt;&gt;</td>
2013-12-08 22:37:31 +00:00
<td>INT4RANGE[], INT4RANGE[][], ...</td>
</tr>
2013-12-08 23:02:38 +00:00
<tr>
2013-12-08 23:03:27 +00:00
<td>types::array::ArrayBase&lt;Option&lt;Range&lt;Timespec&gt;&gt;&gt;</td>
2013-12-08 23:02:38 +00:00
<td>TSRANGE[], TSTZRANGE[], TSRANGE[][], ...</td>
</tr>
2013-12-08 23:07:11 +00:00
<tr>
<td>types::array::ArrayBase&lt;Option&lt;Range&lt;i64&gt;&gt;&gt;</td>
<td>INT8RANGE[], INT8RANGE[][], ...</td>
</tr>
2013-12-05 05:20:48 +00:00
<tr>
2014-06-28 03:36:12 +00:00
<td>std::collections::HashMap&lt;String, Option&lt;String&gt;&gt;</td>
2013-12-05 05:20:48 +00:00
<td>HSTORE</td>
</tr>
2013-09-03 06:19:03 +00:00
</tbody>
</table>
More conversions can be defined by implementing the `ToSql` and `FromSql`
traits.
2014-08-15 06:05:11 +00:00
## Development
2013-11-06 05:29:41 +00:00
Like Rust itself, Rust-Postgres is still in the early stages of development, so
don't be surprised if APIs change and things break. If something's not working
properly, file an issue or submit a pull request!