Staged Changes

NetBox provides a programmatic API to stage the creation, modification, and deletion of objects without actually committing those changes to the active database. This can be useful for performing a "dry run" of bulk operations, or preparing a set of changes for administrative approval, for example.

To begin staging changes, first create a branch:

from extras.models import Branch

branch1 = Branch.objects.create(name='branch1')

Then, activate the branch using the checkout() context manager and begin making your changes. This initiates a new database transaction.

from extras.models import Branch
from netbox.staging import checkout

branch1 = Branch.objects.get(name='branch1')
with checkout(branch1):
    Site.objects.create(name='New Site', slug='new-site')
    # ...

Upon exiting the context, the database transaction is automatically rolled back and your changes recorded as staged changes. Re-entering a branch will trigger a new database transaction and automatically apply any staged changes associated with the branch.

To apply the changes within a branch, call the branch's commit() method:

from extras.models import Branch

branch1 = Branch.objects.get(name='branch1')
branch1.commit()

Committing a branch is an all-or-none operation: Any exceptions will revert the entire set of changes. After successfully committing a branch, all its associated StagedChange objects are automatically deleted (however the branch itself will remain and can be reused).