[−][src]Crate tokio_postgres
An asynchronous, pipelined, PostgreSQL client.
Example
use futures::{Future, Stream}; use tokio_postgres::NoTls; let fut = // Connect to the database tokio_postgres::connect("host=localhost user=postgres", NoTls) .map(|(client, connection)| { // The connection object performs the actual communication with the database, // so spawn it off to run on its own. let connection = connection.map_err(|e| eprintln!("connection error: {}", e)); tokio::spawn(connection); // The client is what you use to make requests. client }) .and_then(|mut client| { // Now we can prepare a simple statement that just returns its parameter. client.prepare("SELECT $1::TEXT") .map(|statement| (client, statement)) }) .and_then(|(mut client, statement)| { // And then execute it, returning a Stream of Rows which we collect into a Vec client.query(&statement, &[&"hello world"]).collect() }) // Now we can check that we got back the same string we sent over. .map(|rows| { let value: &str = rows[0].get(0); assert_eq!(value, "hello world"); }) // And report any errors that happened. .map_err(|e| { eprintln!("error: {}", e); }); // By default, tokio_postgres uses the tokio crate as its runtime. tokio::run(fut);
Behavior
Calling a method like Client::query
on its own does nothing. The associated request is not sent to the database
until the future returned by the method is first polled. Requests are executed in the order that they are first
polled, not in the order that their futures are created.
Pipelining
The client supports pipelined requests. Pipelining can improve performance in use cases in which multiple, independent queries need to be executed. In a traditional workflow, each query is sent to the server after the previous query completes. In contrast, pipelining allows the client to send all of the queries to the server up front, minimizing time spent by one side waiting for the other to finish sending data:
Sequential Pipelined
| Client | Server | | Client | Server |
|----------------|-----------------| |----------------|-----------------|
| send query 1 | | | send query 1 | |
| | process query 1 | | send query 2 | process query 1 |
| receive rows 1 | | | send query 3 | process query 2 |
| send query 2 | | | receive rows 1 | process query 3 |
| | process query 2 | | receive rows 2 | |
| receive rows 2 | | | receive rows 3 | |
| send query 3 | |
| | process query 3 |
| receive rows 3 | |
In both cases, the PostgreSQL server is executing the queries sequentially - pipelining just allows both sides of the connection to work concurrently when possible.
Pipelining happens automatically when futures are polled concurrently (for example, by using the futures join
combinator):
use futures::Future; use tokio_postgres::{Client, Error, Statement}; fn pipelined_prepare( client: &mut Client, ) -> impl Future<Item = (Statement, Statement), Error = Error> { client.prepare("SELECT * FROM foo") .join(client.prepare("INSERT INTO bar (id, name) VALUES ($1, $2)")) }
Runtime
The client works with arbitrary AsyncRead + AsyncWrite
streams. Convenience APIs are provided to handle the
connection process, but these are gated by the runtime
Cargo feature, which is enabled by default. If disabled,
all dependence on the tokio runtime is removed.
Re-exports
pub use crate::config::Config; |
pub use crate::error::Error; |
pub use crate::row::Row; |
pub use crate::row::SimpleQueryRow; |
pub use crate::tls::NoTls; |
Modules
config | Connection configuration. |
error | Errors. |
impls | Futures and stream types used in the crate. |
row | Rows. |
tls | TLS support. |
types | Types. |
Macros
accepts | Generates a simple implementation of |
to_sql_checked | Generates an implementation of |
Structs
Client | An asynchronous PostgreSQL client. |
Column | Information about a column of a Postgres query. |
Connection | A connection to a PostgreSQL database. |
Notification | An asynchronous notification. |
Portal | A portal. |
Socket | The standard stream type used by the crate. |
Statement | A prepared statement. |
TransactionBuilder | A builder type which can wrap a future in a database transaction. |
Enums
AsyncMessage | An asynchronous message from the server. |
SimpleQueryMessage | Message returned by the |
Functions
connect | A convenience function which parses a connection string and connects to the database. |