PlaybackDB

1.4.27 verified Sat May 09 auth: no javascript

PlaybackDB provides PostgreSQL database schemas and utilities for the Playback health platform. Version 1.4.27 is the latest stable release. It includes schema definitions, migration tooling, and type-safe query builders. Unlike generic ORMs, it is tightly coupled to Playback's domain model and internal conventions. The package is released on an ad-hoc cadence alongside Playback application updates. Key differentiators include built-in support for Playback's multi-tenant architecture and automatic audit logging. It requires Node.js 14+ and pg (node-postgres) as a peer dependency.

Common errors

error TypeError: pool.query is not a function ↓

cause Passed a Client instance instead of Pool.

fix

Use new Pool() and pass the pool object to installSchema.

error Error: no schema version found for latest ↓

cause The migration directory is empty or missing.

fix

Ensure the node_modules/playbackdb/migrations directory exists and contains valid SQL files.

error Cannot find module 'playbackdb' ↓

cause Package not installed or import path is incorrect.

fix

Run 'npm install playbackdb' and verify the import path.

Warnings

breaking installSchema now requires a Pool object; passing a Client will throw. ↓

fix Replace new Client() with new Pool() and pass the pool instance.

deprecated getMigrationPath is deprecated. Use getMigrationDir instead. ↓

fix Replace getMigrationPath with getMigrationDir; it returns a directory path.

gotcha Schema migrations are irreversible. Always back up production databases before running installSchema. ↓

fix Use a separate staging environment to test migrations first.

breaking Removed support for callback-style async operations. Use async/await only. ↓

fix Refactor any .then() chains to async/await.

Install

npm install playbackdb

yarn add playbackdb

pnpm add playbackdb

Imports

installSchema

wrong

const { installSchema } = require('playbackdb')

correct

import { installSchema } from 'playbackdb'

ESM-only since v1.0. No CommonJS support.

getMigrationPath

wrong

import getMigrationPath from 'playbackdb'

correct

import { getMigrationPath } from 'playbackdb'

Named export, not default export.

SchemaVersion

wrong

import { SchemaVersion } from 'playbackdb'

correct

import type { SchemaVersion } from 'playbackdb'

TypeScript type only; do not use at runtime.

Quickstart

Connects to a PostgreSQL database using pg Pool and installs the latest Playback schema via installSchema.

import { installSchema } from 'playbackdb';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL ?? 'postgres://localhost:5432/playback',
});

async function setup() {
  try {
    const result = await installSchema(pool, { version: 'latest' });
    console.log('Schema installed:', result.version);
  } catch (err) {
    console.error('Install failed:', err);
  } finally {
    await pool.end();
  }
}

setup();