Skip to content

Commit 286f41d

Browse files
sfacklersfackler
committed
Remove out of date README
Each individual subcrate will gain its own README for display on crates.io
1 parent a2b3a22 commit 286f41d

File tree

1 file changed

+17
-344
lines changed

1 file changed

+17
-344
lines changed

‎README.md

Lines changed: 17 additions & 344 deletions
Original file line numberDiff line numberDiff line change
@@ -1,361 +1,34 @@
11
# Rust-Postgres
2-
[![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)
2+
[![CircleCI](https://circleci.com/gh/sfackler/rust-postgres.svg?style=shield)](https://circleci.com/gh/sfackler/rust-postgres)
33

4-
A native PostgreSQL driver for Rust.
4+
PostgreSQL support for Rust.
55

6-
[Documentation](https://docs.rs/postgres)
7-
8-
You can integrate Rust-Postgres into your project through the [releases on crates.io](https://crates.io/crates/postgres):
9-
```toml
10-
[dependencies]
11-
postgres = "0.15"
12-
```
13-
14-
## Overview
15-
Rust-Postgres is a pure-Rust frontend for the popular PostgreSQL database.
16-
```rust
17-
extern crate postgres;
18-
19-
use postgres::{Connection, TlsMode};
20-
21-
struct Person {
22-
id: i32,
23-
name: String,
24-
data: Option<Vec<u8>>,
25-
}
26-
27-
fn main() {
28-
let conn = Connection::connect("postgres://postgres@localhost:5433", TlsMode::None).unwrap();
29-
conn.execute("CREATE TABLE person (
30-
id SERIAL PRIMARY KEY,
31-
name VARCHAR NOT NULL,
32-
data BYTEA
33-
)", &[]).unwrap();
34-
let me = Person {
35-
id: 0,
36-
name: "Steven".to_string(),
37-
data: None,
38-
};
39-
conn.execute("INSERT INTO person (name, data) VALUES ($1, $2)",
40-
&[&me.name, &me.data]).unwrap();
41-
for row in &conn.query("SELECT id, name, data FROM person", &[]).unwrap() {
42-
let person = Person {
43-
id: row.get(0),
44-
name: row.get(1),
45-
data: row.get(2),
46-
};
47-
println!("Found person {}: {}", person.id, person.name);
48-
}
49-
}
50-
```
51-
52-
## Requirements
53-
* **Rust** - Rust-Postgres is developed against the 1.18 release of Rust
54-
available on http://www.rust-lang.org. It should also compile against more
55-
recent releases.
56-
57-
* **PostgreSQL 7.4 or later** - Rust-Postgres speaks version 3 of the
58-
PostgreSQL protocol, which corresponds to versions 7.4 and later. If your
59-
version of Postgres was compiled in the last decade, you should be okay.
60-
61-
## Usage
62-
63-
### Connecting
64-
Connect to a Postgres server using the standard URI format:
65-
```rust
66-
let conn = Connection::connect("postgres://user:pass@host:port/database?arg1=val1&arg2=val2",
67-
TlsMode::None)?;
68-
```
69-
`pass` may be omitted if not needed. `port` defaults to `5432` and `database`
70-
defaults to the value of `user` if not specified. The driver supports `trust`,
71-
`password`, and `md5` authentication.
72-
73-
Unix domain sockets can be used as well. The `host` portion of the URI should
74-
be set to the absolute path to the directory containing the socket file. Since
75-
`/` is a reserved character in URLs, the path should be URL encoded. If Postgres
76-
stored its socket files in `/run/postgres`, the connection would then look like:
77-
```rust
78-
let conn = Connection::connect("postgres://postgres@%2Frun%2Fpostgres", TlsMode::None)?;
79-
```
80-
Paths which contain non-UTF8 characters can be handled in a different manner;
81-
see the documentation for details.
82-
83-
### Querying
84-
SQL statements can be executed with the `query` and `execute` methods. Both
85-
methods take a query string as well as a slice of parameters to bind to the
86-
query. The `i`th query parameter is specified in the query string by `$i`. Note
87-
that query parameters are 1-indexed rather than the more common 0-indexing.
88-
89-
`execute` returns the number of rows affected by the query (or 0 if not
90-
applicable):
91-
```rust
92-
let updates = conn.execute("UPDATE foo SET bar = $1 WHERE baz = $2", &[&1i32, &"biz"])?;
93-
println!("{} rows were updated", updates);
94-
```
95-
96-
`query` returns an iterable object holding the rows returned from the database.
97-
The fields in a row can be accessed either by their indices or their column
98-
names, though access by index is more efficient. Unlike statement parameters,
99-
result columns are zero-indexed.
100-
```rust
101-
for row in &conn.query("SELECT bar, baz FROM foo WHERE buz = $1", &[&1i32])? {
102-
let bar: i32 = row.get(0);
103-
let baz: String = row.get("baz");
104-
println!("bar: {}, baz: {}", bar, baz);
105-
}
106-
```
107-
108-
### Statement Preparation
109-
If the same statement will be executed repeatedly (possibly with different
110-
parameters), explicitly preparing it can improve performance:
111-
112-
```rust
113-
let stmt = conn.prepare("UPDATE foo SET bar = $1 WHERE baz = $2")?;
114-
for (bar, baz) in updates {
115-
stmt.execute(&[bar, baz])?;
116-
}
117-
```
118-
119-
### Transactions
120-
The `transaction` method will start a new transaction. It returns a
121-
`Transaction` object which has the functionality of a
122-
`Connection` as well as methods to control the result of the
123-
transaction:
124-
```rust
125-
let trans = conn.transaction()?;
6+
## postgres [![Latest Version](https://img.shields.io/crates/v/postgres.svg)](https://crates.io/crates/postgres)
1267

127-
trans.execute(...)?;
128-
let stmt = trans.prepare(...)?;
129-
// ...
130-
131-
trans.commit()?;
132-
```
133-
The transaction will be active until the `Transaction` object falls out of
134-
scope. A transaction will roll back by default. Nested transactions are
135-
supported via savepoints.
136-
137-
### Type Correspondence
138-
Rust-Postgres enforces a strict correspondence between Rust types and Postgres
139-
types. The driver currently supports the following conversions:
140-
141-
<table>
142-
<thead>
143-
<tr>
144-
<th>Rust Type</th>
145-
<th>Postgres Type</th>
146-
</tr>
147-
</thead>
148-
<tbody>
149-
<tr>
150-
<td>bool</td>
151-
<td>BOOL</td>
152-
</tr>
153-
<tr>
154-
<td>i8</td>
155-
<td>"char"</td>
156-
</tr>
157-
<tr>
158-
<td>i16</td>
159-
<td>SMALLINT, SMALLSERIAL</td>
160-
</tr>
161-
<tr>
162-
<td>i32</td>
163-
<td>INT, SERIAL</td>
164-
</tr>
165-
<tr>
166-
<td>u32</td>
167-
<td>OID</td>
168-
</tr>
169-
<tr>
170-
<td>i64</td>
171-
<td>BIGINT, BIGSERIAL</td>
172-
</tr>
173-
<tr>
174-
<td>f32</td>
175-
<td>REAL</td>
176-
</tr>
177-
<tr>
178-
<td>f64</td>
179-
<td>DOUBLE PRECISION</td>
180-
</tr>
181-
<tr>
182-
<td>str/String</td>
183-
<td>VARCHAR, CHAR(n), TEXT, CITEXT, NAME</td>
184-
</tr>
185-
<tr>
186-
<td>[u8]/Vec&lt;u8&gt;</td>
187-
<td>BYTEA</td>
188-
</tr>
189-
<tr>
190-
<td>
191-
postgres::types::Json
192-
and
193-
<a href="https://github.com/serde-rs/json">serde_json::Value</a>
194-
(<a href="#optional-features">optional</a>)
195-
</td>
196-
<td>JSON, JSONB</td>
197-
</tr>
198-
<tr>
199-
<td>
200-
<a href="https://github.com/rust-lang-deprecated/time">time::Timespec</a>
201-
and
202-
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::NaiveDateTime</a>
203-
(<a href="#optional-features">optional</a>)
204-
</td>
205-
<td>TIMESTAMP</td>
206-
</tr>
207-
<tr>
208-
<td>
209-
<a href="https://github.com/rust-lang-deprecated/time">time::Timespec</a>,
210-
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::DateTime&lt;Utc&gt;</a>,
211-
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::DateTime&lt;Local&gt;</a>,
212-
and
213-
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::DateTime&lt;FixedOffset&gt;</a>
214-
(<a href="#optional-features">optional</a>)
215-
</td>
216-
<td>TIMESTAMP WITH TIME ZONE</td>
217-
</tr>
218-
<tr>
219-
<td>
220-
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::NaiveDate</a>
221-
(<a href="#optional-features">optional</a>)
222-
</td>
223-
<td>DATE</td>
224-
</tr>
225-
<tr>
226-
<td>
227-
<a href="https://github.com/lifthrasiir/rust-chrono">chrono::NaiveTime</a>
228-
(<a href="#optional-features">optional</a>)
229-
</td>
230-
<td>TIME</td>
231-
</tr>
232-
<tr>
233-
<td>
234-
<a href="https://github.com/rust-lang-nursery/uuid">uuid::Uuid</a>
235-
(<a href="#optional-features">optional</a>)
236-
</td>
237-
<td>UUID</td>
238-
</tr>
239-
<tr>
240-
<td>
241-
<a href="https://github.com/contain-rs/bit-vec">bit_vec::BitVec</a>
242-
(<a href="#optional-features">optional</a>)
243-
</td>
244-
<td>BIT, VARBIT</td>
245-
</tr>
246-
<tr>
247-
<td>HashMap&lt;String, Option&lt;String&gt;&gt;</td>
248-
<td>HSTORE</td>
249-
</tr>
250-
<tr>
251-
<td>
252-
<a href="https://github.com/abaumhauer/eui48">eui48::MacAddress</a>
253-
(<a href="#optional-features">optional</a>)
254-
</td>
255-
<td>MACADDR</td>
256-
</tr
257-
<tr>
258-
<td>
259-
<a href="https://github.com/georust/rust-geo">geo::Point&lt;f64&gt;</a>
260-
(<a href="#optional-features">optional</a>)
261-
</td>
262-
<td>POINT</td>
263-
</tr>
264-
<tr>
265-
<td>
266-
<a href="https://github.com/georust/rust-geo">geo::Bbox&lt;f64&gt;</a>
267-
(<a href="#optional-features">optional</a>)
268-
</td>
269-
<td>BOX</td>
270-
</tr>
271-
<tr>
272-
<td>
273-
<a href="https://github.com/georust/rust-geo">geo::LineString&lt;f64&gt;</a>
274-
(<a href="#optional-features">optional</a>)
275-
</td>
276-
<td>PATH</td>
277-
</tr>
278-
</tbody>
279-
</table>
280-
281-
`Option<T>` implements `FromSql` where `T: FromSql` and `ToSql` where `T:
282-
ToSql`, and represents nullable Postgres values.
283-
284-
`&[T]` and `Vec<T>` implement `ToSql` where `T: ToSql`, and `Vec<T>`
285-
additionally implements `FromSql` where `T: FromSql`, which represent
286-
one-dimensional Postgres arrays.
287-
288-
More conversions can be defined by implementing the `ToSql` and `FromSql`
289-
traits.
290-
291-
The [postgres-derive](https://github.com/sfackler/rust-postgres-derive)
292-
crate will synthesize `ToSql` and `FromSql` implementations for enum, domain,
293-
and composite Postgres types.
294-
295-
Full support for array types is located in the
296-
[postgres-array](https://github.com/sfackler/rust-postgres-array) crate.
297-
298-
Support for range types is located in the
299-
[postgres-range](https://github.com/sfackler/rust-postgres-range) crate.
300-
301-
Support for the large object API is located in the
302-
[postgres-large-object](https://github.com/sfackler/rust-postgres-large-object)
303-
crate.
304-
305-
## Optional features
306-
307-
### UUID type
308-
309-
[UUID](http://www.postgresql.org/docs/9.4/static/datatype-uuid.html) support is
310-
provided optionally by the `with-uuid` feature, which adds `ToSql` and `FromSql`
311-
implementations for `uuid`'s `Uuid` type. Requires `uuid` version 0.5.
312-
313-
### JSON/JSONB types
314-
315-
[JSON and JSONB](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
316-
support is provided optionally by the `with-serde_json-1` feature, which adds
317-
`ToSql` and `FromSql` implementations for `serde_json`'s `Value` type,
318-
as well as adding a generic `Json<T>` type with those same implementations.
319-
Requires `serde_json` version 1.0.
320-
321-
### TIMESTAMP/TIMESTAMPTZ/DATE/TIME types
8+
[Documentation](https://docs.rs/postgres)
3229

323-
[Date and Time](http://www.postgresql.org/docs/9.1/static/datatype-datetime.html)
324-
support is provided optionally by the `with-time` feature, which adds `ToSql`
325-
and `FromSql` implementations for `time`'s `Timespec` type, or the `with-chrono`
326-
feature, which adds `ToSql` and `FromSql` implementations for `chrono`'s
327-
`DateTime`, `NaiveDateTime`, `NaiveDate` and `NaiveTime` types. Requires `time` version 0.1.14.
10+
A native, synchronous PostgreSQL client.
32811

329-
### BIT/VARBIT types
12+
## tokio-postgres [![Latest Version](https://img.shields.io/crates/v/tokio-postgres.svg)](https://crates.io/crates/tokio-postgres)
33013

331-
[BIT and VARBIT](http://www.postgresql.org/docs/9.4/static/datatype-bit.html)
332-
support is provided optionally by the `with-bit-vec` feature, which adds `ToSql`
333-
and `FromSql` implementations for `bit-vec`'s `BitVec` type. Requires `bit-vec` version 0.4.
14+
[Documentation](https://docs.rs/tokio-postgres)
33415

335-
### MACADDR type
16+
A native, asynchronous PostgreSQL client.
33617

337-
[MACADDR](http://www.postgresql.org/docs/9.4/static/datatype-net-types.html#DATATYPE-MACADDR)
338-
support is provided optionally by the `with-eui48` feature, which adds `ToSql`
339-
and `FromSql` implementations for `eui48`'s `MacAddress` type. Requires `eui48` version 0.3.
18+
## postgres-types [![Latest Version](https://img.shields.io/crates/v/postgres-types.svg)](https://crates.io/crates/postgres-types)
34019

341-
### POINT type
20+
[Documentation](https://docs.rs/postgres-types)
34221

343-
[POINT](https://www.postgresql.org/docs/9.4/static/datatype-geometric.html#AEN6799)
344-
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.
22+
Conversions between Rust and Postgres types.
34523

346-
### BOX type
24+
## postgres-native-tls [![Latest Version](https://img.shields.io/crates/v/postgres-native-tls.svg)](https://crates.io/crates/postgres-native-tls)
34725

348-
[BOX](https://www.postgresql.org/docs/9.4/static/datatype-geometric.html#AEN6883)
349-
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.
26+
[Documentation](https://docs.rs/postgres-native-tls)
35027

351-
### PATH type
28+
TLS support for postgres and tokio-postgres via native-tls.
35229

353-
[PATH](https://www.postgresql.org/docs/9.4/static/datatype-geometric.html#AEN6912)
354-
support is provided optionally by the `with-geo` feature, which adds `ToSql` and `FromSql` implementations for `geo`'s `LineString` type.
355-
Paths converted from LineString are always treated as "open" paths. Requires `geo` version 0.4. Use the
356-
[pclose](https://www.postgresql.org/docs/8.2/static/functions-geometry.html#FUNCTIONS-GEOMETRY-FUNC-TABLE)
357-
geometric function to insert a closed path.
30+
## postgres-openssl [![Latest Version](https://img.shields.io/crates/v/postgres-openssl.svg)](https://crates.io/crates/postgres-openssl)
35831

359-
## See Also
32+
[Documentation](https://docs.rs/postgres-openssl)
36033

361-
- [r2d2-postgres](https://github.com/sfackler/r2d2-postgres) for connection pool support.
34+
TLS support for postgres and tokio-postgres via openssl.

0 commit comments

Comments
 (0)