Aurora DSQL Tools for Prisma

CLI tools for using Prisma ORM with Amazon Aurora DSQL.

Overview

This package provides:

1. Schema Validator - Validates Prisma schemas for DSQL compatibility
2. Migration Transformer - Converts Prisma migrations to DSQL-compatible SQL using dsql-lint
3. Migration Linter - Checks SQL migrations for DSQL compatibility without modifying them
4. All-in-one Migrate Command - Validates, generates, and transforms in one step

Aurora DSQL has specific PostgreSQL compatibility limitations. These tools help you catch issues early and automate the required transformations.

Installation

npm install --save-dev @aws/aurora-dsql-prisma-tools

Supported Node.js versions: 20+ (Active and LTS releases)

@aws/dsql-lint is included and uses its bundled binary by default (no setup required). To use a custom or existing installation, set DSQL_LINT_PATH.

Quick Start

Generate a DSQL-compatible migration in one command:

npx aurora-dsql-prisma migrate prisma/schema.prisma -o prisma/migrations/001_init/migration.sql

If validation fails, fix your schema and re-run.

Commands

Validate Schema

Check your Prisma schema for DSQL compatibility before runtime:

npx aurora-dsql-prisma validate prisma/schema.prisma

What the Validator Checks

The validator checks that relationMode = "prisma" is set in the datasource block (DSQL does not support foreign keys). All other SQL compatibility checks are delegated to dsql-lint — the validator generates SQL from your schema and lints it. See the dsql-lint README for the full list of rules.

Example Output

✗ Missing relationMode = "prisma" in datasource block (line 1)
  → Add relationMode = "prisma" to your datasource block. DSQL does not support foreign key constraints.
✗ Column `"id"` uses SERIAL, which is not supported in DSQL.

✗ Validation failed: 2 error(s)

Transform Migrations

Transform Prisma-generated migrations to be DSQL-compatible:

# Transform from file
npx aurora-dsql-prisma transform raw.sql -o migration.sql

# Transform using pipes (stdin)
npx prisma migrate diff \
    --from-empty \
    --to-schema prisma/schema.prisma \
    --script | npx aurora-dsql-prisma transform > migration.sql

What the Transformer Does

The transform command uses dsql-lint --fix to apply DSQL compatibility fixes. See the dsql-lint README for the full list of rules and transformations.

Lint Migrations

Check a SQL migration file for DSQL compatibility without applying fixes:

npx aurora-dsql-prisma lint migration.sql

All-in-One Migrate

Validate, generate, and transform in one step:

npx aurora-dsql-prisma migrate prisma/schema.prisma -o prisma/migrations/001_init/migration.sql

For incremental migrations against an existing database:

npx aurora-dsql-prisma migrate prisma/schema.prisma \
    -o prisma/migrations/002_add_column/migration.sql \
    --from-config-datasource

Incremental Migrations

After your initial deployment, use --from-config-datasource to generate migrations that only include differences from the live database:

npx aurora-dsql-prisma migrate prisma/schema.prisma \
    -o prisma/migrations/002_add_email/migration.sql \
    --from-config-datasource

This requires a prisma.config.ts that provides database credentials. See the example for a working implementation.

Handling Unsupported Statements

Sometimes Prisma generates DROP CONSTRAINT statements when comparing against a live database. DSQL doesn't support DROP CONSTRAINT. If dsql-lint reports unfixable errors, review its output and manually adjust the migration.

Prisma Schema Requirements

When using Prisma with Aurora DSQL:

1. Set relation mode - use application-layer relationship management:

   datasource db {
     provider     = "postgresql"
     relationMode = "prisma"
   }

2. Use UUID for IDs:

   model User {
     id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
   }

3. Disable advisory locks - When running migrations:

   PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK=1 npx prisma migrate deploy

For the full list of Aurora DSQL SQL compatibility details, see the PostgreSQL compatibility reference.

Example

See examples/veterinary-app/ for a complete working example including:

• DSQL-compatible Prisma schema
• DsqlPrismaClient with automatic IAM authentication
• Sample CRUD operations
• Integration tests

Additional Resources

• Amazon Aurora DSQL Documentation
• Unsupported PostgreSQL Features in DSQL
• Aurora DSQL Connector for node-postgres
• Prisma Documentation
• Prisma Relation Mode

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.