From 7c9717d764a59ed1e075d819970b6506544e5c15 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Thu, 28 Mar 2019 21:55:42 -0700 Subject: [PATCH] Finish Client docs --- postgres/src/client.rs | 140 ++++++++++++++++++++++++++++++++++------- 1 file changed, 117 insertions(+), 23 deletions(-) diff --git a/postgres/src/client.rs b/postgres/src/client.rs index 95152c89..64d14eeb 100644 --- a/postgres/src/client.rs +++ b/postgres/src/client.rs @@ -19,7 +19,11 @@ pub struct Client(tokio_postgres::Client); impl Client { /// A convenience function which parses a configuration string into a `Config` and then connects to the database. /// + /// See the documentation for [`Config`] for information about the connection syntax. + /// /// Requires the `runtime` Cargo feature (enabled by default). + /// + /// [`Config`]: config/struct.Config.html #[cfg(feature = "runtime")] pub fn connect(params: &str, tls_mode: T) -> Result where @@ -39,22 +43,6 @@ impl Client { Config::new() } - /// Creates a new prepared statement. - /// - /// Prepared statements can be executed repeatedly, and may contain query parameters (indicated by `$1`, `$2`, etc), - /// which are set when executed. Prepared statements can only be used with the connection that created them. - pub fn prepare(&mut self, query: &str) -> Result { - self.0.prepare(query).wait() - } - - /// Like `prepare`, but allows the types of query parameters to be explicitly specified. - /// - /// The list of types may be smaller than the number of parameters - the types of the remaining parameters will be - /// inferred. For example, `client.prepare_typed(query, &[])` is equivalent to `client.prepare(query)`. - pub fn prepare_typed(&mut self, query: &str, types: &[Type]) -> Result { - self.0.prepare_typed(query, types).wait() - } - /// Executes a statement, returning the number of rows modified. /// /// A statement may contain parameters, specified by `$n`, where `n` is the index of the parameter of the list @@ -172,10 +160,80 @@ impl Client { Ok(QueryIter::new(self.0.query(&statement, params))) } + /// Creates a new prepared statement. + /// + /// Prepared statements can be executed repeatedly, and may contain query parameters (indicated by `$1`, `$2`, etc), + /// which are set when executed. Prepared statements can only be used with the connection that created them. + /// + /// # Examples + /// + /// ```no_run + /// use postgres::{Client, NoTls}; + /// + /// # fn main() -> Result<(), postgres::Error> { + /// let mut client = Client::connect("host=localhost user=postgres", NoTls)?; + /// + /// let statement = client.prepare("SELECT name FROM people WHERE id = $1")?; + /// + /// for id in 0..10 { + /// let rows = client.query(&statement, &[&id])?; + /// let name: &str = rows[0].get(0); + /// println!("name: {}", name); + /// } + /// # Ok(()) + /// # } + /// ``` + pub fn prepare(&mut self, query: &str) -> Result { + self.0.prepare(query).wait() + } + + /// Like `prepare`, but allows the types of query parameters to be explicitly specified. + /// + /// The list of types may be smaller than the number of parameters - the types of the remaining parameters will be + /// inferred. For example, `client.prepare_typed(query, &[])` is equivalent to `client.prepare(query)`. + /// + /// # Examples + /// + /// ```no_run + /// use postgres::{Client, NoTls}; + /// use postgres::types::Type; + /// + /// # fn main() -> Result<(), postgres::Error> { + /// let mut client = Client::connect("host=localhost user=postgres", NoTls)?; + /// + /// let statement = client.prepare_typed( + /// "SELECT name FROM people WHERE id = $1", + /// &[Type::INT8], + /// )?; + /// + /// for id in 0..10 { + /// let rows = client.query(&statement, &[&id])?; + /// let name: &str = rows[0].get(0); + /// println!("name: {}", name); + /// } + /// # Ok(()) + /// # } + pub fn prepare_typed(&mut self, query: &str, types: &[Type]) -> Result { + self.0.prepare_typed(query, types).wait() + } + /// Executes a `COPY FROM STDIN` statement, returning the number of rows created. /// /// The `query` argument can either be a `Statement`, or a raw query string. The data in the provided reader is /// passed along to the server verbatim; it is the caller's responsibility to ensure it uses the proper format. + /// + /// # Examples + /// + /// ```no_run + /// use postgres::{Client, NoTls}; + /// + /// # fn main() -> Result<(), postgres::Error> { + /// let mut client = Client::connect("host=localhost user=postgres", NoTls)?; + /// + /// client.copy_in("COPY people FROM stdin", &[], &mut "1\tjohn\n2\tjane\n".as_bytes())?; + /// # Ok(()) + /// # } + /// ``` pub fn copy_in( &mut self, query: &T, @@ -195,6 +253,22 @@ impl Client { /// Executes a `COPY TO STDOUT` statement, returning a reader of the resulting data. /// /// The `query` argument can either be a `Statement`, or a raw query string. + /// + /// # Examples + /// + /// ```no_run + /// use postgres::{Client, NoTls}; + /// use std::io::Read; + /// + /// # fn main() -> Result<(), Box> { + /// let mut client = Client::connect("host=localhost user=postgres", NoTls)?; + /// + /// let mut reader = client.copy_out("COPY people TO stdout", &[])?; + /// let mut buf = vec![]; + /// reader.read_to_end(&mut buf)?; + /// # Ok(()) + /// # } + /// ``` pub fn copy_out( &mut self, query: &T, @@ -227,13 +301,8 @@ impl Client { self.simple_query_iter(query)?.collect() } - /// Executes a sequence of SQL statements using the simple query protocol. - /// - /// Statements should be separated by semicolons. If an error occurs, execution of the sequence will stop at that - /// point. The simple query protocol returns the values in rows as strings rather than in their binary encodings, - /// so the associated row type doesn't work with the `FromSql` trait. Rather than simply returning the rows, this - /// method returns a sequence of an enum which indicates either the completion of one of the commands, or a row of - /// data. This preserves the framing between the separate statements in the request. + /// Like `simple_query`, except that it returns a fallible iterator over the resulting values rather than buffering + /// the response in memory. /// /// # Warning /// @@ -245,23 +314,48 @@ impl Client { } /// Begins a new database transaction. + /// + /// The transaction will roll back by default - use the `commit` method to commit it. + /// + /// # Examples + /// + /// ```no_run + /// use postgres::{Client, NoTls}; + /// + /// # fn main() -> Result<(), postgres::Error> { + /// let mut client = Client::connect("host=localhost user=postgres", NoTls)?; + /// + /// let mut transaction = client.transaction()?; + /// transaction.execute("UPDATE foo SET bar = 10", &[])?; + /// // ... + /// + /// transaction.commit()?; + /// # Ok(()) + /// # } + /// ``` pub fn transaction(&mut self) -> Result, Error> { self.simple_query("BEGIN")?; Ok(Transaction::new(self)) } + /// Determines if the client's connection has already closed. + /// + /// If this returns `true`, the client is no longer usable. pub fn is_closed(&self) -> bool { self.0.is_closed() } + /// Returns a shared reference to the inner nonblocking client. pub fn get_ref(&self) -> &tokio_postgres::Client { &self.0 } + /// Returns a mutable reference to the inner nonblocking client. pub fn get_mut(&mut self) -> &mut tokio_postgres::Client { &mut self.0 } + /// Consumes the client, returning the inner nonblocking client. pub fn into_inner(self) -> tokio_postgres::Client { self.0 }