diff --git a/README.md b/README.md index 3a7cf7e2..cbe7182c 100644 --- a/README.md +++ b/README.md @@ -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>, -} +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: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Rust TypePostgres Type
boolBOOL
i8"char"
i16SMALLINT, SMALLSERIAL
i32INT, SERIAL
u32OID
i64BIGINT, BIGSERIAL
f32REAL
f64DOUBLE PRECISION
str/StringVARCHAR, CHAR(n), TEXT, CITEXT, NAME
[u8]/Vec<u8>BYTEA
- postgres::types::Json - and - serde_json::Value - (optional) - JSON, JSONB
- time::Timespec - and - chrono::NaiveDateTime - (optional) - TIMESTAMP
- time::Timespec, - chrono::DateTime<Utc>, - chrono::DateTime<Local>, - and - chrono::DateTime<FixedOffset> - (optional) - TIMESTAMP WITH TIME ZONE
- chrono::NaiveDate - (optional) - DATE
- chrono::NaiveTime - (optional) - TIME
- uuid::Uuid - (optional) - UUID
- bit_vec::BitVec - (optional) - BIT, VARBIT
HashMap<String, Option<String>>HSTORE
- eui48::MacAddress - (optional) - MACADDR
- geo::Point<f64> - (optional) - POINT
- geo::Bbox<f64> - (optional) - BOX
- geo::LineString<f64> - (optional) - PATH
- -`Option` implements `FromSql` where `T: FromSql` and `ToSql` where `T: -ToSql`, and represents nullable Postgres values. - -`&[T]` and `Vec` implement `ToSql` where `T: ToSql`, and `Vec` -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` 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.