Acumatica Database Migration Strategy

Acumatica Database Migration Strategy is the Acumatica operations topic that you only get good at by doing it badly a few times. The first upgrade is always a surprise; the second is a learning; the third is a process. This guide is the process — the planning, the execution, the validation, the rollback — that turns the upgrade from a high-risk event into a routine maintenance task.

The Acumatica release cadence

Acumatica ships two major releases per year — R1 (around March) and R2 (around September). Each release introduces new features, deprecates old ones, and occasionally makes breaking changes. The customisation you ship today must survive the next 4-6 releases without intervention.

Four weeks out

The first step is reading. The release notes are 50-100 pages; they tell you:

• What is new (and how it might interact with your customisation).
• What is deprecated (and whether your code uses it).
• What is breaking (and the migration path).
• What is fixed (and whether the fix changes your workaround).

# Acumatica [VERSION] Upgrade Plan

## Pre-upgrade
- [ ] Release notes read cover to cover (twice)
- [ ] Breaking changes identified for our customisations
- [ ] Top 20 screens identified by user count
- [ ] Staging tenant with production data
- [ ] Database backup verified

## Upgrade day
- [ ] Pre-upgrade database backup
- [ ] Apply upgrade
- [ ] Run post-upgrade scripts
- [ ] Smoke test top 20 screens
- [ ] Run regression suite
- [ ] Verify customisation compilation
- [ ] Hand the tenant back

For the broader upgrade checklist, see the upgrade checklist and the customisation upgrade survival guide.

Two weeks out

Apply the upgrade to the staging tenant. Run the test suite. The first wave of issues is usually:

• Compilation errors. A method signature changed; your code does not compile. Fix the call sites.
• Missing fields. A field was renamed or removed; your code references it. Update the references.
• Behavioural changes. An event fires differently; a workflow transitions differently. Update the handlers.
• New defaults. A new field is required; your data does not have it. Backfill.

// Use conditional compilation to handle multiple versions
#if ACUMATICA_2025R2_OR_NEWER
    var result = Base.NewMethod();
#else
    var result = Base.LegacyMethod();
#endif

One week out

Schedule the production upgrade window. The window should be:

• Long enough for the upgrade, the smoke test, and the rollback if needed (typically 4-8 hours).
• At a known low-traffic time (typically Friday evening or Saturday morning for a 24/7 business).
• With the rollback plan tested and ready to execute.
• With all stakeholders notified in advance.

Upgrade day

The sequence:

1. Pre-upgrade backup. Database, file share, IIS config. The backup that lets you roll back.
2. Apply the upgrade. Run the Acumatica upgrade tool. This is the longest single step.
3. Post-upgrade scripts. Any database scripts that need to run after the framework upgrade.
4. Smoke test. Walk the top 20 screens. Verify they render, the data is correct, the workflows transition.
5. Regression suite. Run the automated test suite. Failures are signals.
6. Hand the tenant back. Communicate to the user base that the upgrade is complete.

# If the smoke test fails, execute the rollback:

# 1. Stop IIS
iisreset /stop

# 2. Restore the database
sqlcmd -S sqlserver -d acumatica -Q "RESTORE DATABASE acumatica FROM DISK = 'C:\Backups\pre-upgrade.bak' WITH REPLACE, RECOVERY;"

# 3. Restore the file share
robocopy "C:\Backups\fileshare" "C:\Acumatica\Files" /MIR

# 4. Restart IIS
iisreset /start

For the broader disaster recovery patterns, see the disaster recovery guide and the backup and restore guide.

Post-upgrade

The 48 hours after the upgrade are the highest-risk period. The monitoring:

• Error rate. A spike in errors indicates a customisation that worked on staging but not on production.
• Performance. A slow screen indicates a new query plan that is not as efficient as the old one.
• User reports. A new ticket is often a regression. Investigate, don't dismiss.
• Workflow failures. A transition that did not fire is a data model or handler issue.

CI/CD for customisations

The customisation that is not in source control is the customisation that will be lost. The minimum CI/CD:

1. Source control. Git, with a clear branching strategy.
2. Automated build. Compile the customisation DLL on every commit.
3. Automated test. Run the unit test suite on every commit.
4. Automated publish. On merge to main, publish to a staging tenant.
5. Manual gate. A human approves the promotion to production.

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '8.0.x' }
      - run: dotnet restore
      - run: dotnet build --no-restore
      - run: dotnet test --no-build

For the broader CI/CD patterns, see the CI/CD guide and the pipeline design guide.

Wrapping up

Read the release notes. Test on staging. Schedule the window. Backup before. Smoke test after. Monitor for 48 hours. Document the upgrade. The discipline is the same.