@inferagraph/sql

SQL persistence for @inferagraph/core. One package, five plug-in implementations:

| Implementation | Contract (core) | Backing | Dialects | |---|---|---|---| | SqlDataSource | Datasource | nodes / edges / node_properties / content | PostgreSQL, MySQL, SQLite, MSSQL | | SqlVectorEmbeddingStore | EmbeddingStore | inferagraph_embeddings (pgvector) | PostgreSQL + pgvector | | SqlInferredEdgeStore | InferredEdgeStore | inferagraph_inferred_edges (pgvector) | PostgreSQL + pgvector | | SqlConversationStore | ConversationStore | inferagraph_conversations | PostgreSQL (TTL math via INTERVAL); other dialects via custom config | | SqlCacheProvider | CacheProvider | inferagraph_cache | PostgreSQL/SQLite (ON CONFLICT); other dialects with custom upsert |

Migration from @inferagraph/sql-datasource:

pnpm remove @inferagraph/sql-datasource
pnpm add @inferagraph/sql

The class is now SqlDataSource (capital S in Source) — update imports accordingly.

Installation

pnpm add @inferagraph/sql @inferagraph/core

You also need to install the driver for your chosen dialect:

# PostgreSQL (required for vector stores)
pnpm add pg

# MySQL
pnpm add mysql2

# SQLite
pnpm add better-sqlite3

# MSSQL
pnpm add tedious

The vector-backed stores (SqlVectorEmbeddingStore, SqlInferredEdgeStore) require PostgreSQL with the pgvector extension. Other dialects supported by Knex (MySQL/SQLite/MSSQL) work fine for SqlDataSource, SqlConversationStore, and SqlCacheProvider.

Schema bootstrap

Run once at deploy time to create every table this package needs:

import { provisionSqlSchemas } from '@inferagraph/sql';

await provisionSqlSchemas({
  connectionString: process.env.DATABASE_URL!,
  embeddingDimensions: 3072,
  embeddings: true,
  inferredEdges: true,
  conversations: true,
  cache: true,
});

The function is idempotent (every CREATE uses IF NOT EXISTS). It issues CREATE EXTENSION IF NOT EXISTS vector when any vector-backed table is requested. If pgvector is not installed on the server, the call fails with a clear error — install with CREATE EXTENSION vector; (one line, requires superuser).

Pass tablePrefix: 'myapp_' to namespace the tables; pass embeddingDimensions: 1024 to match a smaller embedding model.

SqlDataSource — graph data

import { sqlDataSource } from '@inferagraph/sql';

const datasource = sqlDataSource({
  dialect: 'postgres',
  connection: {
    host: 'localhost',
    port: 5432,
    user: 'app',
    password: 'secret',
    database: 'graph_db',
  },
  autoMigrate: true, // auto-create tables on connect
});

await datasource.connect();

const view = await datasource.getInitialView();
const node = await datasource.getNode('node-1');
const neighbors = await datasource.getNeighbors('node-1', 2);
const results = await datasource.search('keyword');

await datasource.disconnect();

getNeighbors(nodeId, depth) supports depth > 1 via application-level BFS; SQL has no native graph traversal so each level fans out one query at a time, deduping nodes and edges.

SqlVectorEmbeddingStore — vector storage

import { sqlVectorEmbeddingStore } from '@inferagraph/sql';

const store = sqlVectorEmbeddingStore({
  dialect: 'postgres',
  connection: process.env.DATABASE_URL!,
});

await store.set({
  nodeId: 'gen-2-7-adam',
  vector: [0.123, -0.045, /* ... */],
  meta: {
    model: 'text-embedding-3-large',
    modelVersion: '1',
    contentHash: 'abc123',
    generatedAt: new Date().toISOString(),
  },
});

const hits = await store.searchVector!([0.111, 0.222, /* ... */], { top: 25 });

The composite key is (nodeId, model, modelVersion, contentHash) — model bumps and content edits naturally bypass stale hits without explicit invalidation.

searchVector issues a pgvector cosine query (embedding <=> $1::vector) ordered ASC and limited to top rows.

SqlInferredEdgeStore — inferred edges

import { sqlInferredEdgeStore } from '@inferagraph/sql';

const store = sqlInferredEdgeStore({
  dialect: 'postgres',
  connection: process.env.DATABASE_URL!,
});

await store.set([
  {
    sourceId: 'adam',
    targetId: 'eve',
    type: 'related_to',
    score: 0.92,
    sources: ['embedding', 'llm'],
    reasoning: 'consistently co-occur',
  },
]);

const incident = await store.getAllForNode('adam');
const topMatches = await store.searchInferredEdges([0.1, 0.2 /* ... */], 10);

set is bulk-replace by contract — the table is cleared and re-populated atomically. Duplicate ordered (sourceId, targetId) keys keep the LAST occurrence.

SqlConversationStore — chat memory

import { sqlConversationStore } from '@inferagraph/sql';

const store = sqlConversationStore({
  dialect: 'postgres',
  connection: process.env.DATABASE_URL!,
  ttlSeconds: 60 * 60 * 24, // optional: 24h per turn
});

await store.appendTurn('conv-42', {
  role: 'user',
  content: 'Tell me about Adam',
  timestamp: Date.now(),
});

const turns = await store.getTurns('conv-42', 20); // oldest -> newest

await store.cleanup(); // optional housekeeping: delete expired rows

getTurns filters expired rows lazily (WHERE expires_at IS NULL OR expires_at > NOW()). The cleanup() method exists for periodic housekeeping when you want to reclaim space.

SqlCacheProvider — generic cache

import { sqlCacheProvider } from '@inferagraph/sql';

const cache = sqlCacheProvider({
  dialect: 'postgres',
  connection: process.env.DATABASE_URL!,
  defaultTtlSeconds: 300, // optional default TTL
});

await cache.set('llm:abc123', JSON.stringify(response));
await cache.set('llm:xyz999', JSON.stringify(response), { ttlSeconds: 30 });

const cached = await cache.get('llm:abc123');
await cache.delete('llm:xyz999');
await cache.clear();

Schema: inferagraph_cache (key TEXT PRIMARY KEY, value TEXT, expires_at TIMESTAMPTZ). UPSERT via INSERT … ON CONFLICT (key) DO UPDATE.

Sharing one Knex instance across stores

Pass the same knex instance to every store to share a single connection pool:

import knex from 'knex';
import {
  sqlDataSource,
  SqlVectorEmbeddingStore,
  SqlInferredEdgeStore,
  SqlConversationStore,
  SqlCacheProvider,
} from '@inferagraph/sql';

const db = knex({
  client: 'postgres',
  connection: process.env.DATABASE_URL,
});

const embeddings = new SqlVectorEmbeddingStore({ knex: db });
const inferredEdges = new SqlInferredEdgeStore({ knex: db });
const conversations = new SqlConversationStore({ knex: db, ttlSeconds: 86400 });
const cache = new SqlCacheProvider({ knex: db, defaultTtlSeconds: 300 });

When you pass knex, the store does NOT call db.destroy() on disconnect() — you own the lifetime.

Configuration reference

SqlDataSourceConfig

| Option | Type | Description | |---|---|---| | dialect | 'postgres' \| 'mysql' \| 'sqlite' \| 'mssql' | SQL dialect | | connection | string \| object | Knex connection config or connection string | | tables.nodes | string | Node table name (default: 'nodes') | | tables.edges | string | Edge table name (default: 'edges') | | tables.properties | string | EAV properties table name (default: 'node_properties') | | tables.content | string | Content table name (default: 'content') | | autoMigrate | boolean | Create tables on connect (default: false) |

SqlVectorEmbeddingStoreConfig / SqlInferredEdgeStoreConfig / SqlConversationStoreConfig / SqlCacheProviderConfig

All four store configs accept either:

• knex: Knex — share an existing pool, OR
• dialect + connection — let the store construct knex internally.

Plus tableName? to namespace the table. Per-store extras:

• SqlConversationStoreConfig.ttlSeconds — per-turn TTL (default: none).
• SqlCacheProviderConfig.defaultTtlSeconds — default TTL applied when set opts omit ttlSeconds.

ProvisionSqlSchemasConfig

| Option | Type | Description | |---|---|---| | connectionString / connection / knex | one required | Connection target | | dialect | 'postgres' \| ... | Default 'pg' | | embeddingDimensions | number | Vector column size (default: 3072) | | tablePrefix | string | Prefix for every table (default: 'inferagraph_') | | embeddings / inferredEdges / conversations / cache | boolean | Opt-in per table |

License

MIT