Using DocumentForge with AI agents

DocumentForge is a good fit for AI coding agents (Claude and friends): it’s a single dependency-free package, embeds in-process, and speaks familiar SQL — so an agent can add a real database to a .NET project without standing up infrastructure.

This page is a compact, copy-paste-friendly reference. For a machine-readable index of the whole site, see /llms.txt.

Install

Embedded (NuGet) is the usual choice inside an app; the dfdb binary is for a standalone server or one-off CLI work.


# Embedded in a .NET app
dotnet add package DocumentForge
 
# Or the standalone server / CLI
dfdb serve --port 5000 --data-dir ./data

Minimal embedded usage


using DocumentForge.Engine;
 
using var db = DocumentForgeDb.OpenOrCreate("app.dfdb");
 
// Insert raw JSON
db.Insert("orders", """{ "pnr": "ABC123", "total": 420.50 }""");
 
// Index the fields you query
db.CreateIndex("orders", "pnr", "idx_pnr", unique: true);
 
// Query with SQL
var result = db.Execute("SELECT * FROM orders WHERE pnr = 'ABC123'");
foreach (var doc in result.Documents)
    Console.WriteLine(doc);

Typed LINQ


public sealed class Order
{
    public Guid Id { get; set; }
    public string Pnr { get; set; } = "";
}
 
var order = db.Collection<Order>("orders")
              .Where(o => o.Pnr == "ABC123")
              .FirstOrDefault();

Operations cheat-sheet

Goal	Call
Open / create a database	`DocumentForgeDb.OpenOrCreate(path)`
Insert one document	`db.Insert(collection, json)`
Insert many (fast)	`db.BulkInsert(collection, docs)`
Create an index	`db.CreateIndex(collection, path, name, unique: bool)`
Run SQL	`db.Execute(sql)`
Typed query	`db.Collection<T>(name).Where(...)`
Query over HTTP	`POST /query {"sql": "..."}`

Gotchas worth knowing

Typed LINQ uses camelCase JSON. Typed Insert and Where agree on field names, and Where(x => x.Id == someGuid) matches correctly.
Indexes are persistent. They survive restarts (no rebuild on startup) and self-heal if the catalog is ever damaged.
The on-disk format is stable. Upgrading the engine over an existing .dfdb file is a no-op migration — point the new build at the old file. See Backup & restore.
One binary does everything — dfdb serve | repl | query | seed | router | cluster | health | rebalance. See the CLI reference.

Where to look next

Quickstart — embedded and server in five minutes
.NET SDK · SQL · REST API
Concepts — the model behind the engine