-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Stream postgresql-query results using the streaming library
--   
--   This package provides incremental streaming functions for the
--   <tt>postgresql-simple</tt> library.
@package streaming-postgresql-simple
@version 0.1.0.0

module Database.PostgreSQL.Simple.Streaming

-- | Perform a <tt>SELECT</tt> or other SQL query that is expected to
--   return results. Uses PostgreSQL's <a>single row mode</a> to stream
--   results directly from the socket to Haskell.
--   
--   It is an error to perform another query using the same connection from
--   within a stream. This applies to both
--   <tt>streaming-postgresql-simple</tt> and <tt>postgresql-simple</tt>
--   itself. If you do need to perform subsequent queries from within a
--   stream, you should use <a>stream</a>, which uses cursors and allows
--   interleaving of queries.
--   
--   To demonstrate the problems of interleaving queries, if we run the
--   following:
--   
--   <pre>
--   let doQuery c =
--         queryWith_ (Pg.fromRow :: RowParser (Pg.Only Int))
--                    c
--                    "VALUES (1), (2)"
--   in S.print (S.mapM_ (_ -&gt; doQuery c) (doQuery c))
--   </pre>
--   
--   We will encounter the exception:
--   
--   <pre>
--   Exception: QueryError {qeMessage = "another command is already in progressn", qeQuery = "VALUES (1), (2)"}
--   </pre>
--   
--   Exceptions that may be thrown:
--   
--   <ul>
--   <li><a>FormatError</a>: the query string could not be formatted
--   correctly.</li>
--   <li><a>QueryError</a>: the result contains no columns (i.e. you should
--   be using <tt>execute</tt> instead of <a>query</a>).</li>
--   <li><a>ResultError</a>: result conversion failed.</li>
--   <li><a>SqlError</a>: the postgresql backend returned an error, e.g. a
--   syntax or type error, or an incorrect table or column name.</li>
--   </ul>
query :: (ToRow q, FromRow r) => Connection -> Query -> q -> Stream (Of r) IO ()

-- | A version of <a>query</a> that does not perform query substitution.
query_ :: (FromRow r) => Connection -> Query -> Stream (Of r) IO ()

-- | A version of <a>query</a> taking parser as argument.
queryWith :: (ToRow q) => RowParser r -> Connection -> Query -> q -> Stream (Of r) IO ()

-- | A version of <a>query_</a> taking parser as argument.
queryWith_ :: RowParser r -> Connection -> Query -> Stream (Of r) IO ()

-- | Perform a <tt>SELECT</tt> or other SQL query that is expected to
--   return results. Results are streamed incrementally from the server.
--   
--   When dealing with small results that don't require further access to
--   the database it may be simpler (and perhaps faster) to use
--   <a>query</a> instead.
--   
--   This is implemented using a database cursor. As such, this requires a
--   transaction. This function will detect whether or not there is a
--   transaction in progress, and will create a <tt>ReadCommitted</tt>
--   <tt>ReadOnly</tt> transaction if needed. The cursor is given a unique
--   temporary name, so the consumer may itself call <a>stream</a>.
--   
--   Exceptions that may be thrown:
--   
--   <ul>
--   <li><a>FormatError</a>: the query string could not be formatted
--   correctly.</li>
--   <li><a>QueryError</a>: the result contains no columns (i.e. you should
--   be using <tt>execute</tt> instead of <a>query</a>).</li>
--   <li><a>ResultError</a>: result conversion failed.</li>
--   <li><a>SqlError</a>: the postgresql backend returned an error, e.g. a
--   syntax or type error, or an incorrect table or column name.</li>
--   </ul>
stream :: (FromRow row, ToRow params, MonadMask m, MonadResource m) => Connection -> Query -> params -> Stream (Of row) m ()
streamWithOptions :: (FromRow row, ToRow params, MonadResource m, MonadMask m) => FoldOptions -> Connection -> Query -> params -> Stream (Of row) m ()

-- | A version of <a>stream</a> that does not perform query substitution.
stream_ :: (FromRow row, MonadMask m, MonadResource m) => Connection -> Query -> Stream (Of row) m ()
streamWithOptions_ :: (FromRow row, MonadResource m, MonadMask m) => FoldOptions -> Connection -> Query -> Stream (Of row) m ()

-- | A version of <a>stream</a> taking a parser as an argument.
streamWith :: (ToRow params, MonadMask m, MonadResource m) => RowParser row -> Connection -> Query -> params -> Stream (Of row) m ()

-- | A version of <a>streamWithOptions</a> taking a parser as an argument.
streamWithOptionsAndParser :: (ToRow params, MonadMask m, MonadResource m) => FoldOptions -> RowParser row -> Connection -> Query -> params -> Stream (Of row) m ()

-- | A version of <a>stream_</a> taking a parser as an argument.
streamWith_ :: (MonadMask m, MonadResource m) => RowParser row -> Connection -> Query -> Stream (Of row) m ()

-- | A version of <a>streamWithOptions_</a> taking a parser as an argument.
streamWithOptionsAndParser_ :: (MonadMask m, MonadResource m) => FoldOptions -> RowParser row -> Connection -> Query -> Stream (Of row) m ()

-- | Issue a <tt>COPY FROM STDIN</tt> query and stream the results in.
--   
--   Note that the data in the stream not need to represent a single row,
--   or even an integral number of rows.
--   
--   The stream indicates whether or not the copy was succesful. If the
--   stream terminates with <a>Nothing</a>, the copy is succesful. If the
--   stream terminates with <a>Just</a> <tt>error</tt>, the error message
--   will be logged.
--   
--   If copying was successful, the number of rows processed is returned.
copyIn :: (ToRow params, MonadIO m) => Connection -> Query -> params -> Stream (Of ByteString) m (Maybe ByteString) -> m (Maybe Int64)

-- | Issue a <tt>COPY TO STDOUT</tt> query and stream the results. When the
--   stream is drained it returns the total amount of rows returned. Each
--   element in the stream is either exactly one row of the result, or
--   header or footer data depending on format.
copyOut :: (MonadIO m, ToRow params) => Connection -> Query -> params -> Stream (Of ByteString) m Int64