GOLF(2gg)

✨ GOLF(2gg) ✨

okay bestie, so we're in the 2gg section of the manual, and today's main character is begin-transaction 💅 she's a database girlie and honestly? she's the moment.

---

💖 NAME 💖

begin-transaction — starts a database transaction (yes that's the whole vibe, keep reading though it gets juicy) 🫶

---

🎀 PURPOSE 🎀

Begins a database transaction. that's it. that's the purpose. iconic, lowkey.

---

🌸 SYNTAX 🌸

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

like, everything in the brackets is optional but you're gonna want some of it, trust 🦋

---

💅 DESCRIPTION 💅

So this statement begins a database transaction. fr fr, that's what it does.

<options> (the one in the "options" clause) is any additional options you want to send to the database — whatever extra stuff you wish to supply for this functionality. it's giving "you know what you're doing" energy.

Once you start a transaction with begin-transaction, you must either commit it with commit-transaction or rollback with rollback-transaction. that's not a suggestion, that's the rules. 🚨

Not me leaving a transaction open... 😭 If you do neither, your transaction will be rolled back once the request has completed, and your program will stop with an error message. Because opening a transaction and then just walking out without committing or rolling back? that is a bug in your program. periodt.

Also important, bestie: you must use begin-transaction, commit-transaction and rollback-transaction instead of calling this functionality through run-query. no shortcuts, no cap.

---

🗄️ DATABASE 🗄️

<database> is specified in the "@" clause, and it's the name of the database-config-file. 📁

If you omit it, your program must use exactly one database — see the --db option in gg. one database only, no side-eyes at the others.

---

⚠️ ERROR HANDLING ⚠️

The error code is available in the <error> variable in the "error" clause — this code is always "0" if it's successful. 💚

The <error> code may or may not be a number, but it's always returned as a string value. quirky, but that's her.

In case of error, error text is available in the "error-text" clause in the <error text> string. 📝

The "on-error-continue" clause says request processing will continue in case of an error, whereas "on-error-exit" says it will exit. This setting overrides the database-level db-error for this specific statement only. So if you use "on-error-continue", be sure to check the error code — do not skip the vibe check on that one 🙈

Also: if the database connection was lost, and could not be reestablished, the request will error out (see error-handling). that one's out of your hands, bestie 💀

---

🌈 EXAMPLES 🌈

here's the whole little love story, start to finish:

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

see? begin, do the thing, commit. clean, no loose ends, we love to see it ✨

---

👑 SEE ALSO 👑

• Database

and also, the whole squad:

• begin-transaction
• commit-transaction
• current-row
• database-config-file
• db-error
• mariadb-database
• postgresql-database
• rollback-transaction
• run-query
• sqlite-database

See all documentation 📚

---

okay that's the whole page bestie, you ate that 💖 this was the $VERSION of the page, dated $DATE, and it lives in GOLF(2gg) — go commit something (literally) 🎀✨