# @prisma-next/sql-schema-ir

> SQL Schema IR types for schema introspection and verification

Latest version **0.16.0** (published 2026-07-21) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @prisma-next/sql-schema-ir
pnpm add @prisma-next/sql-schema-ir
yarn add @prisma-next/sql-schema-ir
bun add @prisma-next/sql-schema-ir
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.16.0 |
| Published | 2026-07-21 |
| First published | 2025-12-09 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=24 |
| Dependencies | 3 |
| Unpacked size | 191.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 410 |
| Maintainers | sevinf, tylerhogarth, aqrln, wmadden-prisma |

## Links

- npm: https://www.npmjs.com/package/@prisma-next/sql-schema-ir
- Repository: https://github.com/prisma/prisma-next
- Homepage: https://github.com/prisma/prisma-next#readme
- Issues: https://github.com/prisma/prisma-next/issues
- npm.io page: https://npm.io/package/@prisma-next/sql-schema-ir

## Dependencies (3)

- [@prisma-next/utils](https://npm.io/package/@prisma-next/utils.md) 0.16.0
- [@prisma-next/contract](https://npm.io/package/@prisma-next/contract.md) 0.16.0
- [@prisma-next/framework-components](https://npm.io/package/@prisma-next/framework-components.md) 0.16.0

## Recent versions

- 0.16.0 (latest) — 2026-07-21
- 0.16.0-dev.35 (dev) — 2026-08-24
- 0.3.0-pr.112.2 (pr) — 2026-01-13
- 0.16.0-dev.34 — 2026-07-27
- 0.16.0-dev.33 — 2026-07-27
- 0.16.0-dev.32 — 2026-07-27
- 0.16.0-dev.31 — 2026-07-27
- 0.16.0-dev.30 — 2026-07-27
- 0.16.0-dev.29 — 2026-07-27
- 0.16.0-dev.28 — 2026-07-24
- 0.16.0-dev.27 — 2026-07-24
- 0.16.0-dev.26 — 2026-07-24
- 0.16.0-dev.25 — 2026-07-24
- 0.16.0-dev.24 — 2026-07-24
- 0.16.0-dev.23 — 2026-07-24
- … 1083 more at https://npm.io/package/@prisma-next/sql-schema-ir/versions

## README

# @prisma-next/sql-schema-ir

SQL Schema Intermediate Representation (IR) types for Prisma Next.

## Overview

This package defines the core types for the SQL Schema IR, a target-agnostic representation of SQL database schemas. This IR is used for schema verification, migration planning, and other tooling operations within the SQL family.

## Purpose

- **Provide a canonical in-memory representation** of SQL schemas that is independent of specific database implementations
- **Decouple schema introspection from verification logic** - adapters produce `SqlSchemaIR`, verification logic consumes it
- **Enable extensible metadata** via annotations for targets and extension packs
- **Support future migration planning** by providing a structured representation of schema differences

## Responsibilities

- **Type Definitions**: Provides core types for SQL Schema IR (`SqlSchemaIR`, `SqlTableIR`, `SqlColumnIR`, etc.)
- **Shared Plane Package**: Located in the shared plane, making it accessible to both migration-plane and runtime-plane packages
- **Extensibility**: Supports annotations for targets and extension packs to attach metadata without modifying core IR structure
- **Type Safety**: Provides TypeScript types for schema representation with proper nullability and constraint modeling

## Dependencies

- **`@prisma-next/contract`**: For `Contract` type (used in `SqlSchemaIR`)

**Dependents:**
- **Migration Plane**:
  - `@prisma-next/family-sql` - SQL family instance uses SqlSchemaIR for schema verification
  - `@prisma-next/framework-components` - Core verification logic (via `./control`)
  - `@prisma-next/adapter-postgres` - Postgres introspection
  - `@prisma-next/extension-pgvector` - Extension verification hooks
- **Runtime Plane** (future):
  - Migration planning logic
  - Schema diff utilities

## Types

### Core Types

- **`SqlSchemaIR`** - Complete database schema representation with tables, extensions, and annotations
- **`SqlTableIR`** - Table representation with columns, constraints, indexes, and annotations
- **`SqlColumnIR`** - Column representation with `nativeType` (DB-specific type), nullability, and annotations
- **`SqlForeignKeyIR`** - Foreign key constraint representation
- **`SqlUniqueIR`** - Unique constraint representation
- **`SqlIndexIR`** - Index representation
- **`SqlAnnotations`** - Namespaced extensibility metadata (e.g., `{ pg: { version: '15' } }`)

### Key Design Decisions

1. **Native type primary**: Columns capture the database-native type (`nativeType`, e.g., `'integer'`, `'vector'`). Codec IDs now live exclusively in the contract—schema IR focuses solely on what exists in the database. This keeps schema verification centered on actual storage, while contract metadata handles codec-level concerns.

2. **Annotations**: All IR types support optional `annotations` for extensibility. This allows targets and extensions to attach metadata without modifying the core IR structure.

3. **Shared Plane**: This package is in the **shared plane**, meaning it can be safely imported by both migration-plane (verification, migration planning) and runtime-plane code.

## Usage

### Basic Usage

```typescript
import type { SqlSchemaIR, SqlTableIR, SqlColumnIR } from '@prisma-next/sql-schema-ir/types';

const schemaIR: SqlSchemaIR = {
  tables: {
    user: {
      name: 'user',
      columns: {
        id: {
          name: 'id',
          nativeType: 'integer',
          nullable: false,
        },
        email: {
          name: 'email',
          nativeType: 'text',
          nullable: false,
        },
      },
      primaryKey: { columns: ['id'] },
      foreignKeys: [],
      uniques: [{ columns: ['email'] }],
      indexes: [],
    },
  },
  extensions: ['vector'],
  annotations: {
    pg: {
      version: '15',
    },
  },
};
```

### Schema Introspection

Adapters produce `SqlSchemaIR` by querying database catalogs:

```typescript
// In Postgres adapter
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';

const controlAdapter = postgresAdapter.createControlInstance();
const schemaIR: SqlSchemaIR = await controlAdapter.introspect(driver, contract);
```

### Schema Verification

Schema verification is performed via the `schemaVerify()` method on the SQL family instance:

```typescript
// In SQL family instance
import sql from '@prisma-next/family-sql/control';
import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';

// Create family instance
const familyInstance = sql.create({
  target: postgresTargetDescriptor,
  adapter: postgresAdapterDescriptor,
  driver: postgresDriverDescriptor,
  extensions: [],
});

// Schema verification is performed via family instance method
const result = await familyInstance.schemaVerify({
  driver,
  contractIR,
  strict: false,
  contractPath: './contract.json',
});
// schemaVerify internally calls adapter.introspect() to get schemaIR
```

## Architecture

### Package Location

- **Domain**: `sql`
- **Layer**: `core`
- **Plane**: `shared`

This package sits at the core layer in the shared plane, making it accessible to both migration-plane (authoring, tooling, targets) and runtime-plane (lanes, runtime, adapters) packages.


## Related Documentation

- `docs/briefs/11-schema-ir.md` - Schema IR project brief
- `docs/briefs/SQL Schema IR and Verification.md` - Detailed design document
- `packages/2-sql/3-tooling/family/src/core/instance.ts` - SQL family instance with `schemaVerify()` method
- `packages/3-targets/6-adapters/postgres/src/exports/control.ts` - Postgres introspection entrypoint

---
_Source: https://npm.io/package/@prisma-next/sql-schema-ir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
