Geodatabase transactions provide an editing pattern for a set of edits to be committed or rolled back as a single batch. When initiated by the user, these batched edits are known as explicit transactions. Explicit transactions are only available when editing a mobile geodatabase on the device (also called a local geodatabase). See the discussion of mobile geodatabases in the Work with data files topic to learn how to create a mobile geodatabase.
Note that editing is not supported for a mobile geodatabase created in ArcGIS Pro that contains a controller dataset, such as a utility network or parcel fabric. Feature tables in such a geodatabase are read-only.
When to use explicit transactions
Explicit transactions are useful in a variety of scenarios, such as the following.
-
A mobile worker collecting data in the field realizes they have entered several edits for the incorrect feature. If your app uses transactions for data input, the worker can roll back the set of erroneous edits and try inputting the data for the correct feature.
-
In a complex data architecture, such as a representation of an electrical network, a single edit touches several feature tables. Using a transaction can ensure that these required table updates are saved together or fail together.
-
While adding a new subnetwork controller in a utility network, a designer may need to create features, establish associations between them, and run a trace to verify the subnetwork. These steps can be made in an explicit transaction so that the assets and their relationships are saved to the local geodatabase together they can also be rolled back together, in case of any errors in the design.
Make edits inside a transaction
You can start a transaction by calling beginTransaction() on the geodatabase that contains the data you want to edit. The transaction stays active until you end it either by committing or rolling back. Use Geodatabase::isInTransaction() to check whether or not the geodatabase has a current transaction.
// Check if the geodatabase is not in a transaction. if (!geodatabase->isInTransaction()) { // Since the geodatabase is not in a transaction, begin one. geodatabase->beginTransaction(); } Add or delete features, update feature geometry and attributes, edit feature attachments and related features, and so on. All edits you make will be included in the current transaction. You can include individual edits as well as bulk edits (inserting a set of features, for example).
End a transaction by committing or rolling back edits. To make further further edits and manage them in a transaction, call Geodatabase::beginTransaction() to start a new one.
Commit edits
To save all edits made in the active transaction, call Geodatabase::commitTransaction(). The edits are saved to the local geodatabase.
// Make sure the geodatabase has an active transaction // before attempting to commit. if (geodatabase->isInTransaction()) { // If there is an active transaction, this call performs // a commit to store the edits and ends the transaction. geodatabase->commitTransaction(); } Rollback edits
To reject all edits made in the active transaction, call Geodatabase::rollbackTransaction(). The edits are not saved to the local geodatabase.
// Make sure the geodatabase has an active transaction // before attempting to rollback. if (geodatabase->isInTransaction()) { // If there is an active transaction, this call rolls back (discards) // the edits and ends the transaction. geodatabase->rollbackTransaction(); } If you are unexpectedly disconnected from the database, any active transaction is automatically rolled back. If the app crashes or the user closes the app without saving their edits, for example, the transaction is rolled back and the edits discarded.
Handle changes in transaction state (optional)
Your app can listen for changes in the transaction state. The event you receive indicates whether a transaction is beginning or ending.
You might use this information to enable and disable editing controls as appropriate.
// Signal/slot that determines if the geodatabase transaction status has changed. connect(geodatabase, &Geodatabase::transactionStatusChanged, this, [](bool isInTransaction) { // Test if the goedatabase is in a transaction. if(isInTransaction) { // Handle the transaction starting. // ... } else { // Handle the transaction ending. // ... } }); Synchronization vs explicit transaction
It is important to distinguish between synchronization of the local geodatabase and creating an explicit transaction on the local geodatabase.
Synchronization keeps your local geodatabase up to date with the feature service from which it was generated. Use Geodatabase::hasLocalEdits() to check if there are any new edits saved to the local geodatabase since the last time you synchronized. The method GeodatabaseFeatureTable::hasLocalEditsSince() returns those edits saved to the local geodatabase but not yet synchronized. The geodatabase feature table includes other methods that work with local edits; see GeodatabaseFeatureTable and search for LocalEdits.
An explicit transaction groups together those edits that you want to treat as a unit, saving them to the local geodatabase or rolling them back. You can create multiple transactions between synchronizations.
One geodatabase transaction at a time
There can be only one transaction active in your app at a time. It is important to note that a transaction can be created in two different ways:
- Explicitly in your code by calling
Geodatabase::beginTransaction(). - Internally by Qt Maps SDK when you synchronize the local geodatabase with the feature service from which it was generated.
Whether you create an explicit transaction or Qt Maps SDK creates an internal transaction, you can still have only one transaction. Therefore, you should not:
- Start a new explicit transaction until you have called
commitTransaction()orrollbackTransaction()to end the current one. - Start an explicit transaction during a synchronization of the local geodatabase with the feature service.
- Synchronize the data while you still have an explicit transaction active.
The safest way to enforce these restrictions is to check the Geodatabase::isInTransaction() property before starting, committing, or rolling back an explicit transaction. Attempting to start more than one transaction at the same time will return an error stating that a transaction is already in progress.
Immediate transaction mode
Qt Maps SDK uses the immediate transaction mode supported by SQLite. When you begin a transaction, the geodatabase is locked for writing. Other processes on your device can read the geodatabase, but are not able to write or see your uncommitted edits. Immediate transaction mode is the reason only one transaction is permitted on the local geodatabase at a time.