Orville.PostgreSQL.Execution.Cursor

Functions and types for working with PostgreSQL cursors. You can use cursors to execute a query and consume rows from the result set incrementally. Rows that you do not consume will never be sent from the database to the client.

Since: 1.0.0.0

Documentation

data Cursor readEntity

A Cursor allows you to fetch rows incrementally from PostgreSQL. Using a cursor will allow you to execute a query that returns a very large result set without the entire result set being loaded in memory in your application and instead pulling rows as you're able to process them.

See withCursor, fetch and move for details on creating and using Cursor values.

Since: 1.0.0.0

withCursor :: MonadOrville m => Maybe ScrollExpr -> Maybe HoldExpr -> Select readEntity -> (Cursor readEntity -> m a) -> m a

Declares a CURSOR in PostgreSQL that is available for the duration of the action passed to withCursor and closes the cursor when that action completes (or raises an exception).

See https://www.postgresql.org/docs/current/sql-declare.html for details about the ScrollExpr and HoldExpr parameters and how cursors behave in general.

We recommend you use this instead of declareCursor and closeCursor unless you need to control the cursor resource acquisition and release yourself and can do so safely.

Since: 1.0.0.0

declareCursor :: MonadOrville m => Maybe ScrollExpr -> Maybe HoldExpr -> Select readEntity -> m (Cursor readEntity)

Declares a CURSOR in PostgreSQL and returns it for you to use. The cursor must be closed via closeCursor (or another means) when you are done using it. Generally you should use withCursor instead of declareCursor to ensure that the cursor gets closed properly.

See https://www.postgresql.org/docs/current/sql-declare.html for details about the ScrollExpr and HoldExpr parameters and how cursors behave in general.

Since: 1.0.0.0

closeCursor :: MonadOrville m => Cursor readEntity -> m ()

Closes a CURSOR in PostgreSQL that was previously declared. This should be used to close any cursors you open via declareCursor, though we recommend you use withCursor instead to ensure that any opened cursors are closed in the event of an exception.

Since: 1.0.0.0

fetch :: MonadOrville m => Maybe CursorDirection -> Cursor readEntity -> m [readEntity]

Fetch rows from a cursor according to the CursorDirection given. See https://www.postgresql.org/docs/current/sql-fetch.html for details about the effects of fetch and the meanings of cursor directions to PostgreSQL.

Since: 1.0.0.0

move :: MonadOrville m => Maybe CursorDirection -> Cursor readEntity -> m ()

Moves a cursor according to the CursorDirection given. See https://www.postgresql.org/docs/current/sql-fetch.html for details about the effect of move and the meanings of cursor directions to PostgreSQL.

Since: 1.0.0.0

data CursorDirection

CursorDirection corresponds to the direction argument to the SQL FETCH and MOVE statements. E.G.

BACKWARD

See PostgreSQL fetch documentation for more information.

CursorDirection provides a SqlExpression instance. See unsafeSqlExpression for how to construct a value with your own custom SQL.

Since: 1.0.0.0

Instances

SqlExpression CursorDirection

Since: 1.0.0.0

Defined in Orville.PostgreSQL.Expr.Cursor

Methods

toRawSql :: CursorDirection -> RawSql

unsafeFromRawSql :: RawSql -> CursorDirection

next :: CursorDirection

Specify the direction of the next single row. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

prior :: CursorDirection

Specify the direction of the prior single row. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

first :: CursorDirection

Specify the direction of the first single row. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

last :: CursorDirection

Specify the direction of the last single row. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

absolute :: Int -> CursorDirection

Specify the direction of the single row at an absolute position within the cursor. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

relative :: Int -> CursorDirection

Specify the direction of the single row relative to the cursor's current position. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

count :: ValueExpression -> ValueExpression

Given a ValueExpression, use it as the argument to the SQL count.

Since: 1.0.0.0

fetchAll :: CursorDirection

Specify the direction of all the next rows. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

forward :: CursorDirection

Specify the direction of the next single row. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

forwardCount :: Int -> CursorDirection

Specify the direction of the next n rows. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

forwardAll :: CursorDirection

Specify the direction of all the next rows. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

backward :: CursorDirection

Specify the direction of the prior single row. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

backwardCount :: Int -> CursorDirection

Specify the direction of the prior n rows. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0

backwardAll :: CursorDirection

Specify the direction of all the prior rows. Primarily for use with fetch or move.

See PostgreSQL fetch documentation for more information.

Since: 1.0.0.0