From pg-boss to PlanLlama: Your Upgrade Path

Understanding how PlanLlama extends pg-boss and how to migrate your existing queues and jobs

Built on the Foundation You Trust

PlanLlama is built on pg-boss, the battle-tested PostgreSQL-based job queue that developers love for its simplicity and reliability. We didn't reinvent the wheel—we supercharged it.

If you're currently using pg-boss, you already understand the core concepts: queues, jobs, workers, and the power of using Postgres as your job infrastructure. PlanLlama takes that foundation and extends it with cloud-native orchestration, real-time monitoring, and cross-platform coordination.

Key principle: PlanLlama maintains compatibility with pg-boss schemas and patterns, so migration is smooth and non-disruptive.

What PlanLlama Adds to pg-boss

Cloud-Native Architecture

No need to manage your own Postgres instance or worker infrastructure. We handle scaling, high availability, and operational complexity.

Cross-Platform Orchestration

Connect workers from different environments, clouds, or applications. Coordinate jobs across AWS, GCP, on-premise, or hybrid setups—all from one control plane.

Real-Time Monitoring & Dashboards

WebSocket-based job lifecycle events, visual dashboards, and alerting so you know exactly what's happening with your jobs in real-time.

Multi-Language Support

Native SDKs for JavaScript/TypeScript, Python, Ruby, and Go. Write workers in the language that makes sense for each service.

Workflow Orchestration

Define complex multi-step workflows with dependency resolution—go beyond simple job queuing to coordinate entire business processes.

Team Collaboration

Project-based multi-tenancy, team member management, and secure token access controls built for modern development teams.

Cron & Scheduling

Built-in cron expression support with timezone awareness, making recurring jobs simple and reliable.

Migration Strategy

Moving from pg-boss to PlanLlama is designed to be gradual and low-risk. You don't need to migrate everything at once.

Step 1: Start with New Jobs

The easiest way to adopt PlanLlama is to start using it for new job queues while keeping your existing pg-boss infrastructure running.

Install the SDK:

npm install planllama

Publish your first job:

import { PlanLlama } from 'planllama';

const client = new PlanLlama(process.env.PLANLLAMA_TOKEN);
await client.start();

// Publish a job
const jobId = await client.publish('new-feature-queue', {
  data: 'your payload'
});

Step 2: Migrate Workers Incrementally

Convert your existing pg-boss workers to PlanLlama workers. The API is intentionally similar:

pg-boss worker:

boss.work('email-queue', 
  async job => {
    await sendEmail(job.data);
  }
);

PlanLlama worker:

client.work('email-queue',
  async job => {
    await sendEmail(job.data);
    return { sent: true };
  }
);

Step 3: Leverage New Capabilities

Once your jobs are running on PlanLlama, take advantage of features that weren't available in pg-boss:

Add real-time event listeners for completed, failed, or retrying events
Create multi-step workflows with dependency resolution
Monitor job execution from the PlanLlama dashboard
Deploy workers across multiple environments or clouds
Set up team access and collaboration

Conceptual Mapping: pg-boss → PlanLlama

pg-boss Concept	PlanLlama Equivalent	Notes
boss.send()	client.publish()	Same job publishing semantics
boss.work()	client.work()	Worker registration with similar API
boss.schedule()	client.schedule()	Cron-based recurring jobs
Queue name	Queue name	Same concept, namespace per project
Job options	JobOptions	Extended with more granular controls
Local Postgres	Managed cloud	No infrastructure to manage
Single instance	Multi-environment	Workers can connect from anywhere

Frequently Asked Questions

Do I need to change my database schema?

No. PlanLlama is a fully managed service—you don't manage the database yourself. We handle all the underlying pg-boss schema and operations in the cloud.

Can I run pg-boss and PlanLlama side-by-side?

Absolutely. Many teams start by running new queues on PlanLlama while keeping existing pg-boss jobs running. This allows for a gradual, risk-free migration.

What about vendor lock-in?

PlanLlama is built on open-source pg-boss principles and uses standard Postgres under the hood. If you ever need to self-host, the patterns and schemas are familiar. We believe in giving you the flexibility to choose what's best for your team.

How does pricing compare to self-hosting pg-boss?

Our free tier is generous for small projects and development. For production workloads, you save on infrastructure costs (Postgres hosting, monitoring, backups) and operational overhead. Check our pricing page for details.

Can I connect workers from multiple clouds or on-premise?

Yes! This is one of PlanLlama's key features. Workers can run anywhere—AWS, GCP, Azure, on-premise data centers, or even your local development machine. As long as they can reach the PlanLlama API, they can process jobs.

Ready to Upgrade from pg-boss?

Start with our free tier and experience the power of pg-boss in the cloud.

Start Free Trial View Full Documentation