BogDB.Extensions.Postgres 1.0.0

BogDB

BogDB is the embeddable graph database for .NET and AI-native applications: a permissive C# (.NET 9) core, MCP-first agent integration, and enterprise security available when teams need it. Schema, queries, and bulk loading are accessible from process, and the same engine is reachable over the Model Context Protocol so agents can query, introspect schema, and coordinate handoffs against a live graph.

Current status: comprehensive xUnit coverage across 170+ test files in BogDb.Tests (parser, planner, optimizer, processor, storage, persistence, end-to-end) plus dedicated suites for each bundled extension and the MCP servers.

Quick Start

using BogDb.Core.Main;

// In-memory graph — no files needed
using var db   = BogDatabase.CreateInMemory();
using var conn = new BogConnection(db);

conn.Query("CREATE NODE TABLE Person (id INT64, name STRING, age INT64, PRIMARY KEY(id))");
conn.Query("CREATE REL TABLE KNOWS (FROM Person TO Person, since INT64)");

conn.BeginWriteTransaction();
conn.Query("CREATE (p:Person {id: 1, name: 'Alice', age: 30})");
conn.Query("CREATE (p:Person {id: 2, name: 'Bob',   age: 25})");
conn.Query("CREATE (:Person {id:1})-[:KNOWS {since: 2020}]->(:Person {id:2})");
conn.Commit();

// Basic pattern match
var r = conn.Query("MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name, a.age");
while (r.HasNext())
{
    var row = r.GetNext();
    Console.WriteLine($"{row.GetString(0)} knows {row.GetString(1)} (age {row.GetLong(2)})");
}

// Open a persistent database from disk instead
using var disk = BogDatabase.Open("graph.bog");

A fluent pipeline is also available for composing queries from C#:

using BogDb.Core.Main;

var rows = conn.BeginPipeline()
    .Match("(p:Person)")
    .Where("p.age > 25")
    .Return("p.name", "p.age")
    .OrderBy("p.age DESC")
    .Limit(10)
    .Execute();

Highlighted Features

Aggregation + GROUP BY + HAVING

// Implicit GROUP BY via WITH clause — no GROUP BY keyword needed
conn.Query(@"
    MATCH (p:Person)
    WITH p.dept AS dept, count(p) AS cnt
    WHERE cnt > 1
    RETURN dept, cnt
    ORDER BY cnt DESC");

// Explicit ORDER BY on aggregate
conn.Query("MATCH (p:Person) RETURN p.country, count(p) AS total ORDER BY total DESC LIMIT 5");

Top-K Optimizer (automatic ORDER BY + LIMIT fusion)

Queries of the form ORDER BY … LIMIT N are automatically fused into a single O(n·log K) max-heap pass by TopKOptimizerRule — no full sort required:

// This query fuses internally into PhysicalTopK (heap, not sort)
var top3 = conn.Query(
    "MATCH (p:Person) RETURN p.name, p.score ORDER BY p.score DESC LIMIT 3");

Recursive Path Traversal

// Variable-length path (1 to 3 hops)
var paths = conn.Query(@"
    MATCH (a:Person)-[r*1..3]->(b:Person)
    WHERE a.name = 'Alice'
    RETURN a.name, length(r), nodes(r), rels(r)");

// nodes(r) returns the list of intermediate node IDs along each path
// rels(r)  returns the list of edge objects traversed

LogicalRecursiveExtend cooperates with LimitPushDownRule so LIMIT counts are propagated into the BFS frontier as an early-stop bound.

Scalar Functions — Broad Coverage

24+ function categories ship in BogDb.Core — math, string, list, date, interval, timestamp, struct, union, map, array, blob, UUID, internal id, casting, arithmetic, pattern, path, and more:

// Math
conn.Query("RETURN factorial(6), gcd(12, 18), lcm(4, 6)");

// Path / schema functions
conn.Query("MATCH (n:Person) RETURN id(n), label(n)");
conn.Query("MATCH (a)-[r]->(b) RETURN start_node(r), end_node(r), type(r)");

// Timestamp / epoch
conn.Query("RETURN to_epoch_ms('2024-01-01 00:00:00')");
conn.Query("RETURN timestamp_year('2026-03-20 12:00:00')");

Window Functions (OVER / PARTITION BY / ORDER BY)

// ROW_NUMBER with global ordering
var r = conn.Query(@"
    MATCH (e:Employee)
    RETURN e.dept, e.name, e.salary,
           ROW_NUMBER() OVER (PARTITION BY e.dept ORDER BY e.salary DESC) AS rn
    ORDER BY e.dept, rn");

// Ranking with ties
conn.Query("MATCH (e:Employee) RETURN e.name, RANK() OVER (ORDER BY e.salary DESC) AS rnk");

// Sliding window aggregates
conn.Query(@"
    MATCH (e:Employee)
    RETURN e.dept, e.name,
           AVG(e.salary) OVER (PARTITION BY e.dept) AS dept_avg,
           SUM(e.salary) OVER (PARTITION BY e.dept) AS dept_total");

Window evaluation is handled by WindowFunctionService and WindowEvaluator, with full frame clause support (ROWS/RANGE BETWEEN …) and the standard ranking, navigation, and aggregate-over variants.

Graph Data Science (GDS)

Run graph algorithms via the CALL algo() YIELD * syntax, or invoke them directly from C#. Algorithms live in BogDb.Core/GraphDataScience/:

// PageRank — iterative rank propagation
var r = conn.Query("CALL pagerank() YIELD *");
while (r.HasNext())
{
    var row = r.GetNext();
    Console.WriteLine($"node {row.GetString(0)} → rank {row.GetDouble(1):F6}");
}

// Weakly Connected Components
conn.Query("CALL wcc() YIELD *");  // columns: node, component_id

// Single-Source Shortest Paths
conn.Query("CALL sssp('0') YIELD *");  // columns: node, distance

Sequences

conn.Query("RETURN nextval('order_seq')");  // → 1
conn.Query("RETURN nextval('order_seq')");  // → 2
conn.Query("RETURN currval('order_seq')");  // → 2

Bulk Load (COPY FROM)

// CSV → node table (schema-typed: INT64/INT32/STRING/DOUBLE/FLOAT/BOOL)
conn.Query("COPY Person FROM 'people.csv'");

// CSV → relationship table
conn.Query("COPY KNOWS FROM 'friendships.csv'");

Bulk load is driven by LogicalCopyFrom → PhysicalCopyFrom with full transactional integration.

Extensions

Custom data-source extensions implement ITableFunction and are registered at runtime through IExtension / IStorageExtension. Bundled extensions:

// Implement
public class MyScanFn : ITableFunction
{
    public string Name => "scan_mydb";
    public IEnumerable<Dictionary<string, object?>> Invoke(IReadOnlyList<object?> args)
    {
        foreach (var record in OpenMySource((string)args[0]!))
            yield return record;
    }
}

// Register and query
new MyExtension().Load(db);
conn.Query("CALL scan_mydb('source.bin') RETURN *");

MCP-First Agent Integration

BogDB ships three first-class MCP servers so agents can talk to a live graph without bespoke glue:

• BogDb.Mcp.Server — read-only query surface (bogdb_query), schema introspection (bogdb_schema, bogdb_tables, bogdb_table_info), and handoff resource coordination. ReadOnlyQueryGuard enforces read-only semantics at the boundary.
• BogDb.Acop.Mcp.Server — the ACOP (Agentic Code Orchestration Protocol) layer for multi-agent handoff coordination, acceptance verification, and durable ingest receipts. See docs/acop/ for the v1.0 protocol, schemas, and fixtures.
• BogDb.Mcp.Codegen.Server — code generation tools backed by the graph.

The handoff index contract carries protocol_version, artifact_id, handoff_kind, target_agent_uid, blocker_codes, and actionability_score — designed so orchestrators can filter, batch, and prioritize agent work against a graph-backed source of truth.

Architecture

Query string
  → ANTLR4 parse     (BogDb.Core/Parser)          CypherLexer, CypherParser, Transformer
  → Bind             (BogDb.Core/Binder)          BoundStatement, BoundRegularQuery, …
  → Plan             (BogDb.Core/Planner)         LogicalPlan / LogicalOperator tree
  → Optimize         (BogDb.Core/Optimizer)       12 rules incl. TopK, FilterPushDown, LimitPushDown
  → Map              (BogDb.Core/Processor/PlanMapper)
  → Execute          (BogDb.Core/Processor/Operator/*)
  → QueryResult

Optimizer rules

Physical pipeline operators

PhysicalOperatorType enumerates 77 operator kinds. Frequently-used ones:

Samples

End-to-end sample apps live alongside the engine and double as integration coverage:

Repository Layout

What Makes BogDB Different

Known Gaps

1. Live SDK wiring for some external connectors: Postgres, DuckDB, and SQLite extensions are present; some live SDK integrations are still being hardened against production workloads.
2. C API: native-style c_api parity is intentionally out of scope; the supported public surface is the C# API and the MCP servers.
3. Feature parity matrix: ACOP documentation under docs/acop/ is the canonical contract reference; a unified feature-matrix document is not yet published at the repo root.