Apex Execute Anonymous

Apex Execute Anonymous

Activate when running ad-hoc Apex — investigation, data fixes, one-off operations. Execute Anonymous commits DML on success (unlike tests), runs as the authenticated user, and surfaces errors via debug logs. Misunderstand any of these and you'll destroy data or corrupt a production org.

Before Starting

• Confirm org and user. sf org display — especially before running against production.
• Plan rollback. Anonymous Apex commits by default. Add Database.setSavepoint/Database.rollback for reversibility.
• Estimate record volume. Anonymous runs the full governor budget once; bulk work past ~10k records must be Batch-ified.

Core Concepts

Script structure

// my-fix.apex
List<Account> accs = [SELECT Id, Rating FROM Account WHERE Rating = null LIMIT 200];
for (Account a : accs) a.Rating = 'Warm';
update accs;
System.debug('Updated ' + accs.size());

CLI invocation

sf apex run --target-org prod --file scripts/my-fix.apex

Output streams the debug log. Errors appear inline.

Transaction semantics

• Auto-commits on success. No implicit savepoint.
• Rolls back on uncaught exception. Partial DML is reverted.
• Can wrap manually with Database.setSavepoint() + Database.rollback(sp).

Variable scope

Variables declared at the top live for the whole anonymous script. No class wrapper; the whole script runs inside an implicit System.runUpdate-like anonymous block.

What you CAN'T do

• Define a method (only inline code and inner classes).
• Run test classes (Test.startTest is legal but you can't @IsTest-annotate code).
• Use global/public modifiers at the top level.
• Access protected members of a class outside its namespace.

Debug output

System.debug() goes to the user's debug log. For sf apex run, the log returns to stdout. Set Apex Code log level to FINE or FINEST for variable values.

Common Patterns

Pattern: Savepoint-guarded data fix

Savepoint sp = Database.setSavepoint();
try {
    List<Contact> cs = [SELECT Id, Email FROM Contact WHERE Email LIKE '%@old.com' LIMIT 200];
    for (Contact c : cs) c.Email = c.Email.replace('@old.com', '@new.com');
    update cs;
    System.debug('Updated ' + cs.size());
    // Flip commented lines to actually apply:
    Database.rollback(sp);
} catch (Exception e) {
    Database.rollback(sp);
    System.debug(e);
}

Pattern: run with rollback first to see effect; flip to commit after review.

Pattern: Iteration-bounded cleanup

Integer MAX = 200;
List<Case> oldCases = [SELECT Id FROM Case WHERE Status = 'Closed' AND IsDeleted = false LIMIT :MAX];
if (oldCases.size() == MAX) {
    System.debug('Limit hit — run again or use Batch Apex');
}
delete oldCases;

Pattern: Dry-run toggle

Boolean APPLY = false;
// ... build list of updates
System.debug('Would update ' + updates.size() + ' records');
if (APPLY) update updates;

Decision Guidance

Recommended Workflow

1. Confirm org with sf org display --target-org <alias> — especially before prod.
2. Write script with dry-run toggle OR savepoint + rollback first.
3. Run via sf apex run --file script.apex --target-org <alias>.
4. Inspect debug log output for the counts/side-effects.
5. Flip apply flag OR comment out the rollback, re-run.
6. Archive the script in a scripts/ directory committed to version control.
7. For production, require peer review before --target-org prod.

Review Checklist

• Target org confirmed explicitly (never rely on default config for prod)
• Savepoint or dry-run toggle present for DML scripts
• Record count bounded via LIMIT clause
• Debug output includes before/after counts
• Script saved to repo for audit trail
• Peer review for any production anonymous script

Salesforce-Specific Gotchas

1. Anonymous Apex commits on success. There is no implicit savepoint. A runaway loop will destroy data before you can interrupt.
2. sf apex run without --file reads from stdin — useful for piped commands but easy to confuse with execution against stdin-EOF.
3. Governor limits are per-execution, not per-statement. A 50k-record loop inside anonymous hits CPU/DML-row caps. Use Batch for volume.
4. Declaring a method fails: Anonymous cannot contain top-level method definitions. Wrap reusable logic in an inner class with a method, then call new MyInner().doThing().
5. Debug log level affects output. If you see System.debug() lines missing, raise Apex Code to FINE.

Output Artifacts

Related Skills

• apex/apex-savepoint-and-rollback — transactional control details
• apex/apex-batch-patterns — for volume fixes
• devops/salesforce-dx-source-tracking — CLI fundamentals