Formatting cleanup
This commit is contained in:
Steven Fackler
parent
455dea3bd0
commit
97efc52a3b
34
README.md
34
README.md
@ -1,13 +1,11 @@
|
||||
Rust-Postgres
|
||||
=============
|
||||
# Rust-Postgres
|
||||
A native PostgreSQL driver for Rust.
|
||||
|
||||
Documentation is available at http://www.rust-ci.org/sfackler/rust-postgres/doc/postgres/.
|
||||
|
||||
[](https://travis-ci.org/sfackler/rust-postgres)
|
||||
|
||||
Overview
|
||||
========
|
||||
## 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.
|
||||
@ -61,9 +59,7 @@ fn main() {
|
||||
}
|
||||
```
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
## Requirements
|
||||
* **Rust** - Rust-Postgres is developed against the *master* branch of the Rust
|
||||
repository. It will most likely not build against the versioned releases on
|
||||
http://www.rust-lang.org.
|
||||
@ -72,11 +68,9 @@ Requirements
|
||||
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
|
||||
=====
|
||||
## Usage
|
||||
|
||||
Connecting
|
||||
----------
|
||||
### Connecting
|
||||
Connect to a Postgres server using the standard URI format:
|
||||
```rust
|
||||
let conn = try!(PostgresConnection::connect("postgres://user:pass@host:port/database?arg1=val1&arg2=val2",
|
||||
@ -95,16 +89,14 @@ let conn = try!(PosgresConnection::connect("postgres://postgres@%2Frun%2Fpostgre
|
||||
Paths which contain non-UTF8 characters can be handled in a different manner;
|
||||
see the documentation for details.
|
||||
|
||||
Statement Preparation
|
||||
---------------------
|
||||
### Statement Preparation
|
||||
Prepared statements can have parameters, represented as `$n` where `n` is an
|
||||
index into the parameter array starting from 1:
|
||||
```rust
|
||||
let stmt = try!(conn.prepare("SELECT * FROM foo WHERE bar = $1 AND baz = $2"));
|
||||
```
|
||||
|
||||
Querying
|
||||
--------
|
||||
### 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
|
||||
@ -134,8 +126,7 @@ let updates = try!(conn.execute("UPDATE foo SET bar = $1 WHERE baz = $2",
|
||||
println!("{} rows were updated", updates);
|
||||
```
|
||||
|
||||
Transactions
|
||||
------------
|
||||
### Transactions
|
||||
The `transaction` method will start a new transaction. It returns a
|
||||
`PostgresTransaction` object which has the functionality of a
|
||||
`PostgresConnection` as well as methods to control the result of the
|
||||
@ -155,8 +146,7 @@ The transaction will be active until the `PostgresTransaction` object falls out
|
||||
of scope. A transaction will roll back by default. Nested transactions are
|
||||
supported via savepoints.
|
||||
|
||||
Connection Pooling
|
||||
------------------
|
||||
### Connection Pooling
|
||||
A very basic fixed-size connection pool is provided in the `pool` module. A
|
||||
single pool can be shared across tasks and `get_connection` will block until a
|
||||
connection is available.
|
||||
@ -173,8 +163,7 @@ for _ in range(0, 10) {
|
||||
}
|
||||
```
|
||||
|
||||
Type Correspondence
|
||||
-------------------
|
||||
### Type Correspondence
|
||||
Rust-Postgres enforces a strict correspondence between Rust types and Postgres
|
||||
types. The driver currently supports the following conversions:
|
||||
|
||||
@ -308,8 +297,7 @@ types. The driver currently supports the following conversions:
|
||||
More conversions can be defined by implementing the `ToSql` and `FromSql`
|
||||
traits.
|
||||
|
||||
Development
|
||||
===========
|
||||
## 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!
|
||||
|
||||
@ -220,8 +220,7 @@ pub trait FromSql {
|
||||
/// Creates a new value of this type from a buffer of Postgres data.
|
||||
///
|
||||
/// If the value was `NULL`, the buffer will be `None`.
|
||||
fn from_sql(ty: &PostgresType, raw: &Option<Vec<u8>>)
|
||||
-> PostgresResult<Self>;
|
||||
fn from_sql(ty: &PostgresType, raw: &Option<Vec<u8>>) -> PostgresResult<Self>;
|
||||
}
|
||||
|
||||
#[doc(hidden)]
|
||||
@ -282,8 +281,7 @@ impl RawFromSql for Timespec {
|
||||
macro_rules! from_range_impl(
|
||||
($t:ty) => (
|
||||
impl RawFromSql for Range<$t> {
|
||||
fn raw_from_sql<R: Reader>(rdr: &mut R)
|
||||
-> PostgresResult<Range<$t>> {
|
||||
fn raw_from_sql<R: Reader>(rdr: &mut R) -> PostgresResult<Range<$t>> {
|
||||
let t = try_pg!(rdr.read_i8());
|
||||
|
||||
if t & RANGE_EMPTY != 0 {
|
||||
@ -444,8 +442,7 @@ impl FromSql for Option<HashMap<String, Option<String>>> {
|
||||
fn from_sql(ty: &PostgresType, raw: &Option<Vec<u8>>)
|
||||
-> PostgresResult<Option<HashMap<String, Option<String>>>> {
|
||||
match *ty {
|
||||
PgUnknownType { name: ref name, .. }
|
||||
if "hstore" == name.as_slice() => {}
|
||||
PgUnknownType { name: ref name, .. } if "hstore" == name.as_slice() => {}
|
||||
_ => return Err(PgWrongType(ty.clone()))
|
||||
}
|
||||
|
||||
@ -548,8 +545,7 @@ raw_to_impl!(f64, write_be_f64)
|
||||
|
||||
impl RawToSql for Timespec {
|
||||
fn raw_to_sql<W: Writer>(&self, w: &mut W) -> PostgresResult<()> {
|
||||
let t = (self.sec - TIME_SEC_CONVERSION) * USEC_PER_SEC
|
||||
+ self.nsec as i64 / NSEC_PER_USEC;
|
||||
let t = (self.sec - TIME_SEC_CONVERSION) * USEC_PER_SEC + self.nsec as i64 / NSEC_PER_USEC;
|
||||
Ok(try_pg!(w.write_be_i64(t)))
|
||||
}
|
||||
}
|
||||
@ -557,22 +553,19 @@ impl RawToSql for Timespec {
|
||||
macro_rules! to_range_impl(
|
||||
($t:ty) => (
|
||||
impl RawToSql for Range<$t> {
|
||||
fn raw_to_sql<W: Writer>(&self, buf: &mut W)
|
||||
-> PostgresResult<()> {
|
||||
fn raw_to_sql<W: Writer>(&self, buf: &mut W) -> PostgresResult<()> {
|
||||
let mut tag = 0;
|
||||
if self.is_empty() {
|
||||
tag |= RANGE_EMPTY;
|
||||
} else {
|
||||
match self.lower() {
|
||||
None => tag |= RANGE_LOWER_UNBOUNDED,
|
||||
Some(&RangeBound { type_: Inclusive, .. }) =>
|
||||
tag |= RANGE_LOWER_INCLUSIVE,
|
||||
Some(&RangeBound { type_: Inclusive, .. }) => tag |= RANGE_LOWER_INCLUSIVE,
|
||||
_ => {}
|
||||
}
|
||||
match self.upper() {
|
||||
None => tag |= RANGE_UPPER_UNBOUNDED,
|
||||
Some(&RangeBound { type_: Inclusive, .. }) =>
|
||||
tag |= RANGE_UPPER_INCLUSIVE,
|
||||
Some(&RangeBound { type_: Inclusive, .. }) => tag |= RANGE_UPPER_INCLUSIVE,
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
@ -619,8 +612,7 @@ impl RawToSql for Json {
|
||||
macro_rules! to_option_impl(
|
||||
($($oid:pat)|+, $t:ty) => (
|
||||
impl ToSql for Option<$t> {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
check_types!($($oid)|+, ty)
|
||||
|
||||
match *self {
|
||||
@ -635,8 +627,7 @@ macro_rules! to_option_impl(
|
||||
macro_rules! to_option_impl_lifetime(
|
||||
($($oid:pat)|+, $t:ty) => (
|
||||
impl<'a> ToSql for Option<$t> {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
check_types!($($oid)|+, ty)
|
||||
|
||||
match *self {
|
||||
@ -651,8 +642,7 @@ macro_rules! to_option_impl_lifetime(
|
||||
macro_rules! to_raw_to_impl(
|
||||
($($oid:ident)|+, $t:ty) => (
|
||||
impl ToSql for $t {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
check_types!($($oid)|+, ty)
|
||||
|
||||
let mut writer = MemWriter::new();
|
||||
@ -680,8 +670,7 @@ to_raw_to_impl!(PgInt8Range, Range<i64>)
|
||||
to_raw_to_impl!(PgTsRange | PgTstzRange, Range<Timespec>)
|
||||
|
||||
impl<'a> ToSql for &'a str {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
check_types!(PgVarchar | PgText | PgCharN | PgName, ty)
|
||||
Ok((Text, Some(Vec::from_slice(self.as_bytes()))))
|
||||
}
|
||||
@ -690,8 +679,7 @@ impl<'a> ToSql for &'a str {
|
||||
to_option_impl_lifetime!(PgVarchar | PgText | PgCharN | PgName, &'a str)
|
||||
|
||||
impl<'a> ToSql for &'a [u8] {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
check_types!(PgByteA, ty)
|
||||
Ok((Binary, Some(Vec::from_slice(*self))))
|
||||
}
|
||||
@ -704,8 +692,7 @@ to_raw_to_impl!(PgTimestamp | PgTimestampTZ, Timespec)
|
||||
macro_rules! to_array_impl(
|
||||
($($oid:ident)|+, $t:ty) => (
|
||||
impl ToSql for ArrayBase<Option<$t>> {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
check_types!($($oid)|+, ty)
|
||||
let mut buf = MemWriter::new();
|
||||
|
||||
@ -755,11 +742,9 @@ to_array_impl!(PgInt8RangeArray, Range<i64>)
|
||||
to_array_impl!(PgJsonArray, Json)
|
||||
|
||||
impl ToSql for HashMap<String, Option<String>> {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
match *ty {
|
||||
PgUnknownType { name: ref name, .. }
|
||||
if "hstore" == name.as_slice() => {}
|
||||
PgUnknownType { name: ref name, .. } if "hstore" == name.as_slice() => {}
|
||||
_ => return Err(PgWrongType(ty.clone()))
|
||||
}
|
||||
|
||||
@ -785,11 +770,9 @@ impl ToSql for HashMap<String, Option<String>> {
|
||||
}
|
||||
|
||||
impl ToSql for Option<HashMap<String, Option<String>>> {
|
||||
fn to_sql(&self, ty: &PostgresType)
|
||||
-> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
fn to_sql(&self, ty: &PostgresType) -> PostgresResult<(Format, Option<Vec<u8>>)> {
|
||||
match *ty {
|
||||
PgUnknownType { name: ref name, .. }
|
||||
if "hstore" == name.as_slice() => {}
|
||||
PgUnknownType { name: ref name, .. } if "hstore" == name.as_slice() => {}
|
||||
_ => return Err(PgWrongType(ty.clone()))
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user