Database.PostgreSQL.Simple.Copy

mid-level support for COPY IN and COPY OUT. See https://www.postgresql.org/docs/9.5/static/sql-copy.html for more information.

To use this binding, first call copy with an appropriate query as documented in the link above. Then, in the case of a COPY TO STDOUT query, call getCopyData repeatedly until it returns CopyOutDone. In the case of a COPY FROM STDIN query, call putCopyData repeatedly and then finish by calling either putCopyEnd to proceed or putCopyError to abort.

You cannot issue another query on the same connection while a copy is ongoing; this will result in an exception. It is harmless to concurrently call getNotification on a connection while it is in a CopyIn or CopyOut state, however be aware that current versions of the PostgreSQL backend will not deliver notifications to a client while a transaction is ongoing.

Documentation

copy :: ToRow params => Connection -> Query -> params -> IO ()

Issue a COPY FROM STDIN or COPY TO STDOUT query. In the former case, the connection's state will change to CopyIn; in the latter, CopyOut. The connection must be in the ready state in order to call this function. Performs parameter subsitution.

copy_ :: Connection -> Query -> IO ()

Issue a COPY FROM STDIN or COPY TO STDOUT query. In the former case, the connection's state will change to CopyIn; in the latter, CopyOut. The connection must be in the ready state in order to call this function. Does not perform parameter subsitution.

data CopyOutResult

Constructors

CopyOutRow !ByteString

Data representing either exactly one row of the result, or header or footer data depending on format.

CopyOutDone !Int64

No more rows, and a count of the number of rows returned.

Instances

Eq CopyOutResult

Methods

(==) :: CopyOutResult -> CopyOutResult -> Bool

(/=) :: CopyOutResult -> CopyOutResult -> Bool

Show CopyOutResult

Methods

showsPrec :: Int -> CopyOutResult -> ShowS

show :: CopyOutResult -> String

showList :: [CopyOutResult] -> ShowS

getCopyData :: Connection -> IO CopyOutResult

Retrieve some data from a COPY TO STDOUT query. A connection must be in the CopyOut state in order to call this function. If this returns a CopyOutRow, the connection remains in the CopyOut state, if it returns CopyOutDone, then the connection has reverted to the ready state.

putCopyData :: Connection -> ByteString -> IO ()

Feed some data to a COPY FROM STDIN query. Note that the data does not need to represent a single row, or even an integral number of rows. The net result of putCopyData conn a >> putCopyData conn b is the same as putCopyData conn c whenever c == BS.append a b.

A connection must be in the CopyIn state in order to call this function, otherwise a SqlError exception will result. The connection remains in the CopyIn state after this function is called.

putCopyEnd :: Connection -> IO Int64

Completes a COPY FROM STDIN query. Returns the number of rows processed.

A connection must be in the CopyIn state in order to call this function, otherwise a SqlError exception will result. The connection's state changes back to ready after this function is called.

putCopyError :: Connection -> ByteString -> IO ()

Aborts a COPY FROM STDIN query. The string parameter is simply an arbitrary error message that may show up in the PostgreSQL server's log.

A connection must be in the CopyIn state in order to call this function, otherwise a SqlError exception will result. The connection's state changes back to ready after this function is called.