Orville.PostgreSQL.Execution.Update

Functions for working with executable UPDATE statements. The Update type is a value that can be passed around and executed later. The Update is directly associated with the presence of a returning clause and how to decode any rows returned by that clause. This means it can be safely executed via executeUpdate or executeUpdateReturnEntities as appropriate. It is a lower-level API than the entity update functions in Orville.PostgreSQL.Execution.EntityOperations, but not as primitive as Orville.PostgreSQL.Expr.Update.

Since: 1.0.0.0

Documentation

data Update readEntity returningClause

Represents an UPDATE statement that can be executed against a database. An Update has a SqlMarshaller bound to it that, when the update returns data from the database, will be used to decode the database result set when it is executed.

Since: 1.0.0.0

updateToUpdateExpr :: Update readEntity returningClause -> UpdateExpr

Extracts the query that will be run when the update is executed. Normally you don't want to extract the query and run it yourself, but this function is useful to view the query for debugging or query explanation.

Since: 1.0.0.0

executeUpdate :: MonadOrville m => Update readEntity returningClause -> m Int

Executes the database query for the Update and returns the number of affected rows.

Since: 1.0.0.0

executeUpdateReturnEntities :: MonadOrville m => Update readEntity ReturningClause -> m [readEntity]

Executes the database query for the Update and uses its AnnotatedSqlMarshaller to decode any rows that were just updated, as returned via a RETURNING clause.

Since: 1.0.0.0

updateToTableReturning :: TableDefinition (HasKey key) writeEntity readEntity -> key -> writeEntity -> Maybe (Update readEntity ReturningClause)

Builds an Update that will update all of the writable columns described in the TableDefinition and return the data as seen by the database. This is useful for getting database-managed columns such as auto-incrementing identifiers and sequences.

This function returns Nothing if the TableDefinition has no columns, which would otherwise generate an Update with invalid SQL syntax.

Since: 1.0.0.0

updateToTable :: TableDefinition (HasKey key) writeEntity readEntity -> key -> writeEntity -> Maybe (Update readEntity NoReturningClause)

Builds an Update that will update all of the writable columns described in the TableDefinition without returning the data as seen by the database.

This function returns Nothing if the TableDefinition has no columns, which would otherwise generate and Update with invalid SQL syntax.

Since: 1.0.0.0

updateToTableFieldsReturning :: TableDefinition key writeEntity readEntity -> NonEmpty SetClause -> Maybe BooleanExpr -> Update readEntity ReturningClause

Builds an Update that will apply the specified column set clauses to rows within the specified table and return the updated version of any rows affected by the update state by using a RETURNING clause.

Since: 1.0.0.0

updateToTableFields :: TableDefinition key writeEntity readEntity -> NonEmpty SetClause -> Maybe BooleanExpr -> Update readEntity NoReturningClause

Builds an Update that will apply the specified column set clauses to rows within the specified table without returning the data as seen by the database.

Since: 1.0.0.0

rawUpdateExpr :: ReturningOption returningClause -> AnnotatedSqlMarshaller writeEntity readEntity -> UpdateExpr -> Update readEntity returningClause

Builds an Update that will execute the specified query and use the given AnnotatedSqlMarshaller to decode it. It is up to the caller to ensure that the given UpdateExpr makes sense and produces a value that can be stored, as well as returning a result that the AnnotatedSqlMarshaller can decode.

This is the lowest level of escape hatch available for Update. The caller can build any query that Orville supports using the expression-building functions, or use RawSql.fromRawSql to build a raw UpdateExpr.

Since: 1.0.0.0