Inserting Records with DML

SOQL reads records out of the database. DML writes them back in, and the simplest write is the insert statement. This lesson walks through what happens between writing new Account(...) and seeing a saved record with an Id.

Build the Record, Then Insert It

A record is an object you construct with its fields, and insert saves it:

Account account = new Account(Name = 'Acme Robotics', Type = 'Customer');
insert account;

Two things happen on that second line. The record is written to the database, and the same object you created is updated in place with the Id of the new row. After insert, account.Id holds the real Salesforce Id, something like 0015g00002AbCdEfAGH.

Because the Id comes back on the object, you can query the row you just made without knowing anything about it beforehand:

List<Account> saved = [SELECT Id, Name FROM Account WHERE Id = :account.Id];

Name Is Required

Name is a required field on Account, and required means the database refuses the row without it. Inserting an Account with no Name throws a DmlException whose message names the problem:

Two details are worth noticing. The message names the FIELD, not the object, so the same exception covers every required field on every object. And a Name made of nothing but spaces counts as missing: the database trims it and finds nothing left. A guard that checks String.isBlank(name) before inserting turns a hard failure into an ordinary branch.

Clean Up With a Savepoint

An insert is permanent. It stays in the database until something deletes it, and in a test or a script that is rarely what you want. A savepoint gives you an undo point:

Savepoint sp = Database.setSavepoint();
insert account;
Database.rollback(sp);

The rollback undoes every change made after the savepoint was taken, so the record disappears and the org is left exactly as it was. Savepoints nest: each setSavepoint call pushes another point onto the stack, and a rollback to an inner point leaves the outer work in place.

Common Mistakes

The first mistake is expecting account.Id to be set before the insert. It is null until the insert runs. The second is forgetting that the insert can fail: an exception from insert leaves the variable assignment from before it untouched, so a method that inserts and then reads account.Id must handle the exception path separately.

The third is a Name that looks blank but is not: a single space passes a check for Name != null and still fails the database. Use String.isBlank when you mean it.

Why This Matters

Every later lesson that updates or deletes records depends on this one. update and delete take the same shape as insert, they can fail the same way, and they need the same savepoint discipline to leave the database as they found it.