CSV to Airtable Sync — Dry-Run First, Every Time

The sample file

The package includes a sample CSV and config so you can see the whole loop with no Airtable account: 2 valid rows and 2 intentional rejections. sample_customers.csv, as shipped:

The field-mapping config (sample_config.json)

{
  "key_column": "customer_id",
  "key_field": "External ID",
  "field_mapping": {
    "customer_id": "External ID",
    "name": "Customer Name",
    "email": "Email",
    "monthly_spend": "Monthly Spend",
    "active": "Active"
  },
  "required": ["customer_id", "name", "email"],
  "types": {
    "monthly_spend": "number",
    "active": "boolean"
  }
}

The dry run — nothing is written

Dry-run is the default: the whole file is validated first and nothing touches Airtable until --commit is added — and a commit refuses the entire file if even one row is rejected. Here is the actual dry run on the sample: the summary it prints, and the rejections.jsonl it writes, with a row-level reason for each rejected row.

$ python3 sync.py sample_customers.csv --config sample_config.json
{
  "valid": 2,
  "rejected": 2,
  "committed": false
}
exit code: 0

--- rejections.jsonl (written by the dry run) ---
{"reason": "missing required value: name", "row": {"active": "true", "customer_id": "C-1003", "email": "missing-name@example.com", "monthly_spend": "500", "name": ""}, "row_number": 4}
{"reason": "duplicate key in CSV: C-1002", "row": {"active": "false", "customer_id": "C-1002", "email": "duplicate@example.com", "monthly_spend": "100", "name": "Duplicate Studio"}, "row_number": 5}

From the package

Screenshots shipped inside the Codester package.

What it does

• Dry-run by default; --commit is the only way anything is written
• All-or-nothing commits: one rejected row stops the whole import
• Full pre-validation: headers, row widths, required values, duplicate keys, numeric/boolean checks
• Field mapping from a small JSON config; merge field drives performUpsert — re-runs don't duplicate
• Rejected rows saved to JSONL with row-level reasons, ready to fix and replay
• Token read from the AIRTABLE_TOKEN environment variable; never printed or stored
• Batches at Airtable's 10-record limit; rate limits handled
• Sample CSV and config included: 2 valid rows, 2 intentional rejections, so you see the whole loop with no account