Orville.PostgreSQL.Execution.Insert

Functions for working with executable INSERT statements. The Insert type is a value that can be passed around and executed later. The Insert 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 executeInsert or executeInsertReturnEntities as appropriate. It is a lower-level API than the entity insert functions in Orville.PostgreSQL.Execution.EntityOperations, but not as primitive as Orville.PostgreSQL.Expr.Insert.

Since: 1.0.0.0

Documentation

data Insert readEntity returningClause

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

Since: 1.0.0.0

insertToInsertExpr :: Insert readEntity returningClause -> InsertExpr

Extracts the query that will be run when the insert 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

executeInsert :: MonadOrville m => Insert readEntity NoReturningClause -> m Int

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

Since: 1.0.0.0

executeInsertReturnEntities :: MonadOrville m => Insert readEntity ReturningClause -> m [readEntity]

Executes the database query for the Insert and uses its SqlMarshaller to decode the rows (that were just inserted) as returned via a RETURNING clause.

Since: 1.0.0.0

insertToTableReturning :: TableDefinition key writeEntity readEntity -> NonEmpty writeEntity -> Insert readEntity ReturningClause

Builds an Insert that will insert 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.

Since: 1.0.0.0

insertToTable :: TableDefinition key writeEntity readEntity -> NonEmpty writeEntity -> Insert readEntity NoReturningClause

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

Since: 1.0.0.0

rawInsertExpr :: ReturningOption returningClause -> AnnotatedSqlMarshaller writeEntity readEntity -> InsertExpr -> Insert readEntity returningClause

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

This is the lowest level of escape hatch available for Insert. The caller can build any query that Orville supports using the expression-building functions, or use RawSql.fromRawSql to build a raw InsertExpr. It is expected that the ReturningOption given matches the InsertExpr. This level of interface does not provide an automatic enforcement of the expectation, however failure is likely if that is not met.

Since: 1.0.0.0