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/doc/postgres
You can integrate Rust-Postgres into your project through the releases on crates.io:
# Cargo.toml
[]
= "0.4"
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;
extern crate time;
use Timespec;
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. 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. It is enabled by default.
To disable support for optional features, add default-features = false
to
your Cargo manifest:
[]
= ...
= false
= [...]
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!