Skip to main content

File Structure

A CSDB file is a UTF-8 text file divided into named sections. A section starts with a header line and continues until the next section header or end of file.

--- <section_name>
section content

Section Names​

The database metadata section is:

--- csdb

Table sections use:

--- table:<table_name>:schema
--- table:<table_name>:data

Machine sections use:

--- row_index:<table_name>:<primary_key_columns>
--- section_index                                                               
--- footer

Readers must reject unknown section headers.

Each table must have both a schema section and a data section. A table name must not appear more than once as a complete table.

Table names must use letters, numbers, and these symbols in any order: _, -, ., $.

Readers must reject table section names that do not follow this rule.

Valid:

workers
Workers
_archive
old-records
invoice.line
tenant$table
work_sessions
invoice_line_2
2_items

Invalid:

work sessions
orders/2026
table:name

Required Order​

The database section must appear first. Readers must reject files whose first section is not --- csdb. Human table sections must be grouped by table in this order:

--- csdb
--- table:workers:schema
--- table:workers:data
--- table:sessions:schema
--- table:sessions:data

Machine sections, when present, must appear after all human sections. The required machine order is primary-key row indexes, section_index, then footer.

Readers must reject sections that are out of order. Writers must emit this order for stable diffs.

Section Content Formats​

  • csdb uses YAML-compatible metadata.
  • table:<name>:schema uses YAML-compatible metadata.
  • table:<name>:data uses CSV.
  • Machine sections use fixed-width section titles and fixed-width records.