@@ -12,17 +12,17 @@
1212-- <http://www.postgresql.org/docs/9.2/static/sql-copy.html> for
1313-- more information.
1414--
15−-- To use this binding, first call 'copy' with a @COPY FROM STDIN@
16−-- or @COPY TO STDOUT@ query as documented in the link above. Then
17−-- call 'getCopyData' repeatedly until it returns 'CopyOutDone' in
18−-- the former case, or in the latter, call 'putCopyData' repeatedly
19−-- and then finish by calling either 'putCopyEnd' to proceed or
20−-- 'putCopyError' to abort.
15+-- To use this binding, first call 'copy' with an appropriate
16+-- query as documented in the link above. Then, in the case of a
17+-- @COPY TO STDOUT@ query, call 'getCopyData' repeatedly until it
18+-- returns 'CopyOutDone'. In the case of a @COPY FROM STDIN@
19+-- query, call 'putCopyData' repeatedly and then finish by calling
20+-- either 'putCopyEnd' to proceed or 'putCopyError' to abort.
2121--
2222-- You cannot issue another query on the same connection while a copy
2323-- is ongoing; this will result in an exception. It is harmless to
2424-- concurrently call @getNotification@ on a connection while it is in
25−-- a copy in or copy out state, however be aware that current versions
25+-- a @CopyIn@ or @CopyOut@ state, however be aware that current versions
2626-- of the PostgreSQL backend will not deliver notifications to a client
2727-- while a transaction is ongoing.
2828--
@@ -50,18 +50,22 @@ import Database.PostgreSQL.Simple
5050import Database.PostgreSQL.Simple.Types
5151import Database.PostgreSQL.Simple.Internal
5252
53−-- | Issue a query that changes a connection's state to @CopyIn@
54−-- (via a @COPY FROM STDIN@ query) or @CopyOut@ (via @COPY TO STDOUT@)
55−-- query. Performs parameter subsitution.
53+
54+-- | Issue a @COPY FROM STDIN@ or @COPY TO STDOUT@ query. In the former
55+-- case, the connection's state will change to @CopyIn@; in the latter,
56+-- @CopyOut@. The connection must be in the normal state in order
57+-- to call this function. Performs parameter subsitution.
5658
5759copy :: ( ToRow params ) => Connection -> Query -> params -> IO ()
5860copy conn template qs = do
5961 q <- formatQuery conn template qs
6062 doCopy "Database.PostgreSQL.Simple.Copy.copy" conn template q
6163
62−-- | Issue a query that changes a connection's state to @CopyIn@
63−-- (via a @COPY FROM STDIN@ query) or @CopyOut@ (via @COPY TO STDOUT@)
64−-- query. Does not perform parameter subsitution.
64+
65+-- | Issue a @COPY FROM STDIN@ or @COPY TO STDOUT@ query. In the former
66+-- case, the connection's state will change to @CopyIn@; in the latter,
67+-- @CopyOut@. The connection must be in the normal state in order
68+-- to call this function. Does not perform parameter subsitution.
6569
6670copy_ :: Connection -> Query -> IO ()
6771copy_ conn (Query q) = do
@@ -92,10 +96,12 @@ data CopyOutResult
9296 -- number of rows returned.
9397 deriving (Eq, Typeable, Show)
9498
95−-- | A connection must be in the @CopyOut@ state in order to call this
96−-- function, via a @COPY TO STDOUT@ query. If this returns a 'CopyOutRow',
97−-- the connection remains in the @CopyOut@ state, if it returns 'CopyOutDone',
98−-- then the connection has reverted to the ready state.
99+
100+-- | Retrieve some data from a @COPY TO STDOUT@ query. A connection
101+-- must be in the @CopyOut@ state in order to call this function. If this
102+-- returns a 'CopyOutRow', the connection remains in the @CopyOut@ state,
103+-- if it returns 'CopyOutDone', then the connection has reverted to the
104+-- ready state.
99105
100106getCopyData :: Connection -> IO CopyOutResult
101107getCopyData conn = withConnection conn loop
@@ -133,13 +139,17 @@ getCopyData conn = withConnection conn loop
133139 sqlErrorHint = funcName
134140 }
135141
136−-- | A connection must be in the @CopyIn@ state in order to call this
137−-- function, via a @COPY FROM STDIN@ query. The connection remains
138−-- in a @CopyIn@ state after this function is called. Note that
142+
143+-- | Feed some data to a @COPY FROM STDIN@ query. Note that
139144-- the data does not need to represent a single row, or even an
140145-- integral number of rows. The net result of
141146-- @putCopyData conn a >> putCopyData conn b@
142147-- is the same as @putCopyData conn c@ whenever @c == BS.append a b@.
148+--
149+-- A connection must be in the @CopyIn@ state in order to call this
150+-- function, otherwise a 'SqlError' exception will result. The
151+-- connection remains in the @CopyIn@ state after this function
152+-- is called.
143153
144154putCopyData :: Connection -> B.ByteString -> IO ()
145155putCopyData conn dat = withConnection conn $ \pqconn -> do
@@ -148,10 +158,13 @@ putCopyData conn dat = withConnection conn $ \pqconn -> do
148158 funcName = "Database.PostgreSQL.Simple.Copy.putCopyData"
149159
150160
151−-- | A connection must be in the @CopyIn@ state in order to call this
152−-- function, via a @COPY FROM STDIN@ query. Completes the COPY IN
153−-- operation, changing the connection's state back to normal.
154−-- Returns the number of rows processed.
161+-- | Completes a @COPY FROM STDIN@ query. Returns the number of rows
162+-- processed.
163+--
164+-- A connection must be in the @CopyIn@ state in order to call this
165+-- function, otherwise a 'SqlError' exception will result. The
166+-- connection's state changes back to normal after this function
167+-- is called.
155168
156169putCopyEnd :: Connection -> IO Int64
157170putCopyEnd conn = withConnection conn $ \pqconn -> do
@@ -160,9 +173,15 @@ putCopyEnd conn = withConnection conn $ \pqconn -> do
160173 where
161174 funcName = "Database.PostgreSQL.Simple.Copy.putCopyEnd"
162175
163−-- | A connection must be in the @CopyIn@ state in order to call this
164−-- function, via a @COPY FROM STDIN@ query. Aborts the COPY IN
165−-- operation, changing the connection's state back to normal.
176+
177+-- | Aborts a @COPY FROM STDIN@ query. The string parameter is simply
178+-- an arbitrary error message that may show up in the PostgreSQL
179+-- server's log.
180+--
181+-- A connection must be in the @CopyIn@ state in order to call this
182+-- function, otherwise a 'SqlError' exception will result. The
183+-- connection's state changes back to normal after this function
184+-- is called.
166185
167186putCopyError :: Connection -> B.ByteString -> IO ()
168187putCopyError conn err = withConnection conn $ \pqconn -> do