From 52aa260f857e7c0392f04709779c1b470227fd5b Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Mon, 25 Mar 2019 21:03:22 -0700 Subject: [PATCH] Reexports and config docs --- postgres/src/client.rs | 12 ++-- postgres/src/config.rs | 124 +++++++++++++++++++++++++++++++++++- postgres/src/lib.rs | 34 +++++----- postgres/src/portal.rs | 1 - postgres/src/statement.rs | 15 ----- postgres/src/transaction.rs | 8 +-- 6 files changed, 150 insertions(+), 44 deletions(-) delete mode 100644 postgres/src/portal.rs delete mode 100644 postgres/src/statement.rs diff --git a/postgres/src/client.rs b/postgres/src/client.rs index e1cc3bba..681b754e 100644 --- a/postgres/src/client.rs +++ b/postgres/src/client.rs @@ -31,11 +31,11 @@ impl Client { } pub fn prepare(&mut self, query: &str) -> Result { - self.0.prepare(query).wait().map(Statement) + self.0.prepare(query).wait() } pub fn prepare_typed(&mut self, query: &str, types: &[Type]) -> Result { - self.0.prepare_typed(query, types).wait().map(Statement) + self.0.prepare_typed(query, types).wait() } pub fn execute(&mut self, query: &T, params: &[&dyn ToSql]) -> Result @@ -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(&mut self, query: &T, params: &[&dyn ToSql]) -> Result, 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( @@ -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) } diff --git a/postgres/src/config.rs b/postgres/src/config.rs index e142b9d2..b04c03f8 100644 --- a/postgres/src/config.rs +++ b/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 + 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(&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(&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(&mut self, executor: E) -> &mut Config where E: Executor + Send>> + 'static + Sync + Send, @@ -127,6 +248,7 @@ impl Config { self } + /// Opens a connection to a PostgreSQL database. pub fn connect(&self, tls_mode: T) -> Result where T: MakeTlsConnect + 'static + Send, diff --git a/postgres/src/lib.rs b/postgres/src/lib.rs index c4a1ae5f..112b1082 100644 --- a/postgres/src/lib.rs +++ b/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() diff --git a/postgres/src/portal.rs b/postgres/src/portal.rs deleted file mode 100644 index cf22e575..00000000 --- a/postgres/src/portal.rs +++ /dev/null @@ -1 +0,0 @@ -pub struct Portal(pub(crate) tokio_postgres::Portal); diff --git a/postgres/src/statement.rs b/postgres/src/statement.rs deleted file mode 100644 index b6abe2a5..00000000 --- a/postgres/src/statement.rs +++ /dev/null @@ -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() - } -} diff --git a/postgres/src/transaction.rs b/postgres/src/transaction.rs index fb56b718..f4f4a264 100644 --- a/postgres/src/transaction.rs +++ b/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, Error> { @@ -113,7 +109,7 @@ impl<'a> Transaction<'a> { max_rows: i32, ) -> Result, Error> { Ok(QueryPortalIter::new( - self.client.get_mut().query_portal(&portal.0, max_rows), + self.client.get_mut().query_portal(&portal, max_rows), )) }