@utaba/deep-memory-storage-sqlserver

SQL Server storage provider for @utaba/deep-memory.

Installation

pnpm add @utaba/deep-memory @utaba/deep-memory-storage-sqlserver

Usage

import { DeepMemory } from '@utaba/deep-memory';
import { SqlServerStorageProvider } from '@utaba/deep-memory-storage-sqlserver';

const provider = new SqlServerStorageProvider({
  connection: {
    server: 'localhost',
    port: 1434,
    database: 'deep-memory',
    user: 'sa',
    password: 'YourPassword',
    options: { trustServerCertificate: true },
  },
  schema: 'dbo',       // optional, default 'dbo'
});

const dm = new DeepMemory({ storage: provider });

// Call once at startup / deployment to create or migrate tables
await dm.ensureSchema();

You can also pass a connection string:

const provider = new SqlServerStorageProvider({
  connection: {
    connectionString: 'Server=localhost,1434;Database=deep-memory;User Id=sa;Password=YourPassword;TrustServerCertificate=true',
  },
});

Or an existing mssql.ConnectionPool:

import sql from 'mssql';

const pool = new sql.ConnectionPool({ /* your config */ });
await pool.connect();

const provider = new SqlServerStorageProvider({ connection: pool });

Database Schema

Automatic creation

Call ensureSchema() once at startup or deployment to create tables if they don't exist. This is not called automatically — the consuming application decides when to run it.

Manual creation

If you manage your own migrations, export the DDL and run it yourself.

From code:

import { getSchemaSQL } from '@utaba/deep-memory-storage-sqlserver';

// Default schema (dbo)
const ddl = getSchemaSQL();

// Custom schema
const ddl = getSchemaSQL('my_schema');

From the command line (after building):

cd packages/storage-sqlserver
node -e "import('./dist/index.js').then(m => console.log(m.getSchemaSQL()))"

Pipe to a file for SSMS:

node -e "import('./dist/index.js').then(m => console.log(m.getSchemaSQL()))" > schema.sql

Schema versioning

A dm_meta table tracks the schema version. On initialise(), the provider checks this version and warns if the database is newer than the provider. The provider does not auto-migrate — update the schema manually using the DDL output from getSchemaSQL().

Tables

All tables are prefixed with dm_ to avoid collisions when co-located with other schemas.

| Table | Description | |-------|-------------| | dm_meta | Schema version tracking | | dm_repositories | Repository definitions and governance config | | dm_vocabularies | Vocabulary JSON document per repository | | dm_vocabulary_change_log | Vocabulary change audit trail | | dm_entities | Graph nodes with provenance and optional embeddings | | dm_relationships | Graph edges with provenance |

Naming conventions

• Tables: plural snake_case (dm_entities, dm_relationships)
• Columns: snake_case (entity_id, created_at)
• Primary keys: pk_{table}
• Foreign keys: fk_{table}_{referenced_table}
• Indexes: ix_{table}_{columns}

Testing

The conformance test suite requires a running SQL Server instance:

MSSQL_CONNECTION_STRING="Server=localhost,1434;Database=deep-memory;User Id=sa;Password=YourPassword;TrustServerCertificate=true" \
  pnpm --filter @utaba/deep-memory-storage-sqlserver test

Without MSSQL_CONNECTION_STRING, tests are skipped.