Payload CMS Migration Workflow

Project Goal: Migrate from homemade PHP/MySQL to Payload CMS with PostgreSQL on Netlify + Neon, then build a modern responsive site redesign.

Quick Start

When starting a migration task:

1. •Find your task: See Migration Tasks or docs/payload-migration/04-migration-tasks.md
2. •Check context: Review Architecture Decisions below
3. •Verify completion: Follow success criteria for your collection
4. •Get help: See Quick Reference for commands and queries

Why Payload + PostgreSQL

• •Relational continuity: MySQL → PostgreSQL is simpler than MySQL → NoSQL
• •Direct database access: PHP can query PostgreSQL directly without learning GraphQL/GROQ
• •Code-first configuration: Collections defined in TypeScript with full type safety
• •Built-in APIs: REST + GraphQL without learning GROQ
• •Self-hosted flexibility: Full control over CMS and deployment

Key Architecture Decisions

Database Strategy

• •Single PostgreSQL database for all data (including votes)
• •Neon serverless PostgreSQL for production
• •Direct SQL access from PHP using PDO
• •ACID transactions for data consistency

Collection Patterns

1. •Base collections: People, DJs, Artists, Venues, Media
2. •Content collections: Concerts, Shows, Posts, Songs, Records
3. •Interactive collections: Top11, YearEndPolls, ModernRockMadness (with votes)

Migration Approach

• •Two-phase: (1) Migrate data and CMS, (2) Redesign frontend
• •Feature flags for gradual cutover
• •PHP site continues querying PostgreSQL directly
• •Payload Admin UI for content management

Core Data Models (Priority Order)

Full details: docs/payload-migration/03-core-data-models.md

Migration Tasks

Task 0: Setup Environment ✅ Complete

• •Payload Admin UI at http://localhost:3000/admin
• •PostgreSQL connection (Neon)
• •Netlify deployment configured
• •Cloudinary for media uploads

Details: docs/payload-migration/04-migration-tasks.md#task-0

Task 1: MySQL to PostgreSQL Schema

Convert MySQL schema to PostgreSQL:

• •Data type conversions (DATETIME → TIMESTAMP, TINYINT → BOOLEAN)
• •Foreign key constraints
• •Indexes for performance
• •Soft delete columns (deleted_at)

Details: docs/payload-migration/04-migration-tasks.md#task-1

Task 2: Data Migration

Export MySQL data and import to PostgreSQL:

• •Use mysqldump for data export
• •Transform data during import
• •Validate relationships
• •Test with sample queries

Details: docs/payload-migration/04-migration-tasks.md#task-2

Task 3+: Collection Implementation

For each collection:

1. •Define Payload collection schema in TypeScript
2. •Configure fields, relationships, access control
3. •Run migrations: yarn payload migrate
4. •Seed with sample data
5. •Test CRUD operations in Admin UI
6. •Verify PHP can query via PostgreSQL

Per-collection checklists: docs/payload-migration/07-success-criteria.md

PHP PostgreSQL Integration

PHP can query PostgreSQL directly without learning GraphQL:

// Connect to PostgreSQL (same as MySQL but different driver)
$pdo = new PDO(
  "pgsql:host=localhost;port=5432;dbname=ynot_payload_dev",
  "username",
  "password"
);

// Query Payload tables directly
$stmt = $pdo->prepare("
  SELECT c.id, c.date, c.venue_id, v.name as venue_name
  FROM concerts c
  JOIN venues v ON c.venue_id = v.id
  WHERE c.date >= NOW()
  ORDER BY c.date ASC
  LIMIT 10
");
$stmt->execute();
$concerts = $stmt->fetchAll(PDO::FETCH_ASSOC);

Full guide: docs/payload-migration/03.5-php-postgresql-querying.md

Cloudinary Media Storage

For image uploads:

1. •Configure Cloudinary plugin in payload.config.ts
2. •Set environment variables (CLOUDINARY_CLOUD_NAME, etc.)
3. •Use Media collection for all uploads
4. •Images auto-optimized and delivered via CDN

Detailed setup: docs/payload-migration/12-cloudinary-integration.md

Success Criteria Per Collection

Each collection must meet:

• • Payload schema defined in TypeScript
• • Migrations run successfully
• • Admin UI shows collection with correct fields
• • Can create/edit/delete records
• • Relationships work correctly
• • PHP can query via PostgreSQL
• • Sample data seeded for testing

Complete checklists: docs/payload-migration/07-success-criteria.md

Quick Reference

Development Commands

# Start Payload dev server
yarn payload:dev

# Run migrations
yarn payload migrate

# Seed sample data
yarn seed:payload

# Access Admin UI
open http://localhost:3000/admin

PostgreSQL Connection

DATABASE_URI=postgresql://user:pass@localhost:5432/ynot_payload_dev
DATABASE_SSL=disable  # For local development

Useful Queries

-- List all collections (tables)
SELECT tablename FROM pg_tables 
WHERE schemaname = 'public' 
ORDER BY tablename;

-- Check collection structure
\d concerts

-- Sample data query
SELECT * FROM concerts 
ORDER BY date DESC 
LIMIT 5;

More examples: docs/payload-migration/08-quick-reference.md

Common Patterns

Many-to-Many Relationships

Use Payload's relationship field with hasMany: true:

{
  name: 'artists',
  type: 'relationship',
  relationTo: 'artists',
  hasMany: true,
}

Soft Deletes

Payload handles this automatically with timestamps: true in collection config.

Rich Text Content

Use Payload's lexical editor for Posts:

{
  name: 'content',
  type: 'richText',
}

File Uploads

Configure cloudinary plugin for Media collection:

plugins: [
  cloudinaryPlugin({
    collections: {
      media: true,
    },
  }),
]

Troubleshooting

Migration Fails

• •Check PostgreSQL connection
• •Verify all dependencies installed
• •Review migration logs: yarn payload migrate --debug

Admin UI Not Accessible

• •Ensure yarn payload:dev is running
• •Check port 3000 is available
• •Verify DATABASE_URI in .env.local

PHP Can't Query

• •Confirm PostgreSQL credentials
• •Test connection: psql -h localhost -U user -d ynot_payload_dev
• •Check table names match schema

Reference Documentation

Comprehensive details in these chapters:

1. •Project Overview - Goals, current state, strategy
2. •Architecture Decisions - Data handling, patterns
3. •Core Data Models - All collections with status
4. •PHP PostgreSQL Querying - Direct SQL access
5. •Migration Tasks - Step-by-step tasks
6. •Shared Utilities - File structure, patterns
7. •Frontend Cutover - Feature flags, deployment
8. •Success Criteria - Per-collection checklists
9. •Quick Reference - Commands, queries, templates
10. •Relational Advantages - Why PostgreSQL
11. •CMS Comparison - Sanity vs Payload
12. •Capacity Planning - Limits, pricing
13. •Cloudinary Integration - Media storage setup

Each chapter is self-contained for cold-start agent conversations.

Workflow Tips

1. •Start small: Begin with base collections (People, Venues)
2. •Test incrementally: Verify each collection before moving to next
3. •Seed data: Use sample data to test relationships
4. •Document issues: Note any migration problems for team review
5. •Follow priority order: Collections are ordered by dependencies

Remember: This is a two-phase project. Phase 1 (current) focuses on data migration and CMS setup. Phase 2 will handle frontend redesign.