{"id":28047,"library":"playbackdb","title":"PlaybackDB","description":"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.","status":"active","version":"1.4.27","language":"javascript","source_language":"en","source_url":"https://github.com/playbackhealth/database","tags":["javascript","playback"],"install":[{"cmd":"npm install playbackdb","lang":"bash","label":"npm"},{"cmd":"yarn add playbackdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add playbackdb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"PostgreSQL client driver required for runtime schema operations and migrations.","package":"pg","optional":false}],"imports":[{"note":"ESM-only since v1.0. No CommonJS support.","wrong":"const { installSchema } = require('playbackdb')","symbol":"installSchema","correct":"import { installSchema } from 'playbackdb'"},{"note":"Named export, not default export.","wrong":"import getMigrationPath from 'playbackdb'","symbol":"getMigrationPath","correct":"import { getMigrationPath } from 'playbackdb'"},{"note":"TypeScript type only; do not use at runtime.","wrong":"import { SchemaVersion } from 'playbackdb'","symbol":"SchemaVersion","correct":"import type { SchemaVersion } from 'playbackdb'"}],"quickstart":{"code":"import { installSchema } from 'playbackdb';\nimport { Pool } from 'pg';\n\nconst pool = new Pool({\n  connectionString: process.env.DATABASE_URL ?? 'postgres://localhost:5432/playback',\n});\n\nasync function setup() {\n  try {\n    const result = await installSchema(pool, { version: 'latest' });\n    console.log('Schema installed:', result.version);\n  } catch (err) {\n    console.error('Install failed:', err);\n  } finally {\n    await pool.end();\n  }\n}\n\nsetup();","lang":"typescript","description":"Connects to a PostgreSQL database using pg Pool and installs the latest Playback schema via installSchema."},"warnings":[{"fix":"Replace new Client() with new Pool() and pass the pool instance.","message":"installSchema now requires a Pool object; passing a Client will throw.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Replace getMigrationPath with getMigrationDir; it returns a directory path.","message":"getMigrationPath is deprecated. Use getMigrationDir instead.","severity":"deprecated","affected_versions":">=1.2.0"},{"fix":"Use a separate staging environment to test migrations first.","message":"Schema migrations are irreversible. Always back up production databases before running installSchema.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refactor any .then() chains to async/await.","message":"Removed support for callback-style async operations. Use async/await only.","severity":"breaking","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use new Pool() and pass the pool object to installSchema.","cause":"Passed a Client instance instead of Pool.","error":"TypeError: pool.query is not a function"},{"fix":"Ensure the node_modules/playbackdb/migrations directory exists and contains valid SQL files.","cause":"The migration directory is empty or missing.","error":"Error: no schema version found for latest"},{"fix":"Run 'npm install playbackdb' and verify the import path.","cause":"Package not installed or import path is incorrect.","error":"Cannot find module 'playbackdb'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}