[docs] Improve the setup instructions for @workflow/world-postgres

[karthikscale3]

Improved the setup guide for @workflow/world-postgres with step-by-step instructions:

• Database schema setup using workflow-postgres-setup CLI command (this is part of this PR)
• World initialization in instrumentation.ts
• Next.js configuration with instrumentationHook
• "How it works" section explaining pg-boss, NOTIFY/LISTEN, and architecture

Changes:

• Replaced basic usage instructions with structured component
• Added expected CLI output examples for better UX
• Documented all required and optional configuration options

Verified this setup by creating a project from scratching and setting up using Supabase

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0dc7c76

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

@karthikscale3 is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The workflow-postgres-setup CLI command documented here does not exist in the codebase. Users will receive a "command not found" error when attempting to follow these setup instructions.

View Details

📝 Patch Details

diff --git a/docs/content/docs/deploying/world/postgres-world.mdx b/docs/content/docs/deploying/world/postgres-world.mdx
index 9c7da33..895a88d 100644
--- a/docs/content/docs/deploying/world/postgres-world.mdx
+++ b/docs/content/docs/deploying/world/postgres-world.mdx
@@ -39,10 +39,11 @@ npm install @workflow/world-postgres
 
 ### Set up the database schema
 
-Run the setup script to create the required database tables:
+Run drizzle-kit to create the required database tables:
 
 ```bash
-pnpm exec workflow-postgres-setup
+pnpm drizzle-kit generate
+pnpm drizzle-kit migrate
 ```
 
 This will create the following tables in your PostgreSQL database:
@@ -53,13 +54,7 @@ This will create the following tables in your PostgreSQL database:
 - `workflow_hooks` - Stores workflow hooks
 - `workflow_stream_chunks` - Stores streaming data
 
-You should see output like:
-
-```
-🔧 Setting up database schema...
-📍 Connection: postgres://postgres:****@db.yourcloudprovider.co:5432/postgres
-✅ Database schema created successfully!
-```
+The migrations will set up your database schema with all necessary tables and indexes.
 
 ### Configure environment variables
 

Analysis

Incorrect CLI command documented for postgres-world database setup

What fails: Users following the documentation in docs/content/docs/deploying/world/postgres-world.mdx line 45 are instructed to run pnpm exec workflow-postgres-setup, but this command does not exist in the codebase.

How to reproduce:

cd packages/world-postgres
pnpm exec workflow-postgres-setup

Result: Error message: Command "workflow-postgres-setup" not found

Expected: The documentation should instruct users to use drizzle-kit as specified in the official packages/world-postgres/README.md (lines 98-99):

pnpm drizzle-kit generate
pnpm drizzle-kit migrate

Root cause: The @workflow/world-postgres package does not define a bin field in its package.json and has no CLI tools. The database schema setup is handled by drizzle-kit migrations, not a custom setup command.

Fix: Updated documentation to use the correct drizzle-kit commands that users should actually run to set up the PostgreSQL database schema.

[pranaygp]

@VaguelySerious @Schniz mind taking a look at this? - since you both know the PG world best :)

[Schniz]

we probably need to implement this

[karthikscale3]

I have made a PR for this - #57