prisma-pglite

Enabling easy Prisma usage with PGlite. This includes a runtime adapter helper and a CLI Prisma wrapper:

• CLI

  • Enables prisma migrate dev with a PGlite database.
  • Enables prisma migrate reset with a PGlite database.
  • Passes all other commands to the standard prisma CLI.

• adapter helper

  • Includes and wraps pglite-prisma-adapter.
  • Automatically propagates your schema to the PGlite database (similar to prisma db push but lacking the ability to apply new migrations to an existing PGlite database).

See the full reference docs at https://electrovir.github.io/prisma-pglite

Install

npm i prisma-pglite

Usage

tl;dr

• Use the prisma-client generator in your schema.prisma (driver adapters are built in to Prisma v7, so no preview feature is required):

  generator client {
      provider = "prisma-client"
      output   = "../generated"
  }

• Use createPgliteAdapter:

  import {PrismaClient} from '../generated/client.js';
  import {createPgliteAdapter} from 'prisma-pglite';
  
  const prismaClient = new PrismaClient({
      adapter: await createPgliteAdapter(),
  });

• Create new migrations with npx prisma-pglite migrate dev

CLI

Instead of running Prisma commands like this:

npx prisma migrate dev

Run them like this:

npx prisma-pglite migrate dev

The prisma-pglite CLI will:

• Intercept migrate dev commands so that they work without running a full Postgres instance.
  • Use --config <prisma-config-path> to customize the Prisma config location. The schema and the migrations directory (migrations.path) are both read from it. Defaults to prisma.config.ts in your current directory.
  • Use --name <migration-name> to provide the migration name inline (otherwise the CLI will prompt you for one).
• Intercept migrate reset commands so that they work with a PGlite database.
  • Use --config <prisma-config-path> to customize the Prisma config location. The schema and the migrations directory (migrations.path) are both read from it. Defaults to prisma.config.ts in your current directory.
  • Use --database <pglite-db-parent-dir-path> to customize the location of your PGlite database that needs to be reset.
• Automatically append --no-hints to the prisma generate command.
• Pass all other commands directly to the Prisma CLI without modification.

All CLI commands are also accessible via the exported API:

• migrate dev:

  import {createPgliteMigration} from 'prisma-pglite';
  
  await createPgliteMigration({
      migrationName: 'my migration',
  });

• migrate reset:

  import {resetPgliteDatabase} from 'prisma-pglite';
  
  await resetPgliteDatabase();

• the whole CLI:

  import {runPrisma} from 'prisma-pglite';
  
  await runPrisma(['migrate dev']);
  await runPrisma(['generate']);

Adapter Helper

Use this when instantiating your PrismaClient instance to connect to or create a PGlite database:

import {join} from 'node:path';
import {PrismaClient} from '../generated/client.js';
import {createPgliteAdapter} from 'prisma-pglite';

const myPrismaConfigPath = join('packages', 'backend', 'prisma.config.ts');

const prismaClient = new PrismaClient({
    adapter: await createPgliteAdapter({
        prismaConfigPath: myPrismaConfigPath,
    }),
});

NOTE: createPgliteAdapter can only push your schema to new PGlite databases. Thus, you'll need to reset your dev database whenever you create a new migration (I suggest investing in a seed script to workaround this and make your dev experience more consistent in general).

See the type PgliteAdapterParams for more details on customizing createPgliteAdapter.

This package requires Prisma v7 or later. Driver adapters are enabled by default in Prisma v7, so the adapter parameter is always available on your PrismaClient constructor (no preview feature is required). Use the prisma-client generator in your schema.prisma:

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

Schema engine version

Migrations run through Prisma's WASM schema engine (@prisma/schema-engine-wasm), which prisma-pglite depends on at a pinned version. That package publishes only prerelease-tagged versions, so it can't be expressed as a semver range. prisma-pglite ships a specific tested version as the default.

If you need it to match a different Prisma release, override the version in package.json with the following (use the exact @prisma/schema-engine-wasm version that ships with your prisma):

"overrides": {"@prisma/schema-engine-wasm": "7.9.0-<n>.<hash>"}

PGlite paths

By default, the pgliteDirPath parameter of createPgliteAdapter expects multiple PGlite database to exist within itself. The default database will be in ${pgliteDirPath}/dev and all test database (triggered by passing in the testContext parameter) will be in ${pgliteDirPath}/${testName}. This structure can be ignored entirely by instead setting the directDatabaseDirPath parameter, but then you lose automatic test database paths.

Examples

• Create a new migration with some flags:

  npx prisma-pglite migrate dev --config packages/backend/prisma.config.ts --name 'add user table'

• Reset your PGlite database

  npx prisma-pglite migrate reset --database .config/pglite-db

• Customize the PGlite adapter:

  import {join} from 'node:path';
  import {PrismaClient} from '../generated/client.js';
  import {createPgliteAdapter} from 'prisma-pglite';
  
  const myPrismaConfigPath = join('packages', 'backend', 'prisma.config.ts');
  
  const prismaClient = new PrismaClient({
      adapter: await createPgliteAdapter({
          prismaConfigPath: myPrismaConfigPath,
          dbParentDirPath: join('.dev', 'pglite'),
      }),
  });

• Create a fresh and super fast PGlite database instance for each test:

  import {describe, it} from '@augment-vir/test';
  import {join} from 'node:path';
  import {PrismaClient} from '../generated/client.js';
  import {createPgliteAdapter} from 'prisma-pglite';
  
  const myPrismaConfigPath = join('packages', 'backend', 'prisma.config.ts');
  
  describe('my test', () => {
      it('connects to the database', async (testContext) => {
          const prismaClient = new PrismaClient({
              adapter: await createPgliteAdapter({
                  prismaConfigPath: myPrismaConfigPath,
                  dbParentDirPath: join('.dev', 'pglite'),
                  dbDirName: testContext,
                  /** It is recommended to always reset the database for tests. */
                  resetDatabase: true,
              }),
          });
      });
  });