postgresql-simple-0.6.5: Mid-Level PostgreSQL client library
Copyright(c) 2013 Leon P Smith
LicenseBSD3
MaintainerLeon P Smith <leon@melding-monads.com>
Stabilityexperimental
Safe HaskellSafe-Inferred
LanguageHaskell2010

Database.PostgreSQL.Simple.Copy

Description

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.

Synopsis

Documentation

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

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 substitution.

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

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 Source #

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.

foldCopyData Source #

Arguments

:: Connection

Database connection

-> (a -> ByteString -> IO a)

Accumulate one row of the result

-> (a -> Int64 -> IO b)

Post-process accumulator with a count of rows

-> a

Initial accumulator

-> IO b

Result

Fold over COPY TO STDOUT query passing each copied row to an accumulator and calling a post-process at the end. A connection must be in the CopyOut state in order to call this function.

Example

(acc, count) <- foldCopyData conn
    (\acc row -> return (row:acc))
    (\acc count -> return (acc, count))
    []

getCopyData :: Connection -> IO CopyOutResult Source #

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 () Source #

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 Source #

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 () Source #

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.