11# Rust-Postgres
22A native PostgreSQL driver for Rust.
33
4- [ Documentation] ( https://sfackler.github.io/rust-postgres/doc/v0.10.2 /postgres )
4+ [ Documentation] ( https://sfackler.github.io/rust-postgres/doc/v0.11.0 /postgres )
55
66[ ![ Build Status] ( https://travis-ci.org/sfackler/rust-postgres.png?branch=master )] ( https://travis-ci.org/sfackler/rust-postgres ) [ ![ Latest Version] ( https://img.shields.io/crates/v/postgres.svg )] ( https://crates.io/crates/postgres )
77
88You can integrate Rust-Postgres into your project through the [ releases on crates.io] ( https://crates.io/crates/postgres ) :
99``` toml
1010# Cargo.toml
1111[dependencies ]
12- postgres = " 0.10 "
12+ postgres = " 0.11 "
1313```
1414
1515## Overview
16- Rust-Postgres is a pure-Rust frontend for the popular PostgreSQL database. It
17- exposes a high level interface in the vein of JDBC or Go's ` database/sql `
18- package.
16+ Rust-Postgres is a pure-Rust frontend for the popular PostgreSQL database.
1917``` rust
2018extern crate postgres;
2119
@@ -28,7 +26,7 @@ struct Person {
2826}
2927
3028fn main () {
31- let conn = Connection :: connect (" postgres://postgres@localhost" & SslMode :: None )
29+ let conn = Connection :: connect (" postgres://postgres@localhost" SslMode :: None )
3230 . unwrap ();
3331
3432 conn . execute (" CREATE TABLE person (
@@ -44,8 +42,7 @@ fn main() {
4442 conn . execute (" INSERT INTO person (name, data) VALUES ($1, $2)"
4543 & [& me . name, & me . data]). unwrap ();
4644
47- let stmt = conn . prepare (" SELECT id, name, data FROM person" . unwrap ();
48- for row in stmt . query (& []). unwrap () {
45+ for row in & conn . query (" SELECT id, name, data FROM person" & []). unwrap () {
4946 let person = Person {
5047 id : row . get (0 ),
5148 name : row . get (1 ),
@@ -57,7 +54,7 @@ fn main() {
5754```
5855
5956## Requirements
60- * ** Rust** - Rust-Postgres is developed against the 1.3 release of Rust
57+ * ** Rust** - Rust-Postgres is developed against the 1.4 release of Rust
6158 available on http://www.rust-lang.org . It should also compile against more
6259 recent releases.
6360
@@ -71,7 +68,7 @@ fn main() {
7168Connect to a Postgres server using the standard URI format:
7269``` rust
7370let conn = try ! (Connection :: connect (" postgres://user:pass@host:port/database?arg1=val1&arg2=val2"
74- & SslMode :: None ));
71+ SslMode :: None ));
7572```
7673` pass ` may be omitted if not needed. ` port ` defaults to ` 5432 ` and ` database `
7774defaults to the value of ` user ` if not specified. The driver supports ` trust ` ,
@@ -80,48 +77,48 @@ defaults to the value of `user` if not specified. The driver supports `trust`,
8077Unix domain sockets can be used as well by activating the ` unix_socket ` feature.
8178The ` host ` portion of the URI should be set to the absolute path to the
8279directory containing the socket file. Since ` / ` is a reserved character in
83- URLs, the path should be URL encoded.
80+ URLs, the path should be URL encoded. If Postgres stored its socket files in
81+ ` /run/postgres ` , the connection would then look like:
8482``` rust
85- let conn = try ! (Connection :: connect (" postgres://postgres@%2Frun%2Fpostgres" & SslMode :: None ));
83+ let conn = try ! (Connection :: connect (" postgres://postgres@%2Frun%2Fpostgres" SslMode :: None ));
8684```
8785Paths which contain non-UTF8 characters can be handled in a different manner;
8886see the documentation for details.
8987
90- ### Statement Preparation
91- Prepared statements can have parameters, represented as ` $n ` where ` n ` is an
92- index into the parameter array starting from 1:
93- ``` rust
94- let stmt = try ! (conn . prepare (" SELECT * FROM foo WHERE bar = $1 AND baz = $2"
95- ```
96-
9788### Querying
98- A prepared statement can be executed with the ` query ` and ` execute ` methods.
99- Both methods take an array of parameters to bind to the query represented as
100- ` &ToSql ` trait objects. ` execute ` returns the number of rows affected by the
101- query (or 0 if not applicable):
89+ SQL statements can be executed with the ` query ` and ` execute ` methods. Both
90+ methods take a query string as well as a slice of parameters to bind to the
91+ query. The ` i ` th query parameter is specified in the query string by ` $i ` . Note
92+ that query parameters are 1-indexed rather than the more common 0-indexing.
93+
94+ ` execute ` returns the number of rows affected by the query (or 0 if not
95+ applicable):
10296``` rust
103- let stmt = try ! (conn . prepare (" UPDATE foo SET bar = $1 WHERE baz = $2"
104- let updates = try ! (stmt . execute (& [& 1i32 , & " biz"
97+ let updates = try ! (conn . execute (" UPDATE foo SET bar = $1 WHERE baz = $2" & [& 1i32 , & " biz"
10598println! (" {} rows were updated" updates );
10699```
107- ` query ` returns an iterator over the rows returned from the database. The
108- fields in a row can be accessed either by their indices or their column names,
109- though access by index is more efficient. Unlike statement parameters, result
110- columns are zero-indexed.
100+
101+ ` query ` returns an iterable object holding the rows returned from the database.
102+ The fields in a row can be accessed either by their indices or their column
103+ names, though access by index is more efficient. Unlike statement parameters,
104+ result columns are zero-indexed.
111105``` rust
112- let stmt = try ! (conn . prepare (" SELECT bar, baz FROM foo"
113- for row in try ! (stmt . query (& [])) {
106+ for row in & try ! (conn . query (" SELECT bar, baz FROM foo WHERE buz = $1" & [& 1i32 ])) {
114107 let bar : i32 = row . get (0 );
115108 let baz : String = row . get (" baz"
116109 println! (" bar: {}, baz: {}" bar , baz );
117110}
118111```
119- In addition, ` Connection ` has a utility ` execute ` method which is useful if a
120- statement is only going to be executed once:
112+
113+ ### Statement Preparation
114+ If the same statement will be executed repeatedly (possibly with different
115+ parameters), explicitly preparing it can improve performance:
116+
121117``` rust
122- let updates = try ! (conn . execute (" UPDATE foo SET bar = $1 WHERE baz = $2"
123- & [& 1i32 , & " biz"
124- println! (" {} rows were updated" updates );
118+ let stmt = try ! (conn . prepare (" UPDATE foo SET bar = $1 WHERE baz = $2"
119+ for (bar , baz ) in updates {
120+ try ! (stmt . execute (& [bar , baz ]));
121+ }
125122```
126123
127124### Transactions
@@ -131,14 +128,12 @@ The `transaction` method will start a new transaction. It returns a
131128transaction:
132129``` rust
133130let trans = try ! (conn . transaction ());
131+
134132try ! (trans . execute (... ));
135133let stmt = try ! (trans . prepare (... ));
134+ // ...
136135
137- if the_coast_is_clear {
138- trans . set_commit ();
139- }
140-
141- try ! (trans . finish ());
136+ try ! (trans . commit ());
142137```
143138The transaction will be active until the ` Transaction ` object falls out of
144139scope. A transaction will roll back by default. Nested transactions are
@@ -246,6 +241,13 @@ types. The driver currently supports the following conversions:
246241 </td>
247242 <td>UUID</td>
248243 </tr>
244+ <tr>
245+ <td>
246+ <a href="https://github.com/contain-rs/bit-vec">bit_vec::BitVec</a>
247+ (<a href="#optional-features">optional</a>)
248+ </td>
249+ <td>BIT, VARBIT</td>
250+ </tr>
249251 <tr>
250252 <td>HashMap<String, Option<String>></td>
251253 <td>HSTORE</td>
@@ -285,8 +287,7 @@ implementations for `uuid`'s `Uuid` type.
285287support is provided optionally by the ` rustc-serialize ` feature, which adds
286288` ToSql ` and ` FromSql ` implementations for ` rustc-serialize ` 's ` Json ` type, and
287289the ` serde_json ` feature, which adds implementations for ` serde_json ` 's ` Value `
288- type. The ` serde ` feature provides implementations for the older
289- ` serde::json::Value ` type.
290+ type.
290291
291292### TIMESTAMP/TIMESTAMPTZ/DATE/TIME types
292293
@@ -295,3 +296,9 @@ support is provided optionally by the `time` feature, which adds `ToSql` and
295296` FromSql ` implementations for ` time ` 's ` Timespec ` type, or the ` chrono `
296297feature, which adds ` ToSql ` and ` FromSql ` implementations for ` chrono ` 's
297298` DateTime ` , ` NaiveDateTime ` , ` NaiveDate ` and ` NaiveTime ` types.
299+
300+ ### BIT/VARBIT types
301+
302+ [ BIT and VARBIT] ( http://www.postgresql.org/docs/9.4/static/datatype-bit.html )
303+ support is provided optionally by the ` bit-vec ` feature, which adds ` ToSql ` and
304+ ` FromSql ` implementations for ` bit-vec ` 's ` BitVec ` type.
0 commit comments