Reexports and config docs

postgres/src/client.rs

@@ -31,11 +31,11 @@ impl Client {
     }
 
     pub fn prepare(&mut self, query: &str) -> Result<Statement, Error> {
-        self.0.prepare(query).wait().map(Statement)
+        self.0.prepare(query).wait()
     }
 
     pub fn prepare_typed(&mut self, query: &str, types: &[Type]) -> Result<Statement, Error> {
-        self.0.prepare_typed(query, types).wait().map(Statement)
+        self.0.prepare_typed(query, types).wait()
     }
 
     pub fn execute<T>(&mut self, query: &T, params: &[&dyn ToSql]) -> Result<u64, Error>
@@ -43,7 +43,7 @@ impl Client {
         T: ?Sized + ToStatement,
     {
         let statement = query.__statement(self)?;
-        self.0.execute(&statement.0, params).wait()
+        self.0.execute(&statement, params).wait()
     }
 
     pub fn query<T>(&mut self, query: &T, params: &[&dyn ToSql]) -> Result<Vec<Row>, Error>
@@ -62,7 +62,7 @@ impl Client {
         T: ?Sized + ToStatement,
     {
         let statement = query.__statement(self)?;
-        Ok(QueryIter::new(self.0.query(&statement.0, params)))
+        Ok(QueryIter::new(self.0.query(&statement, params)))
     }
 
     pub fn copy_in<T, R>(
@@ -77,7 +77,7 @@ impl Client {
     {
         let statement = query.__statement(self)?;
         self.0
-            .copy_in(&statement.0, params, CopyInStream(reader))
+            .copy_in(&statement, params, CopyInStream(reader))
             .wait()
     }
 
@@ -90,7 +90,7 @@ impl Client {
         T: ?Sized + ToStatement,
     {
         let statement = query.__statement(self)?;
-        let stream = self.0.copy_out(&statement.0, params);
+        let stream = self.0.copy_out(&statement, params);
         CopyOutReader::new(stream)
     }
 

postgres/src/config.rs

@@ -1,3 +1,7 @@
+//! Connection configuration.
+//!
+//! Requires the `runtime` Cargo feature (enabled by default).
+
 use futures::future::Executor;
 use futures::sync::oneshot;
 use futures::Future;
@@ -7,14 +11,89 @@ use std::path::Path;
 use std::str::FromStr;
 use std::sync::Arc;
 use std::time::Duration;
-use tokio_postgres::config::{SslMode, TargetSessionAttrs};
 use tokio_postgres::tls::{MakeTlsConnect, TlsConnect};
 use tokio_postgres::{Error, Socket};
 
+#[doc(inline)]
+use tokio_postgres::config::{SslMode, TargetSessionAttrs};
+
 use crate::{Client, RUNTIME};
 
 type DynExecutor = dyn Executor<Box<dyn Future<Item = (), Error = ()> + Send>> + Sync + Send;
 
+/// Connection configuration.
+///
+/// Configuration can be parsed from libpq-style connection strings. These strings come in two formats:
+///
+/// # Key-Value
+///
+/// This format consists of space-separated key-value pairs. Values which are either the empty string or contain
+/// whitespace should be wrapped in `'`. `'` and `\` characters should be backslash-escaped.
+///
+/// ## Keys
+///
+/// * `user` - The username to authenticate with. Required.
+/// * `password` - The password to authenticate with.
+/// * `dbname` - The name of the database to connect to. Defaults to the username.
+/// * `options` - Command line options used to configure the server.
+/// * `application_name` - Sets the `application_name` parameter on the server.
+/// * `sslmode` - Controls usage of TLS. If set to `disable`, TLS will not be used. If set to `prefer`, TLS will be used
+///     if available, but not used otherwise. If set to `require`, TLS will be forced to be used. Defaults to `prefer`.
+/// * `host` - The host to connect to. On Unix platforms, if the host starts with a `/` character it is treated as the
+///     path to the directory containing Unix domain sockets. Otherwise, it is treated as a hostname. Multiple hosts
+///     can be specified, separated by commas. Each host will be tried in turn when connecting. Required if connecting
+///     with the `connect` method.
+/// * `port` - The port to connect to. Multiple ports can be specified, separated by commas. The number of ports must be
+///     either 1, in which case it will be used for all hosts, or the same as the number of hosts. Defaults to 5432 if
+///     omitted or the empty string.
+/// * `connect_timeout` - The time limit in seconds applied to each socket-level connection attempt. Note that hostnames
+///     can resolve to multiple IP addresses, and this limit is applied to each address. Defaults to no timeout.
+/// * `keepalives` - Controls the use of TCP keepalive. A value of 0 disables keepalive and nonzero integers enable it.
+///     This option is ignored when connecting with Unix sockets. Defaults to on.
+/// * `keepalives_idle` - The number of seconds of inactivity after which a keepalive message is sent to the server.
+///     This option is ignored when connecting with Unix sockets. Defaults to 2 hours.
+/// * `target_session_attrs` - Specifies requirements of the session. If set to `read-write`, the client will check that
+///     the `transaction_read_write` session parameter is set to `on`. This can be used to connect to the primary server
+///     in a database cluster as opposed to the secondary read-only mirrors. Defaults to `all`.
+///
+/// ## Examples
+///
+/// ```not_rust
+/// host=localhost user=postgres connect_timeout=10 keepalives=0
+/// ```
+///
+/// ```not_rust
+/// host=/var/lib/postgresql,localhost port=1234 user=postgres password='password with spaces'
+/// ```
+///
+/// ```not_rust
+/// host=host1,host2,host3 port=1234,,5678 user=postgres target_session_attrs=read-write
+/// ```
+///
+/// # Url
+///
+/// This format resembles a URL with a scheme of either `postgres://` or `postgresql://`. All components are optional,
+/// and the format accept query parameters for all of the key-value pairs described in the section above. Multiple
+/// host/port pairs can be comma-separated. Unix socket paths in the host section of the URL should be percent-encoded,
+/// as the path component of the URL specifies the database name.
+///
+/// ## Examples
+///
+/// ```not_rust
+/// postgresql://user@localhost
+/// ```
+///
+/// ```not_rust
+/// postgresql://user:password@%2Fvar%2Flib%2Fpostgresql/mydb?connect_timeout=10
+/// ```
+///
+/// ```not_rust
+/// postgresql://user@host1:1234,host2,host3:5678?target_session_attrs=read-write
+/// ```
+///
+/// ```not_rust
+/// postgresql:///mydb?user=user&host=/var/lib/postgresql
+/// ```
 #[derive(Clone)]
 pub struct Config {
     config: tokio_postgres::Config,
@@ -37,6 +116,7 @@ impl Default for Config {
 }
 
 impl Config {
+    /// Creates a new configuration.
     pub fn new() -> Config {
         Config {
             config: tokio_postgres::Config::new(),
@@ -44,11 +124,15 @@ impl Config {
         }
     }
 
+    /// Sets the user to authenticate with.
+    ///
+    /// Required.
     pub fn user(&mut self, user: &str) -> &mut Config {
         self.config.user(user);
         self
     }
 
+    /// Sets the password to authenticate with.
     pub fn password<T>(&mut self, password: T) -> &mut Config
     where
         T: AsRef<[u8]>,
@@ -57,31 +141,46 @@ impl Config {
         self
     }
 
+    /// Sets the name of the database to connect to.
+    ///
+    /// Defaults to the user.
     pub fn dbname(&mut self, dbname: &str) -> &mut Config {
         self.config.dbname(dbname);
         self
     }
 
+    /// Sets command line options used to configure the server.
     pub fn options(&mut self, options: &str) -> &mut Config {
         self.config.options(options);
         self
     }
 
+    /// Sets the value of the `application_name` runtime parameter.
     pub fn application_name(&mut self, application_name: &str) -> &mut Config {
         self.config.application_name(application_name);
         self
     }
 
+    /// Sets the SSL configuration.
+    ///
+    /// Defaults to `prefer`.
     pub fn ssl_mode(&mut self, ssl_mode: SslMode) -> &mut Config {
         self.config.ssl_mode(ssl_mode);
         self
     }
 
+    /// Adds a host to the configuration.
+    ///
+    /// Multiple hosts can be specified by calling this method multiple times, and each will be tried in order. On Unix
+    /// systems, a host starting with a `/` is interpreted as a path to a directory containing Unix domain sockets.
     pub fn host(&mut self, host: &str) -> &mut Config {
         self.config.host(host);
         self
     }
 
+    /// Adds a Unix socket host to the configuration.
+    ///
+    /// Unlike `host`, this method allows non-UTF8 paths.
     #[cfg(unix)]
     pub fn host_path<T>(&mut self, host: T) -> &mut Config
     where
@@ -91,26 +190,45 @@ impl Config {
         self
     }
 
+    /// Adds a port to the configuration.
+    ///
+    /// Multiple ports can be specified by calling this method multiple times. There must either be no ports, in which
+    /// case the default of 5432 is used, a single port, in which it is used for all hosts, or the same number of ports
+    /// as hosts.
     pub fn port(&mut self, port: u16) -> &mut Config {
         self.config.port(port);
         self
     }
 
+    /// Sets the timeout applied to socket-level connection attempts.
+    ///
+    /// Note that hostnames can resolve to multiple IP addresses, and this timeout will apply to each address of each
+    /// host separately. Defaults to no limit.
     pub fn connect_timeout(&mut self, connect_timeout: Duration) -> &mut Config {
         self.config.connect_timeout(connect_timeout);
         self
     }
 
+    /// Controls the use of TCP keepalive.
+    ///
+    /// This is ignored for Unix domain socket connections. Defaults to `true`.
     pub fn keepalives(&mut self, keepalives: bool) -> &mut Config {
         self.config.keepalives(keepalives);
         self
     }
 
+    /// Sets the amount of idle time before a keepalive packet is sent on the connection.
+    ///
+    /// This is ignored for Unix domain sockets, or if the `keepalives` option is disabled. Defaults to 2 hours.
     pub fn keepalives_idle(&mut self, keepalives_idle: Duration) -> &mut Config {
         self.config.keepalives_idle(keepalives_idle);
         self
     }
 
+    /// Sets the requirements of the session.
+    ///
+    /// This can be used to connect to the primary server in a clustered database rather than one of the read-only
+    /// secondary servers. Defaults to `Any`.
     pub fn target_session_attrs(
         &mut self,
         target_session_attrs: TargetSessionAttrs,
@@ -119,6 +237,9 @@ impl Config {
         self
     }
 
+    /// Sets the executor used to run the connection futures.
+    ///
+    /// Defaults to a postgres-specific tokio `Runtime`.
     pub fn executor<E>(&mut self, executor: E) -> &mut Config
     where
         E: Executor<Box<dyn Future<Item = (), Error = ()> + Send>> + 'static + Sync + Send,
@@ -127,6 +248,7 @@ impl Config {
         self
     }
 
+    /// Opens a connection to a PostgreSQL database.
     pub fn connect<T>(&self, tls_mode: T) -> Result<Client, Error>
     where
         T: MakeTlsConnect<Socket> + 'static + Send,

postgres/src/lib.rs

@@ -5,15 +5,31 @@ use lazy_static::lazy_static;
 #[cfg(feature = "runtime")]
 use tokio::runtime::{self, Runtime};
 
+pub use tokio_postgres::{error, row, tls, types, Column, Portal, SimpleQueryMessage, Statement};
+
+pub use crate::client::*;
+#[cfg(feature = "runtime")]
+pub use crate::config::Config;
+pub use crate::copy_out_reader::*;
+#[doc(no_inline)]
+pub use crate::error::Error;
+pub use crate::query_iter::*;
+pub use crate::query_portal_iter::*;
+#[doc(no_inline)]
+pub use crate::row::{Row, SimpleQueryRow};
+pub use crate::simple_query_iter::*;
+#[doc(no_inline)]
+pub use crate::tls::NoTls;
+pub use crate::to_statement::*;
+pub use crate::transaction::*;
+
 mod client;
 #[cfg(feature = "runtime")]
-mod config;
+pub mod config;
 mod copy_out_reader;
-mod portal;
 mod query_iter;
 mod query_portal_iter;
 mod simple_query_iter;
-mod statement;
 mod to_statement;
 mod transaction;
 
@@ -21,18 +37,6 @@ mod transaction;
 #[cfg(test)]
 mod test;
 
-pub use crate::client::*;
-#[cfg(feature = "runtime")]
-pub use crate::config::*;
-pub use crate::copy_out_reader::*;
-pub use crate::portal::*;
-pub use crate::query_iter::*;
-pub use crate::query_portal_iter::*;
-pub use crate::simple_query_iter::*;
-pub use crate::statement::*;
-pub use crate::to_statement::*;
-pub use crate::transaction::*;
-
 #[cfg(feature = "runtime")]
 lazy_static! {
     static ref RUNTIME: Runtime = runtime::Builder::new()

postgres/src/portal.rs

@@ -1 +0,0 @@
-pub struct Portal(pub(crate) tokio_postgres::Portal);

postgres/src/statement.rs

@@ -1,15 +0,0 @@
-use tokio_postgres::types::Type;
-use tokio_postgres::Column;
-
-#[derive(Clone)]
-pub struct Statement(pub(crate) tokio_postgres::Statement);
-
-impl Statement {
-    pub fn params(&self) -> &[Type] {
-        self.0.params()
-    }
-
-    pub fn columns(&self) -> &[Column] {
-        self.0.columns()
-    }
-}

postgres/src/transaction.rs

@@ -96,11 +96,7 @@ impl<'a> Transaction<'a> {
         T: ?Sized + ToStatement,
     {
         let statement = query.__statement(&mut self.client)?;
-        self.client
-            .get_mut()
-            .bind(&statement.0, params)
-            .wait()
-            .map(Portal)
+        self.client.get_mut().bind(&statement, params).wait()
     }
 
     pub fn query_portal(&mut self, portal: &Portal, max_rows: i32) -> Result<Vec<Row>, Error> {
@@ -113,7 +109,7 @@ impl<'a> Transaction<'a> {
         max_rows: i32,
     ) -> Result<QueryPortalIter<'_>, Error> {
         Ok(QueryPortalIter::new(
-            self.client.get_mut().query_portal(&portal.0, max_rows),
+            self.client.get_mut().query_portal(&portal, max_rows),
         ))
     }