postgresql-simple-0.7.0.1: Mid-Level PostgreSQL client library

Copyright | (c) 2013 Leon P Smith
License | BSD3
Maintainer | Leon P Smith <leon@melding-monads.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

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

- copy :: ToRow params => Connection -> Query -> params -> IO ()
- copy_ :: Connection -> Query -> IO ()
- data CopyOutResult
  - = CopyOutRow !ByteString
  - | CopyOutDone !Int64
- foldCopyData :: Connection -> (a -> ByteString -> IO a) -> (a -> Int64 -> IO b) -> a -> IO b
- getCopyData :: Connection -> IO CopyOutResult
- putCopyData :: Connection -> ByteString -> IO ()
- putCopyEnd :: Connection -> IO Int64
- putCopyError :: Connection -> ByteString -> IO ()

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

#### Instances

Instances details

Show CopyOutResult Source # |
Instance details Defined in Database.PostgreSQL.Simple.Copy Methods showsPrec :: Int -> CopyOutResult -> ShowS Source # show :: CopyOutResult -> String Source # showList :: [CopyOutResult] -> ShowS Source #
Eq CopyOutResult Source # |
Instance details Defined in Database.PostgreSQL.Simple.Copy Methods (==) :: CopyOutResult -> CopyOutResult -> Bool Source # (/=) :: CopyOutResult -> CopyOutResult -> Bool Source #

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.