payload（payload 数据库）

Payload CMS Operations

Manage Payload CMS content via REST API. Works with any Payload deployment (production or local).

When to Use

• Creating or editing posts/pages in Payload CMS
• Converting markdown content to Lexical rich text format
• Listing and querying Payload collections
• Bulk content updates

Workflow: REST API with Authentication

Step 1: Determine the API Endpoint

Ask the user for their Payload site URL, or check common locations:

# Production site (ask user or check project config)
curl -s "https://your-site.com/api/posts?limit=1" | head -c 100

# Local development
curl -s "http://localhost:3000/api/posts?limit=1" 2>/dev/null | head -c 100
curl -s "http://localhost:3010/api/posts?limit=1" 2>/dev/null | head -c 100

Step 2: Authenticate

For mutations (create/update/delete), authentication is required. Payload uses session-based auth.

Option A: User provides credentials

# Login to get auth token
curl -X POST "https://your-site.com/api/users/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}' \
  -c cookies.txt

# Use the cookie file for authenticated requests
curl -X POST "https://your-site.com/api/posts" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"title": "...", "content": {...}}'

Option B: User logs in via admin UI Have the user log in at /admin, then extract the payload-token cookie from their browser for use in API calls.

Step 3: Create/Update Content

# Create a post
curl -X POST "https://your-site.com/api/posts" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "title": "Post Title",
    "slug": "post-slug",
    "content": { "root": { ... } },
    "_status": "published"
  }'

# Update a post
curl -X PATCH "https://your-site.com/api/posts/POST_ID" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"content": { "root": { ... } }}'

Step 4: Verify

# Check the post was created
curl -s "https://your-site.com/api/posts?where[slug][equals]=post-slug" | jq '.docs[0]'

Lexical JSON Structure

Payload's Lexical editor stores content as JSON:

{
  "root": {
    "type": "root",
    "format": "",
    "indent": 0,
    "version": 1,
    "direction": "ltr",
    "children": [
      {
        "type": "paragraph",
        "format": "",
        "indent": 0,
        "version": 1,
        "direction": "ltr",
        "children": [
          {"type": "text", "text": "Content here", "mode": "normal", "format": 0, "detail": 0, "version": 1, "style": ""}
        ]
      }
    ]
  }
}

Supported Node Types

Text Format Bitmask

Markdown to Lexical Conversion

The skill includes a Python script for converting markdown to Lexical JSON:

python3 ${SKILL_DIR}/scripts/md_to_lexical.py article.md > /tmp/content.json

Common Collections

Local Development Alternative

If working locally and REST auth is problematic, write an inline script in the project:

// scripts/create-post.ts
import { getPayload } from 'payload'
import config from '../src/payload.config'

const payload = await getPayload({ config })
await payload.create({
  collection: 'posts',
  data: { title: '...', content: {...}, _status: 'published' }
})
process.exit(0)

Run with: source.env.local && bunx tsx scripts/create-post.ts

Note: If Drizzle prompts for schema migration, answer 'n' and use REST API instead.

Payload CLI Commands

The Payload CLI provides comprehensive database and project management:

Migration Commands

# Check migration status
bun run payload migrate:status

# Run pending migrations
bun run payload migrate

# Create a new migration
bun run payload migrate:create migration-name

# Rollback last migration
bun run payload migrate:down

# Rollback and re-run all migrations
bun run payload migrate:refresh

# Reset all migrations (rollback everything)
bun run payload migrate:reset

# Fresh start - drop all tables and re-run migrations
bun run payload migrate:fresh

Generation Commands

# Generate TypeScript types from collections
bun run payload generate:types

# Generate import map
bun run payload generate:importmap

# Generate Drizzle database schema
bun run payload generate:db-schema

Utility Commands

# Show Payload project info
bun run payload info

# Run a custom script with Payload initialized
bun run payload run scripts/my-script.ts

Jobs Commands (if using Payload Jobs)

# Run queued jobs
bun run payload jobs:run

# Run jobs with options
bun run payload jobs:run --limit 10 --queue default

# Handle scheduled jobs
bun run payload jobs:handle-schedules

Database Security (RLS)

CRITICAL: Payload uses application-level access control by default. For production security, implement Row Level Security (RLS) at the database level:

Why RLS Matters

• Application-level filtering can be bypassed with direct database connections
• RLS enforces security at the database level
• Even table owners cannot bypass RLS when FORCE ROW LEVEL SECURITY is enabled

RLS Migration Template

Create a migration for user-data tables:

// src/migrations/YYYYMMDDHHMMSS_enable_rls.ts
import { type MigrateUpArgs, type MigrateDownArgs, sql } from "@payloadcms/db-postgres";

export async function up({ db }: MigrateUpArgs): Promise<void> {
  // Helper function to check admin status
  await db.execute(sql`
    CREATE OR REPLACE FUNCTION is_admin()
    RETURNS BOOLEAN
    LANGUAGE SQL
    STABLE
    SECURITY DEFINER
    AS $$
      SELECT COALESCE(
        CURRENT_SETTING('app.current_user_role', TRUE) = 'admin',
        FALSE
      );
    $$;
  `);

  // Enable RLS on sensitive tables
  await db.execute(sql`
    ALTER TABLE users ENABLE ROW LEVEL SECURITY;
    ALTER TABLE users FORCE ROW LEVEL SECURITY;

    -- Users can only access their own data
    CREATE POLICY users_select_policy ON users
      FOR SELECT USING (id = (SELECT get_current_user_id()) OR (SELECT is_admin()));

    CREATE POLICY users_update_policy ON users
      FOR UPDATE USING (id = (SELECT get_current_user_id()) OR (SELECT is_admin()));
  `);
}

export async function down({ db }: MigrateDownArgs): Promise<void> {
  await db.execute(sql`DROP FUNCTION IF EXISTS is_admin();`);
  await db.execute(sql`ALTER TABLE users DISABLE ROW LEVEL SECURITY;`);
}

Tables Requiring RLS

• users - User profiles and sensitive data
• api_keys - API credentials
• deposits - Financial transaction data
• usage_logs - Audit trails and usage data
• Any table with user-specific data

Performance Optimization

• Always add indexes on columns used in RLS policies (e.g., user_id)
• Use (SELECT function()) pattern for caching auth checks per query
• Create helper functions with SECURITY DEFINER for complex logic

Migration Workflows

Development Mode vs Migrations

Development Mode (Push):

• Automatic schema updates via push: true (default)
• Good for rapid prototyping
• NOT for production

Migration Mode:

• Explicit schema control via migration files
• Required for production databases
• Version-controlled schema changes

Typical Workflow

1. Develop locally with push mode (default)

- Make changes to Payload config - Drizzle automatically pushes changes to local DB

1. Create migration when feature is complete bun run payload migrate:create feature-name
2. Review generated migration before committing
3. Run migrations in production before deployment # In CI/CD pipeline bun run payload migrate && bun run build

Migration Sync Issues

If you get "dev mode" warnings when running migrations:

# Mark existing migrations as already run
psql "$DATABASE_URL" -c "
INSERT INTO payload_migrations (name, batch, created_at, updated_at)
SELECT * FROM (VALUES
  ('20250101_000000_migration_name', 1, NOW(), NOW())
) AS v(name, batch, created_at, updated_at)
WHERE NOT EXISTS (
  SELECT 1 FROM payload_migrations WHERE name = v.name
);
"

Project Maintenance

Dependency Updates

# Check for outdated packages
bun outdated

# Update specific packages
bun update package-name

# Update all packages
bun update

Type Generation

After modifying collections or globals:

bun run generate:types

Database Connection

Payload uses connection pooling. Common connection strings:

• DATABASE_URI - Primary connection (often pooled)
• POSTGRES_URL_NON_POOLING - Direct connection for migrations

Troubleshooting

Migration timeout: Use non-pooled connection string

# Use POSTGRES_URL_NON_POOLING for migrations
DATABASE_URL=$(grep POSTGRES_URL_NON_POOLING .env.local | cut -d'"' -f2)

Drizzle schema prompts: Answer 'n' to avoid conflicts with migrations

Type errors after updates: Run bun run generate:types

Additional Resources

• references/lexical-format.md - Complete Lexical node type reference
• references/rest-api.md - Full REST API documentation
• references/database-security.md - RLS and security best practices
• scripts/md_to_lexical.py - Markdown to Lexical converter
• scripts/create-post.ts - Example local API script
• Payload Docs: https://payloadcms.com/docs