From 19111a30bfcff3501ea11a1e822e257f2b9286d7 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Sun, 6 Dec 2015 16:08:37 -0800 Subject: [PATCH] Reorder some connection methods Roughly rank them by which usage --- src/lib.rs | 138 ++++++++++++++++++++++++++--------------------------- 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 7085f2c1..731eaa5f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -909,16 +909,66 @@ impl Connection { InnerConnection::connect(params, ssl).map(|conn| Connection { conn: RefCell::new(conn) }) } - /// Sets the notice handler for the connection, returning the old handler. - pub fn set_notice_handler(&self, handler: Box) -> Box { - self.conn.borrow_mut().set_notice_handler(handler) + /// A convenience function for queries that are only run once. + /// + /// If an error is returned, it could have come from either the preparation + /// or execution of the statement. + /// + /// On success, returns the number of rows modified or 0 if not applicable. + /// + /// # Panics + /// + /// Panics if the number of parameters provided does not match the number + /// expected. + pub fn execute(&self, query: &str, params: &[&ToSql]) -> Result { + let (param_types, columns) = try!(self.conn.borrow_mut().raw_prepare("", query)); + let stmt = Statement::new(self, + "".to_owned(), + param_types, + columns, + Cell::new(0), + true); + stmt.execute(params) } - /// Returns a structure providing access to asynchronous notifications. + /// Begins a new transaction. /// - /// Use the `LISTEN` command to register this connection for notifications. - pub fn notifications<'a>(&'a self) -> Notifications<'a> { - Notifications::new(self) + /// Returns a `Transaction` object which should be used instead of + /// the connection for the duration of the transaction. The transaction + /// is active until the `Transaction` object falls out of scope. + /// + /// # Note + /// A transaction will roll back by default. The `set_commit`, + /// `set_rollback`, and `commit` methods alter this behavior. + /// + /// # Panics + /// + /// Panics if a transaction is already active. + /// + /// # Example + /// + /// ```rust,no_run + /// # use postgres::{Connection, SslMode}; + /// # let conn = Connection::connect("", &SslMode::None).unwrap(); + /// let trans = conn.transaction().unwrap(); + /// trans.execute("UPDATE foo SET bar = 10", &[]).unwrap(); + /// // ... + /// + /// trans.commit().unwrap(); + /// ``` + pub fn transaction<'a>(&'a self) -> Result> { + let mut conn = self.conn.borrow_mut(); + check_desync!(conn); + assert!(conn.trans_depth == 0, + "`transaction` must be called on the active transaction"); + try!(conn.quick_query("BEGIN")); + conn.trans_depth += 1; + Ok(Transaction { + conn: self, + commit: Cell::new(false), + depth: 1, + finished: false, + }) } /// Creates a new prepared statement. @@ -969,46 +1019,6 @@ impl Connection { self.conn.borrow_mut().prepare_cached(query, self) } - /// Begins a new transaction. - /// - /// Returns a `Transaction` object which should be used instead of - /// the connection for the duration of the transaction. The transaction - /// is active until the `Transaction` object falls out of scope. - /// - /// # Note - /// A transaction will roll back by default. The `set_commit`, - /// `set_rollback`, and `commit` methods alter this behavior. - /// - /// # Panics - /// - /// Panics if a transaction is already active. - /// - /// # Example - /// - /// ```rust,no_run - /// # use postgres::{Connection, SslMode}; - /// # let conn = Connection::connect("", &SslMode::None).unwrap(); - /// let trans = conn.transaction().unwrap(); - /// trans.execute("UPDATE foo SET bar = 10", &[]).unwrap(); - /// // ... - /// - /// trans.commit().unwrap(); - /// ``` - pub fn transaction<'a>(&'a self) -> Result> { - let mut conn = self.conn.borrow_mut(); - check_desync!(conn); - assert!(conn.trans_depth == 0, - "`transaction` must be called on the active transaction"); - try!(conn.quick_query("BEGIN")); - conn.trans_depth += 1; - Ok(Transaction { - conn: self, - commit: Cell::new(false), - depth: 1, - finished: false, - }) - } - /// Sets the isolation level which will be used for future transactions. /// /// This is a simple wrapper around `SET TRANSACTION ISOLATION LEVEL ...`. @@ -1030,28 +1040,6 @@ impl Connection { IsolationLevel::parse(result[0][0].as_ref().unwrap()) } - /// A convenience function for queries that are only run once. - /// - /// If an error is returned, it could have come from either the preparation - /// or execution of the statement. - /// - /// On success, returns the number of rows modified or 0 if not applicable. - /// - /// # Panics - /// - /// Panics if the number of parameters provided does not match the number - /// expected. - pub fn execute(&self, query: &str, params: &[&ToSql]) -> Result { - let (param_types, columns) = try!(self.conn.borrow_mut().raw_prepare("", query)); - let stmt = Statement::new(self, - "".to_owned(), - param_types, - columns, - Cell::new(0), - true); - stmt.execute(params) - } - /// Execute a sequence of SQL statements. /// /// Statements should be separated by `;` characters. If an error occurs, @@ -1090,6 +1078,13 @@ impl Connection { self.conn.borrow_mut().quick_query(query).map(|_| ()) } + /// Returns a structure providing access to asynchronous notifications. + /// + /// Use the `LISTEN` command to register this connection for notifications. + pub fn notifications<'a>(&'a self) -> Notifications<'a> { + Notifications::new(self) + } + /// Returns information used to cancel pending queries. /// /// Used with the `cancel_query` function. The object returned can be used @@ -1104,6 +1099,11 @@ impl Connection { self.conn.borrow().parameters.get(param).cloned() } + /// Sets the notice handler for the connection, returning the old handler. + pub fn set_notice_handler(&self, handler: Box) -> Box { + self.conn.borrow_mut().set_notice_handler(handler) + } + /// Returns whether or not the stream has been desynchronized due to an /// error in the communication channel with the server. ///