@plyaz/db 0.3.1 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plyaz/db",
-  "version": "0.3.1",
-  "description": "Package description",
+  "version": "0.4.1",
+  "description": "Unified database abstraction layer with CLI for migrations and seeds",
   "type": "module",
   "keywords": [],
   "packageManager": "pnpm@10.11.0",
@@ -33,7 +33,8 @@
   "author": "Redeemer Pace",
   "license": "ISC",
   "files": [
-    "dist"
+    "dist",
+    "template"
   ],
   "dependencies": {
     "@nestjs/common": "^11.1.3",

package/template/config/db.config.mjs.template

@@ -0,0 +1,33 @@
+/**
+ * Database Configuration
+ *
+ * Used by the @plyaz/db CLI for migrations and seeds
+ *
+ * @type {import('@plyaz/db').DatabaseServiceConfig}
+ */
+export default {
+  // ============================================================================
+  // ADAPTER CONFIGURATION
+  // ============================================================================
+
+  adapter: globalThis.process.env.DB_ADAPTER ?? '{{ADAPTER}}',
+
+  config: {
+    connectionString: globalThis.process.env.DATABASE_URL ?? '{{CONNECTION_STRING}}',
+    poolSize: 20,
+
+    // Custom ID columns (optional)
+    // tableIdColumns: {
+    //   'feature_flags': 'key',
+    // },
+  },
+
+  // ============================================================================
+  // MIGRATIONS & SEEDS PATHS
+  // ============================================================================
+
+  migrationsPath: '{{MIGRATIONS_PATH}}',
+  seedsPath: '{{SEEDS_PATH}}',
+  migrationsTable: '{{MIGRATIONS_TABLE}}',
+  seedsTable: '{{SEEDS_TABLE}}',
+};

package/template/migrations/migration.sql.template

@@ -0,0 +1,29 @@
+-- ============================================================================
+-- Migration: {{DESCRIPTION}}
+-- Version: {{VERSION}}
+-- Created: {{CREATED_DATE}}
+-- Author: {{AUTHOR}}
+-- Description: {{DESCRIPTION}}
+-- ============================================================================
+
+-- UP
+-- Create {{TABLE_NAME}} table
+CREATE TABLE IF NOT EXISTS {{SCHEMA}}.{{TABLE_NAME}} (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(255) NOT NULL,
+  -- Add your columns here
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  deleted_at TIMESTAMPTZ DEFAULT NULL
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_{{TABLE_NAME}}_created_at ON {{SCHEMA}}.{{TABLE_NAME}}(created_at);
+
+-- Comments
+COMMENT ON TABLE {{SCHEMA}}.{{TABLE_NAME}} IS '{{DESCRIPTION}}';
+
+-- DOWN
+-- Drop in reverse order
+DROP INDEX IF EXISTS idx_{{TABLE_NAME}}_created_at;
+DROP TABLE IF EXISTS {{SCHEMA}}.{{TABLE_NAME}};

package/template/migrations/migration.ts.template

@@ -0,0 +1,54 @@
+// ============================================================================
+// Migration {{VERSION}}: {{DESCRIPTION}}
+// ============================================================================
+// Created: {{CREATED_DATE}}
+// Author: {{AUTHOR}}
+// Description: {{DESCRIPTION}}
+// Tables: {{SCHEMA}}.{{TABLE_NAME}}
+// Dependencies: [List migration dependencies if any]
+// ============================================================================
+
+import type { DatabaseAdapterType } from '@plyaz/types/db';
+
+/**
+ * Run the migration (forward)
+ * Creates the {{TABLE_NAME}} table with standard audit columns
+ */
+export async function up(adapter: DatabaseAdapterType): Promise<void> {
+  // Create table
+  await adapter.query(`
+    CREATE TABLE IF NOT EXISTS {{SCHEMA}}.{{TABLE_NAME}} (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      name VARCHAR(255) NOT NULL,
+      -- Add your columns here
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      deleted_at TIMESTAMPTZ DEFAULT NULL
+    )
+  `);
+
+  // Create indexes
+  await adapter.query(`
+    CREATE INDEX IF NOT EXISTS idx_{{TABLE_NAME}}_created_at
+    ON {{SCHEMA}}.{{TABLE_NAME}}(created_at)
+  `);
+
+  // Add table comment
+  await adapter.query(`
+    COMMENT ON TABLE {{SCHEMA}}.{{TABLE_NAME}} IS '{{DESCRIPTION}}'
+  `);
+
+  console.log('[Migration {{VERSION}}] {{DESCRIPTION}} - completed');
+}
+
+/**
+ * Rollback the migration (reverse)
+ * Drops the {{TABLE_NAME}} table and related objects
+ */
+export async function down(adapter: DatabaseAdapterType): Promise<void> {
+  // Drop in reverse order of creation
+  await adapter.query(`DROP INDEX IF EXISTS idx_{{TABLE_NAME}}_created_at`);
+  await adapter.query(`DROP TABLE IF EXISTS {{SCHEMA}}.{{TABLE_NAME}}`);
+
+  console.log('[Migration {{VERSION}}] {{DESCRIPTION}} - rolled back');
+}

package/template/seeds/seed.csv.template

@@ -0,0 +1,22 @@
+# Seed: {{DESCRIPTION}}
+# Table: {{SCHEMA}}.{{TABLE_NAME}}
+# Created: {{CREATED_DATE}}
+#
+# CSV Seed File - Edit columns and data below
+# First row defines column names matching the table schema
+# Subsequent rows contain the data to insert
+#
+# Usage:
+#   plyaz-db seed run        - Imports this CSV into the database
+#   plyaz-db seed reset      - Removes seeded records
+#
+# Notes:
+#   - UUIDs should use format: 00000000-0000-0000-0000-000000000001
+#   - Dates use ISO format: 2025-01-01T00:00:00.000Z
+#   - Empty values: leave field empty between commas
+#   - Strings with commas: wrap in double quotes "value, with comma"
+#
+id,name,description,created_at
+{{UUID_1}},Example Record 1,First seed record,{{CREATED_DATE}}T00:00:00.000Z
+{{UUID_2}},Example Record 2,Second seed record,{{CREATED_DATE}}T00:00:00.000Z
+{{UUID_3}},Example Record 3,Third seed record,{{CREATED_DATE}}T00:00:00.000Z

package/template/seeds/seed.sql.template

@@ -0,0 +1,19 @@
+-- ============================================================================
+-- Seed: {{DESCRIPTION}}
+-- Order: {{ORDER}}
+-- Created: {{CREATED_DATE}}
+-- Author: {{AUTHOR}}
+-- Description: {{DESCRIPTION}}
+-- Table: {{SCHEMA}}.{{TABLE_NAME}}
+-- ============================================================================
+
+-- Insert seed data for {{TABLE_NAME}}
+-- Uses ON CONFLICT for idempotent seeds
+
+INSERT INTO {{SCHEMA}}.{{TABLE_NAME}} (id, name, created_at) VALUES
+  ('{{UUID_1}}', 'Seed Record 1', NOW()),
+  ('{{UUID_2}}', 'Seed Record 2', NOW()),
+  ('{{UUID_3}}', 'Seed Record 3', NOW())
+ON CONFLICT (id) DO UPDATE SET
+  name = EXCLUDED.name,
+  updated_at = NOW();

package/template/seeds/seed.ts.template

@@ -0,0 +1,63 @@
+/**
+ * Seed: {{DESCRIPTION}}
+ * Order: {{ORDER}}
+ * Created: {{CREATED_DATE}}
+ * Author: {{AUTHOR}}
+ * Description: {{DESCRIPTION}}
+ * Table: {{SCHEMA}}.{{TABLE_NAME}}
+ */
+
+import type { DatabaseAdapterType } from '@plyaz/types/db';
+
+// Define your seed data
+const TABLE_NAME = '{{TABLE_NAME}}';
+const SEED_DATA = [
+  { name: 'Seed Record 1', value: 100 },
+  { name: 'Seed Record 2', value: 200 },
+  { name: 'Seed Record 3', value: 300 },
+];
+
+/**
+ * Run the seed (insert data into {{TABLE_NAME}})
+ */
+export async function run(adapter: DatabaseAdapterType): Promise<void> {
+  console.log('[Seed] {{DESCRIPTION}} - starting...');
+
+  for (const item of SEED_DATA) {
+    // Check if data already exists (idempotent)
+    const existing = await adapter.findMany(TABLE_NAME, {
+      filter: { field: 'name', operator: 'eq', value: item.name },
+    });
+
+    if (existing.success && existing.value && existing.value.data.length > 0) {
+      console.log(`[Seed] ${item.name} already exists, skipping`);
+      continue;
+    }
+
+    await adapter.create(TABLE_NAME, {
+      ...item,
+      created_at: new Date().toISOString(),
+    });
+  }
+
+  console.log(`[Seed] {{DESCRIPTION}} - created ${SEED_DATA.length} records`);
+}
+
+/**
+ * Cleanup the seed data (for reset operations)
+ */
+export async function cleanup(adapter: DatabaseAdapterType): Promise<void> {
+  console.log('[Seed] {{DESCRIPTION}} - cleaning up...');
+
+  // Delete seeded records by identifiable pattern
+  if (typeof adapter.query === 'function') {
+    for (const item of SEED_DATA) {
+      await adapter.query(
+        `DELETE FROM {{SCHEMA}}.${TABLE_NAME} WHERE name = $1`,
+        [item.name]
+      );
+    }
+  }
+
+  console.log('[Seed] {{DESCRIPTION}} - cleanup complete');
+}