dnim/rust-postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove out of date README

Browse Source 
Each individual subcrate will gain its own README for display on
crates.io
This commit is contained in:
Steven Fackler 2019-10-21 18:04:58 -07:00
parent a2b3a222ab
commit 286f41d423
1 changed files with 17 additions and 344 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

361
README.md
View File

@ -1,361 +1,34 @@
# Rust-Postgres
[![CircleCI](https://circleci.com/gh/sfackler/rust-postgres.svg?style=shield)](https://circleci.com/gh/sfackler/rust-postgres) [![Latest Version](https://img.shields.io/crates/v/postgres.svg)](https://crates.io/crates/postgres)
[![CircleCI](https://circleci.com/gh/sfackler/rust-postgres.svg?style=shield)](https://circleci.com/gh/sfackler/rust-postgres)
A native PostgreSQL driver for Rust.
PostgreSQL support for Rust.
## postgres [![Latest Version](https://img.shields.io/crates/v/postgres.svg)](https://crates.io/crates/postgres)
[Documentation](https://docs.rs/postgres)
You can integrate Rust-Postgres into your project through the [releases on crates.io](https://crates.io/crates/postgres):
```toml
[dependencies]
postgres = "0.15"
```
A native, synchronous PostgreSQL client.
## Overview
Rust-Postgres is a pure-Rust frontend for the popular PostgreSQL database.
```rust
extern crate postgres;
## tokio-postgres [![Latest Version](https://img.shields.io/crates/v/tokio-postgres.svg)](https://crates.io/crates/tokio-postgres)
use postgres::{Connection, TlsMode};
[Documentation](https://docs.rs/tokio-postgres)
struct Person {
id: i32,
name: String,
data: Option<Vec<u8>>,
}
A native, asynchronous PostgreSQL client.
fn main() {
let conn = Connection::connect("postgres://postgres@localhost:5433", TlsMode::None).unwrap();
conn.execute("CREATE TABLE person (
id SERIAL PRIMARY KEY,
name VARCHAR NOT NULL,
data BYTEA
)", &[]).unwrap();
let me = Person {
id: 0,
name: "Steven".to_string(),
data: None,
};
conn.execute("INSERT INTO person (name, data) VALUES ($1, $2)",
&[&me.name, &me.data]).unwrap();
for row in &conn.query("SELECT id, name, data FROM person", &[]).unwrap() {
let person = Person {
id: row.get(0),
name: row.get(1),
data: row.get(2),
};
println!("Found person {}: {}", person.id, person.name);
}
}
```
## postgres-types [![Latest Version](https://img.shields.io/crates/v/postgres-types.svg)](https://crates.io/crates/postgres-types)
## Requirements
* **Rust** - Rust-Postgres is developed against the 1.18 release of Rust
available on http://www.rust-lang.org. It should also compile against more
recent releases.
[Documentation](https://docs.rs/postgres-types)
* **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.
Conversions between Rust and Postgres types.
## Usage
## postgres-native-tls [![Latest Version](https://img.shields.io/crates/v/postgres-native-tls.svg)](https://crates.io/crates/postgres-native-tls)
### Connecting
Connect to a Postgres server using the standard URI format:
```rust
let conn = Connection::connect("postgres://user:pass@host:port/database?arg1=val1&arg2=val2",
TlsMode::None)?;
```
`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.
[Documentation](https://docs.rs/postgres-native-tls)
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. If Postgres
stored its socket files in `/run/postgres`, the connection would then look like:
```rust
let conn = Connection::connect("postgres://postgres@%2Frun%2Fpostgres", TlsMode::None)?;
```
Paths which contain non-UTF8 characters can be handled in a different manner;
see the documentation for details.
TLS support for postgres and tokio-postgres via native-tls.
### Querying
SQL statements can be executed with the `query` and `execute` methods. Both
methods take a query string as well as a slice of parameters to bind to the
query. The `i`th query parameter is specified in the query string by `$i`. Note
that query parameters are 1-indexed rather than the more common 0-indexing.
## postgres-openssl [![Latest Version](https://img.shields.io/crates/v/postgres-openssl.svg)](https://crates.io/crates/postgres-openssl)
`execute` returns the number of rows affected by the query (or 0 if not
applicable):
```rust
let updates = conn.execute("UPDATE foo SET bar = $1 WHERE baz = $2", &[&1i32, &"biz"])?;
println!("{} rows were updated", updates);
```
[Documentation](https://docs.rs/postgres-openssl)
`query` returns an iterable object holding 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.
```rust
for row in &conn.query("SELECT bar, baz FROM foo WHERE buz = $1", &[&1i32])? {
let bar: i32 = row.get(0);
let baz: String = row.get("baz");
println!("bar: {}, baz: {}", bar, baz);
}
```
### Statement Preparation
If the same statement will be executed repeatedly (possibly with different
parameters), explicitly preparing it can improve performance:
```rust
let stmt = conn.prepare("UPDATE foo SET bar = $1 WHERE baz = $2")?;
for (bar, baz) in updates {
stmt.execute(&[bar, baz])?;
}
```
### 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:
```rust
let trans = conn.transaction()?;
trans.execute(...)?;
let stmt = trans.prepare(...)?;
// ...
trans.commit()?;
```
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:
<table>
<thead>
<tr>
<th>Rust Type</th>
<th>Postgres Type</th>
</tr>
</thead>
<tbody>
<tr>
<td>bool</td>
<td>BOOL</td>
</tr>
<tr>
<td>i8</td>
<td>"char"</td>
</tr>
<tr>
<td>i16</td>
<td>SMALLINT, SMALLSERIAL</td>
</tr>
<tr>
<td>i32</td>
<td>INT, SERIAL</td>
</tr>
<tr>
<td>u32</td>
<td>OID</td>
</tr>
<tr>
<td>i64</td>
<td>BIGINT, BIGSERIAL</td>
</tr>
<tr>
<td>f32</td>
<td>REAL</td>
</tr>
<tr>
<td>f64</td>
<td>DOUBLE PRECISION</td>
</tr>
<tr>
<td>str/String</td>
<td>VARCHAR, CHAR(n), TEXT, CITEXT, NAME</td>
</tr>
<tr>
<td>[u8]/Vec&lt;u8&gt;</td>
<td>BYTEA</td>
</tr>
<tr>
<td>
postgres::types::Json
and
<a href="https://github.com/serde-rs/json">serde_json::Value</a>
(<a href="#optional-features">optional</a>)
</td>
<td>JSON, JSONB</td>
</tr>
<tr>
<td>
<a href="https://github.com/rust-lang-deprecated/time">time::Timespec</a>
and
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::NaiveDateTime</a>
(<a href="#optional-features">optional</a>)
</td>
<td>TIMESTAMP</td>
</tr>
<tr>
<td>
<a href="https://github.com/rust-lang-deprecated/time">time::Timespec</a>,
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::DateTime&lt;Utc&gt;</a>,
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::DateTime&lt;Local&gt;</a>,
and
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::DateTime&lt;FixedOffset&gt;</a>
(<a href="#optional-features">optional</a>)
</td>
<td>TIMESTAMP WITH TIME ZONE</td>
</tr>
<tr>
<td>
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::NaiveDate</a>
(<a href="#optional-features">optional</a>)
</td>
<td>DATE</td>
</tr>
<tr>
<td>
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::NaiveTime</a>
(<a href="#optional-features">optional</a>)
</td>
<td>TIME</td>
</tr>
<tr>
<td>
<a href="https://github.com/rust-lang-nursery/uuid">uuid::Uuid</a>
(<a href="#optional-features">optional</a>)
</td>
<td>UUID</td>
</tr>
<tr>
<td>
<a href="https://github.com/contain-rs/bit-vec">bit_vec::BitVec</a>
(<a href="#optional-features">optional</a>)
</td>
<td>BIT, VARBIT</td>
</tr>
<tr>
<td>HashMap&lt;String, Option&lt;String&gt;&gt;</td>
<td>HSTORE</td>
</tr>
<tr>
<td>
<a href="https://github.com/abaumhauer/eui48">eui48::MacAddress</a>
(<a href="#optional-features">optional</a>)
</td>
<td>MACADDR</td>
</tr
<tr>
<td>
<a href="https://github.com/georust/rust-geo">geo::Point&lt;f64&gt;</a>
(<a href="#optional-features">optional</a>)
</td>
<td>POINT</td>
</tr>
<tr>
<td>
<a href="https://github.com/georust/rust-geo">geo::Bbox&lt;f64&gt;</a>
(<a href="#optional-features">optional</a>)
</td>
<td>BOX</td>
</tr>
<tr>
<td>
<a href="https://github.com/georust/rust-geo">geo::LineString&lt;f64&gt;</a>
(<a href="#optional-features">optional</a>)
</td>
<td>PATH</td>
</tr>
</tbody>
</table>
`Option<T>` implements `FromSql` where `T: FromSql` and `ToSql` where `T:
ToSql`, and represents nullable Postgres values.
`&[T]` and `Vec<T>` implement `ToSql` where `T: ToSql`, and `Vec<T>`
additionally implements `FromSql` where `T: FromSql`, which represent
one-dimensional Postgres arrays.
More conversions can be defined by implementing the `ToSql` and `FromSql`
traits.
The [postgres-derive](https://github.com/sfackler/rust-postgres-derive)
crate will synthesize `ToSql` and `FromSql` implementations for enum, domain,
and composite Postgres types.
Full support for array types is located in the
[postgres-array](https://github.com/sfackler/rust-postgres-array) crate.
Support for range types is located in the
[postgres-range](https://github.com/sfackler/rust-postgres-range) crate.
Support for the large object API is located in the
[postgres-large-object](https://github.com/sfackler/rust-postgres-large-object)
crate.
## Optional features
### UUID type
[UUID](http://www.postgresql.org/docs/9.4/static/datatype-uuid.html) support is
provided optionally by the `with-uuid` feature, which adds `ToSql` and `FromSql`
implementations for `uuid`'s `Uuid` type. Requires `uuid` version 0.5.
### JSON/JSONB types
[JSON and JSONB](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
support is provided optionally by the `with-serde_json-1` feature, which adds
`ToSql` and `FromSql` implementations for `serde_json`'s `Value` type,
as well as adding a generic `Json<T>` type with those same implementations.
Requires `serde_json` version 1.0.
### TIMESTAMP/TIMESTAMPTZ/DATE/TIME types
[Date and Time](http://www.postgresql.org/docs/9.1/static/datatype-datetime.html)
support is provided optionally by the `with-time` feature, which adds `ToSql`
and `FromSql` implementations for `time`'s `Timespec` type, or the `with-chrono`
feature, which adds `ToSql` and `FromSql` implementations for `chrono`'s
`DateTime`, `NaiveDateTime`, `NaiveDate` and `NaiveTime` types. Requires `time` version 0.1.14.
### BIT/VARBIT types
[BIT and VARBIT](http://www.postgresql.org/docs/9.4/static/datatype-bit.html)
support is provided optionally by the `with-bit-vec` feature, which adds `ToSql`
and `FromSql` implementations for `bit-vec`'s `BitVec` type. Requires `bit-vec` version 0.4.
### MACADDR type
[MACADDR](http://www.postgresql.org/docs/9.4/static/datatype-net-types.html#DATATYPE-MACADDR)
support is provided optionally by the `with-eui48` feature, which adds `ToSql`
and `FromSql` implementations for `eui48`'s `MacAddress` type. Requires `eui48` version 0.3.
### POINT type
[POINT](https://www.postgresql.org/docs/9.4/static/datatype-geometric.html#AEN6799)
support is provided optionally by the `with-geo` feature, which adds `ToSql` and `FromSql` implementations for `geo`'s `Point` type. Requires `geo` version 0.4.
### BOX type
[BOX](https://www.postgresql.org/docs/9.4/static/datatype-geometric.html#AEN6883)
support is provided optionally by the `with-geo` feature, which adds `ToSql` and `FromSql` implementations for `geo`'s `Bbox` type. Requires `geo` version 0.4.
### PATH type
[PATH](https://www.postgresql.org/docs/9.4/static/datatype-geometric.html#AEN6912)
support is provided optionally by the `with-geo` feature, which adds `ToSql` and `FromSql` implementations for `geo`'s `LineString` type.
Paths converted from LineString are always treated as "open" paths. Requires `geo` version 0.4. Use the
[pclose](https://www.postgresql.org/docs/8.2/static/functions-geometry.html#FUNCTIONS-GEOMETRY-FUNC-TABLE)
geometric function to insert a closed path.
## See Also
- [r2d2-postgres](https://github.com/sfackler/r2d2-postgres) for connection pool support.
TLS support for postgres and tokio-postgres via openssl.