Documentation

Author: sfackler

postgres-shared/src/lib.rs

@@ -15,6 +15,15 @@ pub mod error;
 pub mod params;
 pub mod types;
 
+/// Contains information necessary to cancel queries for a session.
+#[derive(Copy, Clone, Debug)]
+pub struct CancelData {
+    /// The process ID of the session.
+    pub process_id: i32,
+    /// The secret key for the session.
+    pub secret_key: i32,
+}
+
 pub struct RowData {
     buf: Vec<u8>,
     indices: Vec<Option<Range<usize>>>,

postgres-tokio/src/error.rs

@@ -1,3 +1,5 @@
+//! Error types.
+
 use std::error;
 use std::io;
 use std::fmt;
@@ -7,10 +9,16 @@ use Connection;
 #[doc(inline)]
 pub use postgres_shared::error::*;
 
+/// A runtime error.
 #[derive(Debug)]
 pub enum Error<C = Connection> {
+    /// An error communicating with the database.
+    ///
+    /// IO errors are fatal - the connection is not returned.
     Io(io::Error),
+    /// An error reported by the database.
     Db(Box<DbError>, C),
+    /// An error converting between Rust and Postgres types.
     Conversion(Box<error::Error + Sync + Send>, C),
 }
 

postgres-tokio/src/lib.rs

@@ -1,3 +1,6 @@
+//! An asynchronous Postgres driver.
+#![warn(missing_docs)]
+
 extern crate fallible_iterator;
 extern crate futures;
 extern crate futures_state_stream;
@@ -28,11 +31,11 @@ use std::sync::mpsc::{self, Sender, Receiver};
 use tokio_core::reactor::Handle;
 
 #[doc(inline)]
-pub use postgres_shared::{params, Column, RowIndex};
+pub use postgres_shared::{params, CancelData};
 
 use error::{ConnectError, Error, DbError, SqlState};
 use params::{ConnectParams, IntoConnectParams};
-use stmt::Statement;
+use stmt::{Statement, Column};
 use stream::PostgresStream;
 use tls::Handshake;
 use transaction::Transaction;
@@ -55,18 +58,27 @@ const TYPEINFO_QUERY: &'static str = "__typeinfo";
 const TYPEINFO_ENUM_QUERY: &'static str = "__typeinfo_enum";
 const TYPEINFO_COMPOSITE_QUERY: &'static str = "__typeinfo_composite";
 
+/// Specifies the TLS support required for a new connection.
 pub enum TlsMode {
+    /// The connection must use TLS.
     Require(Box<Handshake>),
+    /// The connection will use TLS if available.
     Prefer(Box<Handshake>),
+    /// The connection will not use TLS.
     None,
 }
 
-#[derive(Debug, Copy, Clone)]
-pub struct CancelData {
-    pub process_id: i32,
-    pub secret_key: i32,
-}
-
+/// Attempts to cancel an in-progress query.
+///
+/// The backend provides no information about whether a cancellation attempt
+/// was successful or not. An error will only be returned if the driver was
+/// unable to connect to the database.
+///
+/// A `CancelData` object can be created via `Connection::cancel_data`. The
+/// object can cancel any query made on that connection.
+///
+/// Only the host and port of the connection info are used. See
+/// `Connection::connect` for details of the `params` argument.
 pub fn cancel_query<T>(params: T,
                        tls_mode: TlsMode,
                        cancel_data: CancelData,
@@ -161,6 +173,7 @@ impl Sink for InnerConnection {
     }
 }
 
+/// A connection to a Postgres database.
 pub struct Connection(InnerConnection);
 
 // FIXME fill out
@@ -172,6 +185,24 @@ impl fmt::Debug for Connection {
 }
 
 impl Connection {
+    /// Creates a new connection to a Postgres database.
+    ///
+    /// Most applications can use a URL string in the normal format:
+    ///
+    /// ```notrust
+    /// postgresql://user[:password]@host[:port][/database][?param1=val1[[&param2=val2]...]]
+    /// ```
+    ///
+    /// The password may be omitted if not required. The default Postgres port
+    /// (5432) is used if none is specified. The database name defaults to the
+    /// username if not specified.
+    ///
+    /// To connect to the server via Unix sockets, `host` should be set to the
+    /// absolute path of the directory containing the socket file.  Since `/` is
+    /// a reserved character in URLs, the path should be URL encoded. If the
+    /// path contains non-UTF 8 characters, a `ConnectParams` struct should be
+    /// created manually and passed in. Note that Postgres does not support TLS
+    /// over Unix sockets.
     pub fn connect<T>(params: T,
                       tls_mode: TlsMode,
                       handle: &Handle)
@@ -421,6 +452,19 @@ impl Connection {
             .boxed()
     }
 
+    /// Execute a sequence of SQL statements.
+    ///
+    /// Statements should be separated by `;` characters. If an error occurs,
+    /// execution of the sequence will stop at that point. This is intended for
+    /// execution of batches of non-dynamic statements - for example, creation
+    /// of a schema for a fresh database.
+    ///
+    /// # Warning
+    ///
+    /// Prepared statements should be used for any SQL statement which contains
+    /// user-specified data, as it provides functionality to safely embed that
+    /// data in the statement. Do not form statements via string concatenation
+    /// and feed them into this method.
     pub fn batch_execute(self, query: &str) -> BoxFuture<Connection, Error> {
         self.simple_query(query)
             .map(|r| r.1)
@@ -873,6 +917,7 @@ impl Connection {
             .boxed()
     }
 
+    /// Creates a new prepared statement.
     pub fn prepare(mut self, query: &str) -> BoxFuture<(Statement, Connection), Error> {
         let id = self.0.next_stmt_id;
         self.0.next_stmt_id += 1;
@@ -888,12 +933,24 @@ impl Connection {
             .boxed()
     }
 
+    /// Executes a statement, returning the number of rows modified.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the number of parameters provided does not match the number
+    /// expected.
     pub fn execute(self, statement: &Statement, params: &[&ToSql]) -> BoxFuture<(u64, Connection), Error> {
         self.raw_execute(statement.name(), "", statement.parameters(), params)
             .and_then(|conn| conn.finish_execute())
             .boxed()
     }
 
+    /// Executes a statement, returning a stream over the resulting rows.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the number of parameters provided does not match the number
+    /// expected.
     pub fn query(self,
                  statement: &Statement,
                  params: &[&ToSql])
@@ -905,24 +962,26 @@ impl Connection {
             .boxed()
     }
 
+    /// Starts a new transaction.
     pub fn transaction(self) -> BoxFuture<Transaction, Error> {
         self.simple_query("BEGIN")
             .map(|(_, c)| Transaction::new(c))
             .boxed()
     }
 
-    pub fn close(self) -> BoxFuture<(), Error> {
-        let mut terminate = vec![];
-        frontend::terminate(&mut terminate);
-        self.0.send(terminate)
-            .map(|_| ())
-            .map_err(Error::Io)
-            .boxed()
-    }
-
+    /// Returns information used to cancel pending queries.
+    ///
+    /// Used with the `cancel_query` function. The object returned can be used
+    /// to cancel any query executed by the connection it was created from.
     pub fn cancel_data(&self) -> CancelData {
         self.0.cancel_data
     }
+
+    /// Returns the value of the specified Postgres backend parameter, such as
+    /// `timezone` or `server_version`.
+    pub fn parameter(&self, param: &str) -> Option<&str> {
+        self.0.parameters.get(param).map(|s| &**s)
+    }
 }
 
 fn connect_err(fields: &mut ErrorFields) -> ConnectError {

postgres-tokio/src/rows.rs

@@ -1,3 +1,5 @@
+//! Postgres rows.
+
 use postgres_shared::{RowData, Column};
 use std::collections::HashMap;
 use std::error::Error;
@@ -10,6 +12,7 @@ pub use postgres_shared::RowIndex;
 use RowNew;
 use types::{WrongType, FromSql, SessionInfo};
 
+/// A row from Postgres.
 pub struct Row {
     columns: Arc<Vec<Column>>,
     data: RowData,
@@ -25,14 +28,25 @@ impl RowNew for Row {
 }
 
 impl Row {
+    /// Returns information about the columns in the row.
     pub fn columns(&self) -> &[Column] {
         &self.columns
     }
 
+    /// Returns the number of values in the row
     pub fn len(&self) -> usize {
         self.columns.len()
     }
 
+    /// Retrieves the contents of a field of the row.
+    ///
+    /// A field can be accessed by the name or index of its column, though
+    /// access by index is more efficient. Rows are 0-indexed.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the index does not reference a column or the return type is
+    /// not compatible with the Postgres type.
     pub fn get<T, I>(&self, idx: I) -> T
         where T: FromSql,
               I: RowIndex + fmt::Debug
@@ -44,6 +58,14 @@ impl Row {
         }
     }
 
+    /// Retrieves the contents of a field of the row.
+    ///
+    /// A field can be accessed by the name or index of its column, though
+    /// access by index is more efficient. Rows are 0-indexed.
+    ///
+    /// Returns `None` if the index does not reference a column, `Some(Err(..))`
+    /// if there was an error converting the result value, and `Some(Ok(..))`
+    /// on success.
     pub fn try_get<T, I>(&self, idx: I) -> Result<Option<T>, Box<Error + Sync + Send>>
         where T: FromSql,
               I: RowIndex

postgres-tokio/src/stmt.rs

@@ -1,3 +1,5 @@
+//! Prepared statements.
+
 use std::mem;
 use std::sync::Arc;
 use std::sync::mpsc::Sender;
@@ -8,6 +10,7 @@ pub use postgres_shared::Column;
 use StatementNew;
 use types::Type;
 
+/// A prepared statement.
 pub struct Statement {
     close_sender: Sender<(u8, String)>,
     name: String,
@@ -46,10 +49,12 @@ impl Drop for Statement {
 }
 
 impl Statement {
+    /// Returns the types of query parameters for this statement.
     pub fn parameters(&self) -> &[Type] {
         &self.params
     }
 
+    /// Returns information about the resulting columns for this statement.
     pub fn columns(&self) -> &[Column] {
         &self.columns
     }

postgres-tokio/src/stream.rs

@@ -79,6 +79,7 @@ pub fn connect(host: ConnectTarget,
         .boxed()
 }
 
+/// A raw connection to the database.
 pub struct Stream(InnerStream);
 
 enum InnerStream {

postgres-tokio/src/tls/mod.rs

@@ -1,3 +1,5 @@
+//! TLS support.
+
 use futures::BoxFuture;
 use std::error::Error;
 use tokio_core::io::Io;
@@ -7,9 +9,12 @@ pub use stream::Stream;
 #[cfg(feature = "with-openssl")]
 pub mod openssl;
 
+/// A trait implemented by streams returned from `Handshake` implementations.
 pub trait TlsStream: Io + Send {
+    /// Returns a shared reference to the inner stream.
     fn get_ref(&self) -> &Stream;
 
+    /// Returns a mutable reference to the inner stream.
     fn get_mut(&mut self) -> &mut Stream;
 }
 
@@ -25,7 +30,9 @@ impl TlsStream for Stream {
     }
 }
 
+/// A trait implemented by types that can manage TLS encryption for a stream.
 pub trait Handshake: 'static + Sync + Send {
+    /// Performs a TLS handshake, returning a wrapped stream.
     fn handshake(self: Box<Self>,
                  host: &str,
                  stream: Stream)

postgres-tokio/src/tls/openssl.rs

@@ -1,3 +1,5 @@
+//! OpenSSL support.
+
 use futures::{Future, BoxFuture};
 use openssl::ssl::{SslMethod, SslConnector, SslConnectorBuilder};
 use openssl::error::ErrorStack;
@@ -16,9 +18,11 @@ impl TlsStream for SslStream<Stream> {
     }
 }
 
+/// A `Handshake` implementation using OpenSSL.
 pub struct OpenSsl(SslConnector);
 
 impl OpenSsl {
+    /// Creates a new `OpenSsl` with default settings.
     pub fn new() -> Result<OpenSsl, ErrorStack> {
         let connector = try!(SslConnectorBuilder::new(SslMethod::tls())).build();
         Ok(OpenSsl(connector))