CSDB

CSDB

A Comma Separated Database (CSDB) is a human-readable, text-based database format that can be used both as a portable exchange format and as a lightweight AI legible backend.

Documentation
File One text document
Data Multiple relational tables
Speed Optional machine indexes
This project is under active development and may have drastic changes

Plain text formatted database.

CSDB keeps metadata, table schemas, and CSV data together in one UTF-8 file. Humans can edit and review it in a diff, while tools can validate structure, types, keys, relationships, and machine indexes.

first, define database metadata 
--- csdb
format: CSDB
version: 1
name: payroll
tables:
  - workers
  - sessions
then, define a schema in YAML 
--- table:sessions:schema
name: sessions
columns:
  id: text
  worker_id: text
  start_time: timestamp
required:
  - id
  - worker_id
primary_key:
  columns: [id]
finally, store records in csv 
--- table:sessions:data
id,worker_id,start_time
s_001,w_001,2026-01-01T09:00:00Z
s_002,w_001,2026-01-02T09:00:00Z

It's that simple...

Designed for native codebases across programming languages.

Install CSDB in TypeScript projects, open files directly, and use table methods or SQL without a language bridge. A native Python library is planned.

TypeScript Library

GitHub
Install npm install @csvdatabase/csdb
TypeScript method 
import { openCSDB } from "@csvdatabase/csdb";

const db = await openCSDB("payroll.csdb");
const sessions = db.table("sessions")
  .where({ worker_id: "w_001" })
  .all();
SQL method 
const sessions = db.sql(
  "SELECT * FROM sessions WHERE worker_id = ?",
  ["w_001"]
);

Python Library (Planned)

GitHub
Release status

The native Python implementation has not been built or published yet. Track its progress on GitHub.

Created to be simplistic to use.

Git-friendly

Text-first storage keeps schema and data changes visible in ordinary code review.

Relational

Tables can define primary keys, unique constraints, indexes, and foreign keys.

Portable

The specification defines stable sections, type metadata, validation rules, and CSV serialization.

Human editable

People can read and modify CSDB files with normal text editors and source-control tools.

AI legible

Models can read the schema, relationships, comments, and records plainly without binary decoding.

Practically fast

Optional machine indexes maximize practical lookup speed while preserving the plain-text source of truth.

Try it yourself and contribute.

Download a small CSDB file, inspect it in a text editor, and help shape the format and libraries as they grow.

Download sample database Donate