pds#

ATProto Personal Data Server storage for OCaml.

Overview#

A library for reading and writing ATProto PDS (Personal Data Server) storage format. This enables:

• Local PDS-compatible repositories without running a full PDS
• Offline repository manipulation (backup, migration, inspection)
• CAR import/export for interoperability

Storage Layout#

<repo>/
├── pds.db              # SQLite database
│   ├── blocks table    # CID → DAG-CBOR bytes
│   ├── refs table      # name → CID (branches)
│   └── meta table      # did, version, etc.
└── blobs/              # Large binary data
    ├── ba/             # First 2 chars of CID
    │   └── bafyrei...  # Full CID as filename
    └── ...

Installation#

opam install pds

Usage#

(* Create a new repository *)
let repo = Pds.create (Eio.Path.(fs / "my-repo")) ~did:(Atp.Did.of_string_exn "did:web:example.com") in

(* Store records *)
Pds.put repo ~collection:"app.bsky.feed.post" ~rkey:"abc123" record_bytes;

(* Read records *)
let data = Pds.find repo ~collection:"app.bsky.feed.post" ~rkey:"abc123" in

(* List collection *)
let records = Pds.list repo ~collection:"app.bsky.feed.post" in

(* Store blobs *)
let blob_ref = Pds.put_blob repo ~mime_type:"image/png" image_bytes in

(* Export as CAR *)
let car_data = Pds.export_car repo in

(* Import from CAR *)
let count = Pds.import_car repo car_data in

(* Close *)
Pds.close repo

API#

Repository#

• Pds.create path ~did - Create a new repository
• Pds.open_ path - Open an existing repository
• Pds.did t - Get the repository's DID
• Pds.close t - Close the repository

Records#

• Pds.find t ~collection ~rkey - Read a record
• Pds.put t ~collection ~rkey data - Write a record
• Pds.delete t ~collection ~rkey - Delete a record
• Pds.list t ~collection - List records in a collection

Blobs#

• Pds.put_blob t ~mime_type data - Store a blob
• Pds.get_blob t cid - Read a blob

Commits#

• Pds.head t - Get current commit CID
• Pds.checkout t - Get MST at HEAD
• Pds.commit t ~tree ~message ~signing_key - Create a signed commit

Import/Export#

• Pds.import_car t data - Import blocks from CAR
• Pds.export_car t - Export repository as CAR

Related Work#

• ocaml-atp - ATProto primitives (MST, CID, DAG-CBOR, CAR)
• ocaml-sqlite - SQLite key-value store (used internally)
• Bluesky PDS - Reference TypeScript implementation

Licence#

MIT License. See LICENSE.md for details.