Begin transaction

Purpose: Begins database transaction.

 begin-transaction [ @<database> ] \
     [ on-error-continue | on-error-exit ] \
     [ error <error> ] [ error-text <error text> ] \
     [ options <options> ]

This statement begins a database transaction.

<options> (in "options" clause) is any additional options to send to database you wish to supply for this functionality.

Once you start a transaction with begin-transaction, you must either commit it with commit-transaction or rollback with rollback-transaction. If you do neither, your transaction will be rolled back once the request has completed and your program will stop with an error message. This is because opening a transaction and leaving without committing or a rollback is a bug in your program.

You must use begin-transaction, commit-transaction and rollback-transaction instead of calling this functionality through run-query.

Database

<database> is specified in "@" clause and is the name of the database-config-file. If ommited, your program must use exactly one database (see --db option in gg).

Error handling

The error code is available in <error> variable in "error" clause - this code is always "0" if successful. The <error> code may or may not be a number but is always returned as a string value. In case of error, error text is available in "error-text" clause in <error text> string.

"on-error-continue" clause specifies that request processing will continue in case of an error, whereas "on-error-exit" clause specifies that it will exit. This setting overrides database-level db-error for this specific statement only. If you use "on-error-continue", be sure to check the error code.

Note that if database connection was lost, and could not be reestablished, the request will error out (see error-handling).

Examples

 begin-transaction @mydb
 run-query @mydb="insert into employee (name, dateOfHire) values ('%s', now())" input "Terry" no-loop
 commit-transaction @mydb