Transactions

Database transactions allow your application to make a series of database changes in an all-or-nothing commit. Consider an HTTP request that creates a new Order and has an afterChange hook to update the stock count of related Items. If an error occurs when updating an Item and an HTTP error is returned to the user, you would not want the new Order to be persisted or any other items to be changed either. This kind of interaction with the database is handled seamlessly with transactions. By default, FrogBot will use transactions for all data changing operations, as long as it is supported by the configured database. Database changes are contained within all FrogBot operations and any errors thrown will result in all changes being rolled back without being committed. When transactions are not supported by the database, FrogBot will continue to operate as expected without them.

MongoDB requires a connection to a replicaset in order to make use of transactions.

Transactions in SQLite are disabled by default. You need to pass transactionOptions: {} to enable them.

The initial request made to FrogBot will begin a new transaction and attach it to the req.transactionID. If you have a hook that interacts with the database, you can opt in to using the same transaction by passing the req in the arguments. For example:

const afterChange: CollectionAfterChangeHook = async ({ req }) => {
  // because req.transactionID is assigned from FrogBot and passed through,
  // my-slug will only persist if the entire request is successful
  await req.frogbot.create({
    req,
    collection: 'my-slug',
    overrideAccess: true,
    data: {
      some: 'data',
    },
  })
}

Async Hooks with Transactions

Since FrogBot hooks can be async and be written to not await the result, it is possible to have an incorrect success response returned on a request that is rolled back. If you have a hook where you do not await the result, then you should not pass the req.transactionID.

const afterChange: CollectionAfterChangeHook = async ({ req }) => {
  // WARNING: an async call made with the same req, but NOT awaited,
  // may fail resulting in an OK response being returned with response data that is not committed
  const dangerouslyIgnoreAsync = req.frogbot.create({
    req,
    collection: 'my-slug',
    overrideAccess: true,
    data: {
      some: 'other data',
    },
  })

  // Should this call fail, it will not rollback other changes
  // because the req (and its transactionID) is not passed through
  const safelyIgnoredAsync = req.frogbot.create({
    collection: 'my-slug',
    overrideAccess: true,
    data: {
      some: 'other data',
    },
  })
}

Direct Transaction Access

When writing your own scripts or custom endpoints, you may wish to have direct control over transactions. This is useful for interacting with your database outside of FrogBot’s Local API. The following functions can be used for managing transactions:

frogbot.db.beginTransaction - Starts a new session and returns a transaction ID for use in other FrogBot Local API calls.
frogbot.db.commitTransaction - Takes the identifier for the transaction, finalizes any changes.
frogbot.db.rollbackTransaction - Takes the identifier for the transaction, discards any changes.

FrogBot uses the req object to pass the transaction ID through to the database adapter. If you are not using the req object, you can make a new object to pass the transaction ID directly to database adapter methods and Local API calls. Example:

import frogbot from 'frogbot'
import config from './frogbot.config'

const standaloneFrogBotScript = async () => {
  // initialize FrogBot
  await frogbot.init({ config })

  const transactionID = await frogbot.db.beginTransaction()

  try {
    // Make an update using the Local API
    await frogbot.update({
      collection: 'posts',
      overrideAccess: true,
      data: {
        some: 'data',
      },
      where: {
        slug: { equals: 'my-slug' },
      },
      req: { transactionID },
    })

    /*
      You can make additional db changes or run other functions
      that need to be committed on an all or nothing basis
     */

    // Commit the transaction
    await frogbot.db.commitTransaction(transactionID)
  } catch (error) {
    // Rollback the transaction
    await frogbot.db.rollbackTransaction(transactionID)
  }
}

standaloneFrogBotScript()

Disabling Transactions

If you wish to disable transactions entirely, you can do so by passing false as the transactionOptions in your database adapter configuration. All the official FrogBot database adapters support this option. In addition to allowing database transactions to be disabled at the adapter level. You can prevent FrogBot from using a transaction in direct calls to the Local API by adding disableTransaction: true to the args. For example:

await frogbot.update({
  collection: 'posts',
  overrideAccess: true,
  data: {
    some: 'data',
  },
  where: {
    slug: { equals: 'my-slug' },
  },
  disableTransaction: true,
})

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Async Hooks with Transactions

Direct Transaction Access

Disabling Transactions

​Async Hooks with Transactions

​Direct Transaction Access

​Disabling Transactions

Async Hooks with Transactions

Direct Transaction Access

Disabling Transactions