The simplest reliable import path is often to read structured Markdown directly. If the files already use consistent headings and fenced sections, converting them with AI or squeezing long text into CSV adds work without improving the database update.
The design decision
A reusable command is a good first interface for bulk content updates. It can parse files, map each file to a known record, show a preview, and then save only approved fields.
The important optimization is not raw database speed. For a modest set of records, predictable parsing and safe matching save more time than complex batching.
A practical import process
- Define the file format. Give every content section a stable heading or marker.
- Map files to records. Use an explicit identifier map instead of guessing from a title.
- Parse without rewriting. Preserve Markdown, line breaks, and template placeholders exactly.
-
Preview the changes. Show the target record and changed fields before writing.
-
Update only the intended fields. Keep publishing or downstream generation as a separate action.
Why not convert everything first?
JSON is useful when building a long-term interchange format because it can carry identifiers and metadata. CSV is convenient for simple mappings, but awkward for multiline content. AI is helpful for inconsistent source documents, not for deterministic files that already have a stable structure.
Common mistakes
- Cause: matching records by editable titles. Fix: use stable IDs or unique keys.
-
Cause: treating an update as an upsert without a real unique database constraint. Fix: define the conflict key explicitly.
-
Cause: importing and publishing in one irreversible step. Fix: preview, save, verify, then publish separately.
-
Cause: letting a converter alter placeholders. Fix: validate that required tokens remain unchanged.
Design the importer before claiming it exists
This is a proposed import design, not evidence that a particular command has been implemented. Define repeated-heading behavior, malformed-file errors, missing identifiers, and atomicity first. A dry run should report the exact target and changed fields. Repeating the same import should produce no additional records or unintended changes.
Start with a small, repeatable command that reads the existing Markdown directly. The next action is to create the explicit file-to-record mapping before writing the importer.