Unlimited On-Demand Graph Databases with Cloudflare Durable Objects

I found myself needing to create unlimited, isolated graph databases for an AI agent I’m building. I figured an elegant way using Durable Objects on the Cloudflare Developers Platform. Each graph gets its own instance with dedicated SQLite storage, enabling true multi-tenancy without the complexity of traditional database partitioning.

Traditional graph database deployments require careful infrastructure planning. You need to decide upfront how many database instances to provision, configure connection pooling, implement tenant isolation at the query level, and manage scaling as your user base grows. What if you could skip all of that and let the platform handle it?

In this blog post, I’ll walk through building a simple and extensible graph database system leveraging SQLite on Durable Objects where creating a new database is as simple as making an HTTP request with a new identifier. No provisioning, no configuration, just instant isolation.

Graph database visualisation

The Multi-Tenancy Problem

If you’re building any kind of multi-tenant application today, you’re probably dealing with one of these patterns:

Shared database with tenant IDs: Every query needs WHERE tenant_id = ?
Schema per tenant: Complex migrations and connection management
Traditional database per tenant: Infrastructure overhead and cost

The key problem is architectural complexity. When you store multiple tenants in a shared database, you’re constantly guarding against data leakage. One missing WHERE clause and you’ve exposed customer data. Likewise, when you create separate databases per tenant, you’re managing infrastructure at scale, which usually is resource inefficient.

Graph databases add another layer of complexity. Graph queries naturally traverse relationships, making it even easier to accidentally cross tenant boundaries.

Traditional solutions require:

Careful query design: Every traversal must check tenant ownership
Complex access control: Node and edge-level security policies
Performance trade-offs: Filtering by tenant ID on every hop

What if each tenant could have their own isolated graph database, created automatically on first access?

Durable Objects as Micro-Databases

Cloudflare Durable Objects solve this elegantly. Each Durable Object instance is a globally-unique, strongly-consistent compute environment with built-in SQLite storage. The key insight: treat each Durable Object as a complete database instance.

With Durable Objects, you get:

Automatic isolation: Each instance has its own SQLite database
Deterministic routing: Each graphId always routes to the same instance
Zero provisioning: Instances are created on-demand
Global distribution: Automatically deployed to Cloudflare’s edge network

This enables a powerful pattern: one graph database per identifier.

1
// This is all you need to get an isolated database
2
const doId = env.GraphDatabase.idFromName("user-123-graph");
3
const stub = env.GraphDatabase.get(doId);

The first time you access user-123-graph, Cloudflare creates a new Durable Object instance. The second time, you get the same instance. It’s deterministic, isolated, and automatic.

Project Overview

We’ll be using:

Cloudflare Workers - Serverless HTTP handling and routing
Cloudflare Durable Objects - Stateful instances with SQLite
Hono - Lightweight web framework
TypeScript - Type-safe development

Here’s the basic structure:

1
.
2
├── bindings.ts           # TypeScript bindings
3
├── src
4
│   ├── index.ts         # Worker router and API endpoints
5
│   ├── do.ts            # Durable Object graph database implementation
6
│   └── migrate.ts       # Migration system
7
├── migrations
8
│   ├── index.ts         # Migration registry
9
│   └── v00_add_graph_tables.ts  # Initial schema
10
├── web
11
│   ├── index.html       # Graph visualization UI
12
│   ├── app.js           # Frontend application
13
│   └── style.css        # Styles
14
├── wrangler.json        # Cloudflare configuration
15
└── package.json         # Dependencies

The architecture looks like this:

graph TB
    Client[Client/Browser] -->|HTTP Request| Worker[Cloudflare Worker - Hono Router]

    Worker -->|Extract graphId from URL| Router{URL Router}

    Router -->|idFromName graphId| NS[Durable Object Namespace]

    NS -->|Get or Create Instance| DO[GraphDatabase Durable Object Instance]

    DO -->|Raw SQL Operations| SQL[(SQLite Storage)]

    SQL -->|schema_history| Migrations[Migration System]
    SQL -->|nodes table| Nodes[Nodes: id, type, data, timestamps]
    SQL -->|edges table| Edges[Edges: source, target, relationship]

    DO -->|Graph Operations| Ops[BFS Traversal, Pathfinding, Neighbor Queries]

    Ops -->|Read/Write| SQL

    DO -->|JSON Response| Worker
    Worker -->|HTTP Response| Client

    style Worker fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style DO fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style SQL fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style NS fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C

The complete source code is available on GitHub. I suggest following along with the code for reference.

Setting Up the Worker

Let’s start with the Worker configuration. Create a wrangler.json file:

1
{
2
  "name": "durable-objects-graph-database",
3
  "compatibility_date": "2025-10-27",
4
  "workers_dev": true,
5
  "main": "./src/index.ts",
6
  "assets": {
7
    "directory": "./web",
8
    "binding": "ASSETS"
9
  },
10
  "migrations": [
11
    {
12
      "new_sqlite_classes": ["GraphDatabase"],
13
      "tag": "v1"
14
    }
15
  ],
16
  "durable_objects": {
17
    "bindings": [
18
      {
19
        "name": "GraphDatabase",
20
        "class_name": "GraphDatabase"
21
      }
22
    ]
23
  }
24
}

The new_sqlite_classes migration is crucial. It enables SQLite storage in your Durable Objects. Without this, your Durable Objects will not have a SQLite database attached.

The assets configuration serves a web interface directly from the Worker, enabling us to visualise our graph databases.

Building the Graph Database Durable Object

The GraphDatabase Durable Object implements the graph database. It’s a class extending the DurableObject class. It encapsulates all graph operations and manages its own SQLite database.

Schema Design

Graph databases are different from traditional relational databases. Instead of thinking in individual tables with joins, you think in nodes (entities) and edges (relationships).

Understanding Nodes and Edges

Imagine modeling an organization:

graph LR
    Alice[("Alice - Engineering Manager")]
    Bob[("Bob - Senior Engineer")]
    Project[("Project X - Active")]

    Alice -->|manages| Bob
    Bob -->|works_on| Project

    style Alice fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Bob fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Project fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C

Nodes are the “things”: Alice, Bob, and Project X. Each node has:

An ID (unique identifier)
A type (person, project, document, etc.)
Data (arbitrary JSON properties like name, role, status)

Edges are the connections: “Alice manages Bob” and “Bob works on Project X”. Each edge has:

A source (where the edge starts)
A target (where the edge ends)
A relationship (what type of connection this is)
Optional properties (metadata about the relationship)

The power comes from traversing these relationships. To answer “what projects does Alice’s team work on?”, you traverse: Alice → manages → Bob → works_on → Project X.

The Schema

Here’s how we model this in SQLite:

1
CREATE TABLE IF NOT EXISTS nodes (
2
    id TEXT PRIMARY KEY,            -- Unique identifier (e.g., "alice", "project-x")
3
    type TEXT NOT NULL,             -- Category (e.g., "person", "project")
4
    data TEXT NOT NULL,             -- JSON blob: {"name": "Alice", "role": "Manager"}
5
    created_by TEXT NOT NULL,       -- Who created this node
6
    last_edited_by TEXT NOT NULL,   -- Who last modified it
7
    updated INTEGER NOT NULL,       -- Last update timestamp (ms since epoch)
8
    created INTEGER NOT NULL        -- Creation timestamp (ms since epoch)
9
);
10

11
CREATE TABLE IF NOT EXISTS edges (
12
    source TEXT NOT NULL,           -- Source node ID
13
    target TEXT NOT NULL,           -- Target node ID
14
    relationship TEXT NOT NULL,     -- Relationship type (e.g., "manages", "works_on")
15
    properties TEXT,                -- Optional JSON: {"since": "2024", "hours": 40}
16
    created_by TEXT NOT NULL,
17
    last_edited_by TEXT NOT NULL,
18
    updated INTEGER NOT NULL,
19
    created INTEGER NOT NULL,
20
    UNIQUE(source, target, relationship)  -- Prevents duplicate edges
21
);

Why This Design Works

Flexible Node Storage: The data field stores JSON as text. This means different node types can have completely different properties:

1
// Person node
2
{"name": "Alice", "role": "Engineering Manager", "email": "[email protected]"}
3

4
// Project node
5
{"name": "Project X", "status": "active", "deadline": "2025-12-31"}
6

7
// Document node
8
{"title": "Architecture Doc", "url": "https://...", "embedding": [...]}

You don’t need to alter the schema when adding new node types or properties. Just store different JSON.

Multi-Relationship Support: The UNIQUE(source, target, relationship) constraint ensures the uniqueness of relationships between nodes, and enables multiple relationship types between the same two nodes:

graph LR
    A[("Alice")]
    B[("Bob")]

    A -->|manages| B
    A -->|mentors| B
    A -->|collaborates_with| B

    style A fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style B fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C

Alice can simultaneously manage, mentor, and collaborate with Bob. Each is a separate edge with a different relationship value.

Directional Relationships: Edges have direction. “Alice manages Bob” is different from “Bob manages Alice”. The source and target fields encode this direction:

For bidirectional relationships (like “friends_with”), you create two edges:

graph LR
    A[("Alice")]
    B[("Bob")]

    A -->|friends_with| B
    B -->|friends_with| A

    style A fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style B fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C

Indexes: We add indexes to improve query performance:

1
CREATE INDEX edges_source_idx ON edges(source);  -- Fast outbound queries
2
CREATE INDEX edges_target_idx ON edges(target);  -- Fast inbound queries
3
CREATE INDEX nodes_type_idx ON nodes(type);      -- Filter by node type

When you ask “who does Alice manage?”, the database uses edges_source_idx to quickly find all edges where source = 'alice'. Without this index, it would scan a large number of edge. Query performance would tank for large graphs.

Similarly, “who manages Alice?” uses edges_target_idx to find edges where target = 'alice'.

The nodes_type_idx lets you efficiently query “find all person nodes” or “find all projects” without scanning every node.

Migration System

Durable Object provide a SQLite interface, but it’s up to us to figure out a migration system. The database schema will evolve over time as our application evolves. The migration system is idempotent and version-tracked. Each Durable Object instance maintains its own migration state in a schema_history table.

The migration logic:

Create schema_history table if it doesn’t exist
Compare current schema version with available migrations
Apply any pending migrations in order within a transaction
Record each migration in the history table

1
export function migrate(storage: DurableObjectStorage, migrations: SQLMigration[]) {
2
  createSchemaHistory(storage);
3
  const current = getSchema(storage);
4
  const toApply = migrations.filter((m) => m.version > (current?.version || -1));
5

6
  storage.transactionSync(() => {
7
    for (const migration of toApply) {
8
      storage.sql.exec(migration.sql);
9
      storage.sql.exec(
10
        "INSERT INTO schema_history (version, name) VALUES (?, ?)",
11
        migration.version, migration.name
12
      );
13
    }
14
  });
15
}

The transactionSync wrapper ensures atomicity; either all migrations succeed or none do. This prevents corrupted schema states if a migration fails partway through.

The migrations must run in the constructor of the Durable Object class. When a Durable Object receives a request, if it’s not yet in memory on the Cloudflare network, it is initialised and the migrations run “just-in-time” for this given instance of the Durable Object class.

Durable Object Implementation

Now let’s implement the GraphDatabase class:

1
import { DurableObject } from "cloudflare:workers";
2
import type { Bindings } from "../bindings";
3
import { migrations } from "../migrations";
4
import { migrate } from "./migrate";
5

6
export class GraphDatabase extends DurableObject {
7
  private db: SqlStorage;
8

9
  constructor(ctx: DurableObjectState, env: Bindings) {
10
    super(ctx, env);
11
    this.db = ctx.storage.sql;
12

13
    this.ctx.blockConcurrencyWhile(async () => {
14
      migrate(ctx.storage, migrations);
15
    });
16
  }
17
}

The blockConcurrencyWhile ensures migrations complete before any other requests are processed. Without this, you could have race conditions where a request tries to query a table that doesn’t exist yet.

Node Operations

We need operations to create, read, update, and delete nodes. The key node methods in the GraphDatabase class are:

addNode(): Creates or updates a node with JSON data stored as text
findNode(): Retrieves a single node by its ID
findNodes(): Lists nodes with optional filtering by type, a limit, and an offset
deleteNode(): Removes a node and cascades to delete all connected edges, ensuring the integrity of the graph

1
addNode(node: InsertNode): Node {
2
  const { id, type, data, userId } = node;
3
  const result = this.db.exec(
4
    "INSERT OR REPLACE INTO nodes (...) VALUES (...) RETURNING *",
5
    id, type, JSON.stringify(data), userId, userId, Date.now(), Date.now()
6
  );
7

8
  return toNode(result.toArray()[0]);
9
}
10

11
findNode(id: string): Node | null {
12
  const result = this.db.exec("SELECT * FROM nodes WHERE id = ?", id);
13
  const res = result.toArray();
14
  if (!res.length) {
15
    return null;
16
  }
17

18
  const rows = res as Array<DBNode>;
19
  const row = rows[0];
20
  if (!row) return null;
21

22
  return toNode(row);
23
}
24

25
findNodes(filters?: { type?: string; limit?: number; offset?: number }): Node[] {
26
  let query = "SELECT * FROM nodes";
27
  const params: any[] = [];
28

29
  if (filters?.type) {
30
    query += " WHERE type = ?";
31
    params.push(filters.type);
32
  }
33

34
  if (filters?.limit) {
35
    query += " LIMIT ?";
36
    params.push(filters.limit);
37
  }
38

39
  if (filters?.offset) {
40
    query += " OFFSET ?";
41
    params.push(filters.offset);
42
  }
43

44
  const result = this.db.exec(query, ...params);
45
  const res = result.toArray();
46

47
  return res.map((row) => toNode(row as DBNode));
48
}
49

50
deleteNode(id: string): Node | null {
51
  // First delete all edges connected to this node
52
  this.db.exec("DELETE FROM edges WHERE source = ? OR target = ?", id, id);
53

54
  // Then delete the node
55
  const result = this.db.exec("DELETE FROM nodes WHERE id = ? RETURNING *", id);
56
  const res = result.toArray();
57
  if (!res.length) {
58
    return null;
59
  }
60

61
  const rows = res as Array<DBNode>;
62
  const row = rows[0];
63
  if (!row) return null;
64

65
  return toNode(row);
66
}

Edge Operations

How Edges Work

Consider this scenario: you want to model how team members contribute to projects:

graph LR
    Alice[("Alice - Manager")]
    Bob[("Bob - Engineer")]
    Charlie[("Charlie - Engineer")]
    ProjectX[("Project X")]
    ProjectY[("Project Y")]

    Alice -->|manages| Bob
    Alice -->|manages| Charlie
    Bob -->|works_on: 40 hrs/week| ProjectX
    Charlie -->|works_on: 20 hrs/week| ProjectX
    Charlie -->|works_on: 20 hrs/week| ProjectY

    style Alice fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Bob fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Charlie fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style ProjectX fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style ProjectY fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C

Each edge stores:

1
// Bob works on Project X
2
{
3
  source: "bob",
4
  target: "project-x",
5
  relationship: "works_on",
6
  properties: { hours_per_week: 40, role: "lead" }
7
}
8

9
// Charlie works on Project X
10
{
11
  source: "charlie",
12
  target: "project-x",
13
  relationship: "works_on",
14
  properties: { hours_per_week: 20, role: "contributor" }
15
}

Notice how the same relationship type (works_on) can have different properties. This lets you capture nuance, both Bob and Charlie work on Project X, but with different time commitments and roles.

The Composite Key Pattern

The UNIQUE(source, target, relationship) constraint is fundamental to the design. It means:

Alice can both “manages” and “mentors” Bob (different relationships)
Alice can “manages” both Bob and Charlie (different targets)
Alice “manages” Bob can’t be inserted twice (duplicate prevented)

1
// First call: creates the edge
2
await connectNodes({
3
  source: "bob",
4
  target: "project-x",
5
  relationship: "works_on",
6
  properties: { hours_per_week: 30 }
7
});
8

9
// Second call: updates the same edge (changes hours from 30 to 40)
10
await connectNodes({
11
  source: "bob",
12
  target: "project-x",
13
  relationship: "works_on",
14
  properties: { hours_per_week: 40 }
15
});

Edge Methods

The core edge operations are:

connectNodes() - Creates or updates an edge:

1
const edge = await stub.connectNodes({
2
  source: "alice",
3
  target: "bob",
4
  relationship: "manages",
5
  properties: { since: "2024-01-15", team: "engineering" },
6
  userId: "system"
7
});

disconnectNodes() - Removes a specific edge:

1
// Remove the "manages" relationship (other relationships remain)
2
await stub.disconnectNodes("alice", "bob", "manages");

findEdges() - Query edges by node or relationship:

1
// Find all edges connected to Bob (any direction)
2
const bobEdges = await stub.findEdges({ nodeId: "bob" });
3

4
// Find all "manages" relationships in the graph
5
const managesEdges = await stub.findEdges({ relationship: "manages" });

Edge Properties: When to Use Them

Some relationships are simple facts (“knows”, “contains”, “references”). Others carry context that’s essential to understanding the relationship:

1
// Simple edge - no properties needed
2
{ source: "doc-1", target: "doc-2", relationship: "references" }
3

4
// Rich edge - properties add crucial context
5
{
6
  source: "alice",
7
  target: "project-x",
8
  relationship: "contributed_to",
9
  properties: {
10
    role: "architect",
11
    startDate: "2024-01-01",
12
    endDate: "2024-06-30",
13
    linesOfCode: 15420,
14
    commits: 247
15
  }
16
}

The flexibility to add properties without schema changes lets you evolve your data model. You can start with simple edges and enrich them later as you discover what metadata matters.

Graph Traversal

Graph traversal enables your to explore relationships and answer questions like “how are these two entities connected?” or “what’s reachable from this starting point?”

Directional Queries

The findNeighbors() method finds all nodes directly connected to a given node. Direction matters:

graph TB
    subgraph "Both (all Alice's connections)"
    D2[("David")]
    A3[("Alice")]
    B2[("Bob")]
    C2[("Charlie")]
    D2 -->|manages| A3
    A3 -->|manages| B2
    A3 -->|manages| C2
    style A3 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style D2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style B2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style C2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    end

    subgraph "Outbound (who does Alice manage?)"
    A1[("Alice")]
    B1[("Bob")]
    C1[("Charlie")]
    A1 -->|manages| B1
    A1 -->|manages| C1
    style A1 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style B1 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style C1 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    end

    subgraph "Inbound (who manages Alice?)"
    D[("David - VP Engineering")]
    A2[("Alice")]
    D -->|manages| A2
    style D fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style A2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    end

Directional queries are lets you model asymmetric relationships. “Alice manages Bob” is directional, the reverse isn’t automatically true.

1
findNeighbors(
2
  nodeId: string,
3
  direction: "inbound" | "outbound" | "both" = "both"
4
): string[] {
5
  let query: string;
6
  const params: string[] = [];
7

8
  switch (direction) {
9
    case "inbound":
10
      query = "SELECT DISTINCT source AS neighbor FROM edges WHERE target = ?";
11
      params.push(nodeId);
12
      break;
13
    case "outbound":
14
      query = "SELECT DISTINCT target AS neighbor FROM edges WHERE source = ?";
15
      params.push(nodeId);
16
      break;
17
    case "both":
18
    default:
19
      query = `
20
        SELECT DISTINCT target AS neighbor FROM edges WHERE source = ?
21
        UNION
22
        SELECT DISTINCT source AS neighbor FROM edges WHERE target = ?
23
      `;
24
      params.push(nodeId, nodeId);
25
      break;
26
  }
27

28
  const result = this.db.exec(query, ...params);
29
  const res = result.toArray();
30
  return res.map((row) => (row as { neighbor: string }).neighbor);
31
}

Breadth-First Search (BFS)

The traverse() method implements breadth-first search to explore the graph layer by layer. BFS guarantees finding the shortest path between two nodes.

Here’s how BFS explores a graph starting from Alice:

graph TB
    subgraph "Depth 2 (Second hop)"
    A2[("Alice")]
    B2[("Bob")]
    C2[("Charlie")]
    PX[("Project X")]
    PY[("Project Y")]
    A2 -.->|manages| B2
    A2 -.->|manages| C2
    B2 -.->|works_on| PX
    C2 -.->|works_on| PY
    style A2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style B2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style C2 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style PX fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style PY fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    end

    subgraph "Depth 1 (First hop)"
    A1[("Alice")]
    B1[("Bob")]
    C1[("Charlie")]
    A1 -.->|manages| B1
    A1 -.->|manages| C1
    style A1 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style B1 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style C1 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    end

    subgraph "Depth 0 (Start)"
    A0[("Alice")]
    style A0 fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    end

BFS visits all nodes at depth 1 before moving to depth 2. This guarantees the first path found to any node is the shortest.

Pathfinding Example: “How is Alice connected to Project X?”

Depth 0: Start at Alice
Depth 1: Explore Bob and Charlie (Alice’s direct reports)
Depth 2: Find Project X through Bob
Result: Alice → manages → Bob → works_on → Project X (2 hops)

Even if there’s a longer path (Alice → manages → Charlie → collaborates_with → Bob → works_on → Project X), BFS finds the shorter one first.

The traversal operates in two modes:

Pathfinding Mode (when endNodeId is specified): Find the shortest path from start to end node
Reachability Mode (when endNodeId is omitted): Find all nodes reachable within maxDepth hops

1
traverse(startNodeId: string, options = {}) {
2
  const { endNodeId, maxDepth = 50, direction = "both" } = options;
3
  const visited = new Set<string>();
4
  const queue = [{ id: startNodeId, path: [startNodeId], depth: 0 }];
5

6
  while (queue.length > 0) {
7
    const current = queue.shift()!;
8
    if (current.depth > maxDepth) continue;
9

10
    // Pathfinding: stop when target found
11
    if (endNodeId && current.id === endNodeId) {
12
      return { found: true, path: current.path, depth: current.depth };
13
    }
14

15
    if (visited.has(current.id)) continue;
16
    visited.add(current.id);
17

18
    // Explore neighbors
19
    const neighbors = this.findNeighbors(current.id, direction);
20
    for (const neighborId of neighbors) {
21
      if (!visited.has(neighborId)) {
22
        queue.push({
23
          id: neighborId,
24
          path: [...current.path, neighborId],
25
          depth: current.depth + 1,
26
        });
27
      }
28
    }
29
  }
30

31
  // Reachability: return all visited nodes
32
  return { found: true, reachableNodes: Array.from(visited), count: visited.size };
33
}

In a highly connected graph (think social networks where most people are connected within 6 degrees), an unbounded traversal could visit the entire graph. By limiting depth through maxDepth, you can explore local neighborhoods without scanning millions of nodes.

The algorithm maintains a visited set to avoid cycles. Without this, you could loop indefinitely in a graph with circular references (A → B → C → A).

Building the HTTP API

Now let’s expose these operations through an HTTP API. We’ll use Hono for routing:

1
import { Hono } from "hono";
2
import { cors } from "hono/cors";
3
import type { Bindings } from "../bindings";
4

5
const app = new Hono<{ Bindings: Bindings }>();
6

7
app.use("/*", cors());
8

9
export default {
10
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext): Promise<Response> {
11
    const url = new URL(request.url);
12

13
    if (url.pathname.startsWith("/api/")) {
14
      const apiRequest = new Request(request.url.replace("/api", ""), request);
15
      return app.fetch(apiRequest, env, ctx);
16
    }
17

18
    return env.ASSETS.fetch(request);
19
  },
20
};
21

22
export { GraphDatabase } from "./do";
23

24
function getGraphDatabaseStub(env: Bindings, graphId: string) {
25
  const doId = env.GraphDatabase.idFromName(graphId);
26
  return env.GraphDatabase.get(doId);
27
}

The routing is clean: /api/* goes to our Hono app, everything else is served from static assets for a simple web interface to visualise the graph.

The getGraphDatabaseStub function uses idFromName(graphId) to get a unique ID from the graphId, and creates a stub which can be used to invoke methods on the associated Durable Object. This is the foundation of the multi-tenancy model:

Same input ("user-123-graph") → Same Durable Object ID → Same instance
Different input ("user-456-graph") → Different ID → Different instance
No coordination needed; the idFromName guarantees deterministic routing

You don’t need a lookup table mapping tenant IDs to Durable Object IDs.

API Endpoints

Every endpoint extracts graphId from the URL path, making multi-tenancy explicit in the URL structure:

1
/api/alice-graph/nodes      # Alice's graph
2
/api/bob-graph/nodes        # Bob's graph
3
/api/project-x/nodes        # Project X's graph

Node Operations:

POST /:graphId/nodes - Create or update a node
GET /:graphId/nodes/:nodeId - Retrieve a specific node
GET /:graphId/nodes?type=&limit=&offset= - List nodes with filtering
DELETE /:graphId/nodes/:nodeId - Delete node and connected edges

Edge Operations:

POST /:graphId/edges - Create an edge between nodes
GET /:graphId/edges?nodeId=&relationship= - Find edges by node or relationship
DELETE /:graphId/edges/:source/:relationship/:target - Remove a specific edge

Graph Operations:

GET /:graphId/nodes/:nodeId/neighbors?direction= - Find adjacent nodes
POST /:graphId/traverse - Execute BFS pathfinding or reachability analysis
GET /:graphId/stats - Get graph metrics (node count, edge count, type distributions)

Each endpoint follows the same pattern: extract the graphId, get the Durable Object stub, call the method, return JSON.

1
app.post("/:graphId/nodes", async (c) => {
2
  const graphId = c.req.param("graphId");
3
  const body = await c.req.json<InsertNode>();
4
  const stub = getGraphDatabaseStub(c.env, graphId);
5
  const node = await stub.addNode(body);
6
  return c.json({ node });
7
});

No shared tables, no tenant ID columns in queries. Different graphs queries are routed to different Durable Object instances.

Interactive Graph Visualization

I also vibe-coded a simple UI to visualise the state of the graph, hosted on the same Worker as the HTTP API.

Testing It Out

Let’s deploy and test our graph database using Wrangler:

1
npm run deploy

Wrangler will build your TypeScript code, upload it to Cloudflare, and output your Worker URL:

1
https://durable-objects-graph-database.your-account.workers.dev

Creating a Knowledge Graph

Let’s build a simple organizational graph with people and projects:

1
# Create person nodes (Alice, Bob)
2
curl -X POST https://your-worker.workers.dev/api/my-org/nodes \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "id": "alice",
6
    "type": "person",
7
    "data": {"name": "Alice", "role": "Engineering Manager"},
8
    "userId": "system"
9
  }'
10

11
curl -X POST https://your-worker.workers.dev/api/my-org/nodes \
12
  -H "Content-Type: application/json" \
13
  -d '{
14
    "id": "bob",
15
    "type": "person",
16
    "data": {"name": "Bob", "role": "Senior Engineer"},
17
    "userId": "system"
18
  }'
19

20
# Create a project node
21
curl -X POST https://your-worker.workers.dev/api/my-org/nodes \
22
  -H "Content-Type: application/json" \
23
  -d '{
24
    "id": "project-x",
25
    "type": "project",
26
    "data": {"name": "Project X", "status": "active"},
27
    "userId": "system"
28
  }'
29

30
# Add relationships: Alice manages Bob, Bob works on Project X
31
curl -X POST https://your-worker.workers.dev/api/my-org/edges \
32
  -H "Content-Type: application/json" \
33
  -d '{
34
    "source": "alice",
35
    "target": "bob",
36
    "relationship": "manages",
37
    "userId": "system"
38
  }'
39

40
curl -X POST https://your-worker.workers.dev/api/my-org/edges \
41
  -H "Content-Type: application/json" \
42
  -d '{
43
    "source": "bob",
44
    "target": "project-x",
45
    "relationship": "works_on",
46
    "properties": {"hours_per_week": 40},
47
    "userId": "system"
48
  }'

Querying the Graph

Now let’s explore the graph:

1
# Find everyone Alice manages
2
curl https://your-worker.workers.dev/api/my-org/nodes/alice/neighbors?direction=outbound
3

4
# Response:
5
# {
6
#   "neighbors": ["bob"],
7
#   "count": 1
8
# }
9

10
# Find who's working on Project X
11
curl https://your-worker.workers.dev/api/my-org/nodes/project-x/neighbors?direction=inbound
12

13
# Response:
14
# {
15
#   "neighbors": ["bob"],
16
#   "count": 1
17
# }
18

19
# Find the path from Alice to Project X
20
curl -X POST https://your-worker.workers.dev/api/my-org/traverse \
21
  -H "Content-Type: application/json" \
22
  -d '{
23
    "startNodeId": "alice",
24
    "endNodeId": "project-x",
25
    "maxDepth": 5
26
  }'
27

28
# Response:
29
# {
30
#   "found": true,
31
#   "path": ["alice", "bob", "project-x"],
32
#   "depth": 2
33
# }

The traversal found a path: Alice → Bob → Project X. This shows the connection between a manager and a project through the people she manages.

Multi-Tenancy in Action

Creating multiple graphs is as simple as making HTTP calls:

1
# Create a node in Alice's personal graph
2
curl -X POST https://your-worker.workers.dev/api/alice-personal/nodes \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "id": "note-1",
6
    "type": "note",
7
    "data": {"content": "Remember to review PRs"},
8
    "userId": "alice"
9
  }'
10

11
# Create a node in the company graph
12
curl -X POST https://your-worker.workers.dev/api/company-wide/nodes \
13
  -H "Content-Type: application/json" \
14
  -d '{
15
    "id": "policy-1",
16
    "type": "policy",
17
    "data": {"title": "Remote Work Policy"},
18
    "userId": "hr"
19
  }'

These are completely isolated. A query on “alice-personal” will never see “company-wide” data. Each has its own Durable Object instance with its own SQLite database.

Use Cases

I’m particularly interested in AI agent uses cases.

AI Agent Memory

AI agents need persistent memory to build context over time and understand complex relationships. Traditional approaches use vector databases for semantic search, but graph databases excel at representing how concepts, entities, and conversations interconnect.

The Problem with Context-Only Memory

When an AI agent remembers only through vector similarity, it loses the structure of relationships. Consider this scenario:

An AI assistant named Alice helps a user with their work. Over multiple conversations, the user mentions:

They’re working on “Project X” (a web app)
They’re collaborating with “Bob” (the designer)
“Project X” has a deadline of March 1st
Bob is on vacation until February 20th

A vector database might retrieve “Bob” when the user asks about the deadline, but it can’t easily answer “Who on my team is available to help before the deadline?” That requires understanding the relationships: Project X → has_deadline → March 1st, Project X → involves → Bob, Bob → unavailable_until → February 20th.

Graph-Based Agent Memory

With a graph database, each agent builds a knowledge graph that captures not just facts, but how they relate:

graph LR
    User[("User")]
    ProjX[("Project X - Web Redesign")]
    Bob[("Bob - Designer")]
    Deadline[("March 1, 2025")]
    Vacation[("Feb 20, 2025")]

    User -->|working_on| ProjX
    User -->|collaborates_with| Bob
    ProjX -->|involves| Bob
    ProjX -->|deadline| Deadline
    Bob -->|unavailable_until| Vacation

    style User fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style ProjX fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Bob fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Deadline fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C
    style Vacation fill:#E8E8E8,stroke:#AEAEAE,color:#1C1C1C

Here’s how the agent builds this knowledge over time:

1
// Conversation 1: User mentions they're working on a project
2
await fetch('/api/agent-alice/nodes', {
3
  method: 'POST',
4
  body: JSON.stringify({
5
    id: 'project-x',
6
    type: 'project',
7
    data: { name: 'Web Redesign', status: 'in_progress' },
8
    userId: 'agent-alice'
9
  })
10
});
11

12
await fetch('/api/agent-alice/edges', {
13
  method: 'POST',
14
  body: JSON.stringify({
15
    source: 'user',
16
    target: 'project-x',
17
    relationship: 'working_on',
18
    userId: 'agent-alice'
19
  })
20
});
21

22
// Conversation 2: User mentions Bob is helping with design
23
await fetch('/api/agent-alice/nodes', {
24
  method: 'POST',
25
  body: JSON.stringify({
26
    id: 'bob',
27
    type: 'person',
28
    data: { name: 'Bob', role: 'Designer' },
29
    userId: 'agent-alice'
30
  })
31
});
32

33
await fetch('/api/agent-alice/edges', {
34
  method: 'POST',
35
  body: JSON.stringify({
36
    source: 'project-x',
37
    target: 'bob',
38
    relationship: 'involves',
39
    userId: 'agent-alice'
40
  })
41
});
42

43
// Conversation 3: User mentions Bob's vacation
44
await fetch('/api/agent-alice/edges', {
45
  method: 'POST',
46
  body: JSON.stringify({
47
    source: 'bob',
48
    target: 'unavailable-period',
49
    relationship: 'unavailable_until',
50
    properties: { date: '2025-02-20' },
51
    userId: 'agent-alice'
52
  })
53
});

Now when the user asks “Is my team available to help me finish before the deadline?”, the agent can traverse the graph:

1
// Start from the user, explore their projects and collaborators
2
const context = await fetch('/api/agent-alice/traverse', {
3
  method: 'POST',
4
  body: JSON.stringify({
5
    startNodeId: 'user',
6
    maxDepth: 3,  // Explore up to 3 hops away
7
    direction: 'both'
8
  })
9
});
10

11
// Returns: User → Project X → Bob → Unavailable Until Feb 20
12
// Agent can reason: "Bob won't be available until Feb 20, but your deadline is March 1,
13
// so you'll have 9 days to work together"

Why This Works

Each agent gets its own graph (/api/agent-alice/, /api/agent-bob/). As the agent has more conversations, the graph grows organically:

Conversations link to Topics they discuss
Topics link to Projects, People, Deadlines
Projects link to Tasks, Documents, Decisions
People link to Skills, Availability, Preferences

The graph becomes a structure memory layer that captures not just what the agent knows, but how concepts interconnect. When recalling context, traversal provides the most relevant connected information, not just similar words, but structurally related concepts.

Graph-RAG Systems

Retrieval-Augmented Generation (RAG) enhances LLMs by providing relevant context from external knowledge bases. Graph-based RAG goes beyond simple vector similarity by modeling relationships between documents, entities, and concepts. Store document chunks and their relationships for more intelligent retrieval.

Limitations and Considerations

While this pattern is powerful, there are important limitations to understand:

Scale per Graph: Each Durable Object instance is limited to 10 GB, as such is best suited for graphs with thousands to tens of thousands of nodes. For larger graphs, consider sharding.
Cross-Graph Queries: You can’t easily query across multiple graphs. Each Durable Object is isolated. If you need to aggregate data from multiple tenants, you’ll need to query each graph individually.
Cold Start Latency: The first request to a new Durable Object has some initialization overhead. For frequently accessed graphs this isn’t an issue, but rarely-used graphs might experience slightly higher latency on first access.
Global Consistency: Durable Objects provide strong consistency within a single instance but don’t offer distributed transactions across instances. If you need atomicity across multiple graphs, you’ll need to implement your own coordination.
Backup and Export: There’s no built-in backup system. For production use, you’ll want to implement periodic exports of graph data to durable storage like Cloudflare R2.

What’s Next

This foundation enables many extensions:

Full-Text Search: Add SQLite FTS5 virtual tables for text search within node and edge properties
Complex nested queries: Add the ability to run more complex queries on the JSON data of nodes and edges using SQLite json_tree functions
Graph Algorithms: Implement PageRank, community detection, or centrality metrics for graph analysis
Graph Embeddings: Store vector embeddings on nodes using Cloudflare Vectorize for hybrid graph + semantic similarity search
Batch Operations: Add endpoints for bulk node/edge creation and updates to improve performance for large imports

The complete source code with a visualization UI is available on GitHub. Fork it and build something interesting.

Conclusion

Durable Objects flip the traditional database model on its head. Instead of managing infrastructure and partitioning data, you create instances on demand. Each instance is a complete, isolated database with its own storage and compute.

With SQLite storage, migrations, and proper schema design, each instance becomes a fully-featured database that happens to run at the edge.

This pattern works for graphs, but it generalizes to any domain where you need isolated per-tenant data stores. Document databases, time-series data, etc; the architecture is the same.