Skip to content

How to seed data into an org

Scratch orgs start empty. To give one the reference and sample records a project needs, you seed data into it. The toolchain offers two built-in ways, both driven by sfdx-project.json; for anything genuinely complex, reach for a dedicated data tool instead.

Seeding runs automatically on scratch creation

org scratch-create imports the configured data after it deploys metadata (skip it with --skip-data-import). You can also run either importer on its own against any org with npm run data:import -- --target-org <org> or npm run data:import:csv -- --target-org <org>.

Use this for a small set of records with relationships (an Account with its Contacts and Cases, say). It uses sf data import tree, which preserves the reference graph.

  1. Export a graph from an org that already has the data:

    npm run data:export -- --plan --query "SELECT Id, Name FROM Account WHERE ..." --target-org <org>

    This writes the record JSON plus a *-plan.json that ties the files together.

  2. Commit those files under a data directory (for example datasets/json/).

  3. Register the plan pattern in sfdx-project.json under plugins.diadx.dataImports.planFiles — patterns may use a directory wildcard, and only files ending in -plan.json are imported:

    "plugins": {
    "diadx": {
        "dataImports": { "planFiles": ["datasets/json/**/*"] }
    }
}

npm run data:import (and scratch creation) then imports each plan.

Way 2 — CSV bulk upsert (single-object volume)

Use this for a larger set of records for one object, keyed by an external id so re-runs update rather than duplicate. It uses sf data upsert bulk.

  1. Put the CSV under datasets/csv/.

  2. Register it in sfdx-project.json under plugins.diadx.dataImports.csvFiles, naming the object, the file, and the external-id field:

    "plugins": {
    "diadx": {
        "dataImports": {
            "csvFiles": [
                { "objectType": "Account", "file": "accounts.csv", "externalKey": "External_Id__c" }
            ]
        }
    }
}

npm run data:import:csv (and scratch creation) upserts each file with sf data upsert bulk --sobject <object> --external-id <field>.

When to reach for a dedicated data tool

The built-in importers do not handle circular or self-referential relationships, deep hierarchies, large multi-object graphs, record anonymisation, or precise upsert ordering across many objects. For those, run a purpose-built tool as its own step — the toolchain does not wrap them:

Seed data is committed in clear text

Anything under datasets/ is tracked in the repository. Never commit real customer data or PII — seed with synthetic records only.