Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Rust-Postgres
A native PostgreSQL driver for Rust.
Documentation is available at https://sfackler.github.io/rust-postgres/doc/postgres
You can integrate Rust-Postgres into your project through the releases on crates.io:
# Cargo.toml
[]
= "0.6"
Overview
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.
extern crate postgres;
use ;
Requirements
-
Rust - Rust-Postgres is developed against the nightly releases on 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.
Usage
Connecting
Connect to a Postgres server using the standard URI format:
let conn = try!;
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.
Unix domain sockets can be used as well by activating the unix_socket
feature.
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.
let conn = try!;
Paths which contain non-UTF8 characters can be handled in a different manner; see the documentation for details.
Statement Preparation
Prepared statements can have parameters, represented as $n
where n
is an
index into the parameter array starting from 1:
let stmt = try!;
Querying
A prepared statement can be executed with the query
and execute
methods.
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
query (or 0 if not applicable):
let stmt = try!;
let updates = try!;
println!;
query
returns an iterator over the rows returned from the database. The
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.
let stmt = try!;
for row in try!
In addition, Connection
has a utility execute
method which is useful if a
statement is only going to be executed once:
let updates = try!;
println!;
Transactions
The transaction
method will start a new transaction. It returns a
Transaction
object which has the functionality of a
Connection
as well as methods to control the result of the
transaction:
let trans = try!;
try!;
let stmt = try!;
if the_coast_is_clear
try!;
The transaction will be active until the Transaction
object falls out of
scope. A transaction will roll back by default. Nested transactions are
supported via savepoints.
Type Correspondence
Rust-Postgres enforces a strict correspondence between Rust types and Postgres types. The driver currently supports the following conversions:
More conversions can be defined by implementing the ToSql
and FromSql
traits.
Support for Postgres arrays is located in the postgres-array crate.
Support for Postgres ranges is located in the postgres-range crate.
Optional features
UUID type
UUID support is
provided optionally by the uuid
feature.
JSON/JSONB types
JSON and JSONB
support is provided optionally by the rustc-serialize
feature.
TIMESTAMP/TIMESTAMPTZ types
TIMESTAMP and TIMESTAMPTZ
support is provided optionally by the time
feature.
Development
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!