@nanodb-orm/plugin-schema-guard

Schema guard plugin for nanodb-orm.

Use it to enforce required schema structures in plugin/runtime preflight and to run deep drift checks.

Install

npm install @nanodb-orm/plugin-schema-guard

Usage

import { createDatabase } from 'nanodb-orm';
import { schemaGuard, withSchemaGuard } from '@nanodb-orm/plugin-schema-guard';

const db = await createDatabase({
  tables,
  plugins: [
    schemaGuard({
      requireTables: ['users', 'sessions'],
      tables: {
        sessions: {
          requiredColumns: ['token', 'user_id', 'expires_at'],
          requiredIndexes: ['sessions_token_idx'],
        },
      },
    }),
  ],
});

const guarded = withSchemaGuard(db);
await guarded.schemaGuard.assert(); // includes deep validation by default

Options

schemaGuard({
  mode: 'error', // 'error' | 'warn'
  runOnReady: true, // run static rule preflight during plugin install
  includeDeepValidationInAssert: true, // default deep behavior for .assert()

  requireTables: ['users'],
  forbidTables: ['legacy_users'],

  tables: {
    users: {
      requiredColumns: ['id', 'email'],
      requiredIndexes: [
        'users_email_idx',
        { columns: ['email'], unique: true },
      ],
      requiredUniqueConstraints: [['email']],
      requiredForeignKeys: [
        {
          columns: ['org_id'],
          table: 'organizations',
          references: ['id'],
          onDelete: 'CASCADE',
        },
      ],
      requiredCheckConstraintNames: ['users_email_format'],
    },
  },
});

Runtime API

The plugin injects db.schemaGuard:

• inspect() -> synchronous static rule report
• check({ deep?: boolean }) -> static + optional deep drift validation
• assert({ deep?: boolean }) -> throws on mismatches