Getting Started

Install

TypeScript

npm install @csvdatabase/csdb

Create A Database In Memory

TypeScript

import { CSDBDatabase } from "@csvdatabase/csdb";

const db = CSDBDatabase.parse(`--- csdb
format: CSDB
version: 1
name: demo
tables:
  - notes

--- table:notes:schema
name: notes
columns:
  id: text
  body: text
required:
  - id
primary_key:
  columns: [id]

--- table:notes:data
id,body
n_001,hello
`);

Insert And Query Rows

TypeScript

db.table("notes").insert({ id: "n_002", body: "from the fluent API" });
db.table("notes").insert({ id: "n_003", body: null });

const notes = db.table("notes")
  .where("body", "!=", null)
  .orderBy("id")
  .all();

SQL

INSERT INTO notes (id, body)
VALUES ('n_002', 'from SQL');

INSERT INTO notes (id, body)
VALUES ('n_003', NULL);

SELECT *
FROM notes
WHERE body IS NOT NULL
ORDER BY id ASC;

JSON

Send each object below as a separate POST /v1/commands request:

{
  "database": "demo",
  "command": {
    "kind": "insert",
    "table": "notes",
    "rows": [{ "id": "n_002", "body": "from JSON" }]
  }
}

{
  "database": "demo",
  "command": {
    "kind": "insert",
    "table": "notes",
    "rows": [{ "id": "n_003", "body": null }]
  }
}

{
  "database": "demo",
  "command": {
    "kind": "select",
    "table": "notes",
    "columns": "*",
    "joins": [],
    "where": {
      "type": "is-null",
      "expr": { "type": "identifier", "name": "body" },
      "not": true
    },
    "orderBy": [{ "column": "id", "direction": "asc" }],
    "output": "objects"
  }
}

Optional non-primary-key columns accept null. In CSV, unquoted empty fields represent null, while quoted empty strings remain empty strings.

Save A File

TypeScript

import { saveCSDB } from "@csvdatabase/csdb";

await saveCSDB(db, "demo.csdb", { machineIndexes: "omit" });

The JSON server does not accept save paths. It resolves database inside its configured data directory and automatically persists successful mutations.

What To Read Next

• Overview explains the document model.
• Database API shows table creation, validation, and serialization.
• TableQuery API covers the fluent table API.
• CSDB Server defines the server command and response contract.