@xata.io/pgroll

TypeScript definitions and validation for pgroll - a zero-downtime, reversible, schema migration tool for PostgreSQL.

Installation

npm install @xata.io/pgroll

Features

• 🔧 CLI Commands - Complete pgroll CLI commands structure
• 📄 JSON Schema - Migration schema definition and validation
• 🏷️ TypeScript Types - Auto-generated Zod schemas and TypeScript types
• ✅ Validation - Built-in validation for migration files
• 🔄 Auto-generated - Automatically updated from the latest pgroll definitions

Usage

CLI Commands

import { Commands } from '@xata.io/pgroll';

// Access pgroll CLI commands
console.log(Commands.commands);

// Example: Get all command names
const commandNames = Commands.commands.map((cmd) => cmd.name);
console.log(commandNames); // ['analyze', 'baseline', 'completion', ...]

JSON Schema

import { generateJSONSchema } from '@xata.io/pgroll';

// Get the complete JSON schema for pgroll migrations
const schema = generateJSONSchema();
console.log(schema);

TypeScript Types & Validation

import { Types } from '@xata.io/pgroll';

// Use Zod schemas for validation
const migration = {
  name: 'add_users_table',
  operations: [
    {
      create_table: {
        name: 'users',
        columns: [
          { name: 'id', type: 'serial', pk: true },
          { name: 'name', type: 'text', nullable: false }
        ]
      }
    }
  ]
};

// Validate migration structure
try {
  const validMigration = Types.MigrationDefinition.parse(migration);
  console.log('Migration is valid:', validMigration);
} catch (error) {
  console.error('Migration validation failed:', error);
}

// TypeScript types are also available
type Migration = Types.Migration;
type Operation = Types.OperationType;

Source URLs

import { PGROLL_JSON_SCHEMA_URL, PGROLL_CLI_DEFINITION_URL } from '@xata.io/pgroll';

// Get the source URLs for the definitions
console.log(PGROLL_JSON_SCHEMA_URL); // Schema URL
console.log(PGROLL_CLI_DEFINITION_URL); // CLI definition URL

Development

Generate Types

To regenerate the TypeScript definitions from the latest pgroll sources:

pnpm run generate

This will fetch the latest definitions from:

• https://raw.githubusercontent.com/xataio/pgroll/main/schema.json
• https://raw.githubusercontent.com/xataio/pgroll/refs/heads/main/cli-definition.json

Build

pnpm run build

Type Check

pnpm run tsc

Generated Files

• src/schema.ts - Complete JSON schema for pgroll migrations
• src/commands.ts - pgroll CLI commands definition
• src/types.ts - TypeScript types and Zod validation schemas
• src/index.ts - Main exports

Migration Operations

The package includes TypeScript definitions for all pgroll migration operations:

• add_column - Add a new column to a table
• alter_column - Modify an existing column
• create_index - Create a new index
• create_table - Create a new table
• drop_column - Remove a column from a table
• drop_constraint - Remove a constraint
• drop_index - Remove an index
• drop_table - Remove a table
• rename_constraint - Rename a constraint
• rename_table - Rename a table
• set_replica_identity - Set replica identity
• sql - Execute raw SQL

Related

• pgroll - Zero-downtime PostgreSQL schema migrations
• @xata.io/pgstream - PostgreSQL streaming and transformation definitions

License

Apache-2.0