# pgflow

import { Card, CardGrid, LinkCard, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import TestimonialCarousel from '../../components/TestimonialCarousel.astro';
import CodeOverlay from '../../components/CodeOverlay.astro';

<div class="comparison-container">

<div class="comparison-column">

### 🛠️ Without pgflow

<div class="left-content-wrapper">

<div class="scrollable-content">

<CodeOverlay />

<button class="reset-overlay-button" aria-label="Show overlay again">
  ↻ Show overlay
</button>

<button class="scroll-top-button" aria-label="Scroll to top">
  ↑
</button>

<div class="scrollable-inner">

**1. Set up queues**
```sql
SELECT pgmq.create('scrape_queue');
SELECT pgmq.create('summarize_queue');
SELECT pgmq.create('extract_keywords_queue');
```

**2. Scrape processor Edge Function**
```typescript
import { serve } from 'std/http/server.ts';
import { scrapeWebsite } from './scraper.ts';

serve(async () => {
  const supabase = createClient(/*...*/);

  // Read one message from scrape queue
  const { data: messages } = await supabase.rpc(
    'pgmq_read',
    {
      queue_name: 'scrape_queue',
      vt: 30, // 30 second visibility timeout
      qty: 1
    }
  );

  if (!messages?.[0]) {
    return new Response('No messages', { status: 200 });
  }

  const { msg_id, message } = messages[0];
  const { url } = message;

  try {
    // Scrape the website
    const content = await scrapeWebsite(url);

    // Store in articles table (state tracking)
    const { data: article } = await supabase
      .from('articles')
      .insert({ url, content })
      .select()
      .single();

    // Send to BOTH parallel queues
    await supabase.rpc('pgmq_send', {
      queue_name: 'summarize_queue',
      msg: { url }
    });

    await supabase.rpc('pgmq_send', {
      queue_name: 'extract_keywords_queue',
      msg: { url }
    });

    // Delete from scrape queue
    await supabase.rpc('pgmq_delete', {
      queue_name: 'scrape_queue',
      msg_id
    });

  } catch (error) {
    console.error('Scrape failed:', error);
    // Message becomes visible again after timeout
  }

  return new Response('OK');
});
```

**3. Summarize processor Edge Function**

```typescript
import { serve } from 'std/http/server.ts';
import { summarizeContent } from './summarizer.ts';

serve(async () => {
  const supabase = createClient(/*...*/);

  // Read one message from summarize queue
  const { data: messages } = await supabase.rpc(
    'pgmq_read',
    {
      queue_name: 'summarize_queue',
      vt: 30,
      qty: 1
    }
  );

  if (!messages?.[0]) {
    return new Response('No messages', { status: 200 });
  }

  const { msg_id, message } = messages[0];
  const { url } = message;

  try {
    // Fetch article from state table
    const { data: article } = await supabase
      .from('articles')
      .select('content')
      .eq('url', url)
      .single();

    // Summarize content
    const summary = await summarizeContent(article.content);

    // Update state table with summary
    await supabase
      .from('articles')
      .update({ summary })
      .eq('url', url);

    // Delete from summarize queue
    await supabase.rpc('pgmq_delete', {
      queue_name: 'summarize_queue',
      msg_id
    });

  } catch (error) {
    console.error('Summarize failed:', error);
    // Message becomes visible again after timeout
  }

  return new Response('OK');
});
```

**4. Extract keywords processor Edge Function**

```typescript
import { serve } from 'std/http/server.ts';
import { extractKeywords } from './extractor.ts';

serve(async () => {
  const supabase = createClient(/*...*/);

  // Read one message from extract queue
  const { data: messages } = await supabase.rpc(
    'pgmq_read',
    {
      queue_name: 'extract_keywords_queue',
      vt: 30,
      qty: 1
    }
  );

  if (!messages?.[0]) {
    return new Response('No messages', { status: 200 });
  }

  const { msg_id, message } = messages[0];
  const { url } = message;

  try {
    // Fetch article from state table
    const { data: article } = await supabase
      .from('articles')
      .select('content')
      .eq('url', url)
      .single();

    // Extract keywords
    const keywords = await extractKeywords(article.content);

    // Update state table with keywords
    await supabase
      .from('articles')
      .update({ keywords })
      .eq('url', url);

    // Delete from extract queue
    await supabase.rpc('pgmq_delete', {
      queue_name: 'extract_keywords_queue',
      msg_id
    });

  } catch (error) {
    console.error('Extract failed:', error);
    // Message becomes visible again after timeout
  }

  return new Response('OK');
});
```

**5. Publish articles cron job**

```sql
-- Poll for completed articles and publish them
SELECT cron.schedule(
  'publish-articles',
  '*/15 * * * * *',
  $$
    UPDATE articles
    SET published = true
    WHERE published = false
      AND summary IS NOT NULL
      AND keywords IS NOT NULL
  $$
);
```

**6. Schedule queue processors**
```sql
-- Scrape processor runs every 15 seconds
SELECT cron.schedule(
  'scrape-processor',
  '*/15 * * * * *',
  $$SELECT net.http_post(
    url := 'https://your-project.supabase.co/functions/v1/scrape-processor'
  )$$
);

-- Summarize processor runs every 15 seconds
SELECT cron.schedule(
  'summarize-processor',
  '*/15 * * * * *',
  $$SELECT net.http_post(
    url := 'https://your-project.supabase.co/functions/v1/summarize-processor'
  )$$
);

-- Extract keywords processor runs every 15 seconds
SELECT cron.schedule(
  'extract-keywords-processor',
  '*/15 * * * * *',
  $$SELECT net.http_post(
    url := 'https://your-project.supabase.co/functions/v1/extract-keywords-processor'
  )$$
);
```

**7. Trigger workflow**

```typescript
// Add URL to scrape queue to start the workflow
await supabase.rpc('pgmq_send', {
  queue_name: 'scrape_queue',
  msg: { url: 'https://example.com' }
});
```

</div>

</div>

</div>

<div class="disclaimer-left disclaimer-mobile">
  Based on Supabase's recommended pattern. <a href="https://supabase.com/blog/processing-large-jobs-with-edge-functions" target="_blank" rel="noopener">Read the full guide →</a>
</div>

</div>

<div class="comparison-column">

### ⚡ With pgflow

<div class="right-content-wrapper">

```typescript
import { Flow } from 'npm:@pgflow/dsl';

new Flow<{ url: string }>({ slug: 'analyzeArticle' })
  .step({ slug: 'fetchArticle' },
    (input) => scrapeWebsite(input.run.url)
  )
  .step({ slug: 'summarize', dependsOn: ['fetchArticle'] },
    (input) => summarizeContent(input.fetchArticle)
  )
  .step({ slug: 'extractKeywords', dependsOn: ['fetchArticle'] },
    (input) => extractKeywords(input.fetchArticle)
  )
  .step({ slug: 'publish', dependsOn: ['summarize', 'extractKeywords'] },
    (input) => publishArticle({
      url: input.run.url,
      content: input.fetchArticle,
      summary: input.summarize,
      keywords: input.extractKeywords
    })
  );
```

</div>

</div>

</div>

<div class="disclaimer-left disclaimer-desktop">
  Based on Supabase's recommended pattern. <a href="https://supabase.com/blog/processing-large-jobs-with-edge-functions" target="_blank" rel="noopener">Read the full guide →</a>
</div>

<div class="comparison-note-wrapper">
  <Aside type="tip" title="You write the business logic. pgflow handles everything else.">
    Queue management, state tracking, dependency resolution, task coordination, and retries - **pgflow is the orchestration engine.**

    [How pgflow works →](/concepts/how-pgflow-works/)

    [Complete setup guide →](/get-started/installation/)
  </Aside>
</div>

<div class="quickstart-section">

```bash
npx pgflow@latest install
```

<div class="quickstart-caption">Sets up pgflow in your Supabase project. <a href="/get-started/installation/">View full setup guide →</a></div>

</div>

## Why pgflow

<CardGrid>
  <Card title="✨ No manual wiring">
    Skip the tedious pg_cron → pgmq → Edge Function setup. No manual queue wiring, no archive code, no state table management. pgflow handles all the plumbing - you just define your workflow. [Learn more →](/get-started/installation/)
  </Card>

  <Card title="📦 Runs entirely in Supabase">
    Everything in your existing Supabase project. No Bull, no Redis, no Temporal, no Railway. No external services, no vendor dashboards, no additional infrastructure to manage. [Learn more →](/concepts/how-pgflow-works/)
  </Card>

  <Card title="👁️ Full observability in SQL">
    All workflow state lives in Postgres tables. Query execution history, inspect step outputs, and debug failures with standard SQL. No hidden state, no external dashboards. [Learn more →](/deploy/monitor-execution/)
  </Card>

  <Card title="🔄 Automatic retries">
    Built-in retry logic with exponential backoff for flaky AI APIs. When OpenAI times out or rate-limits, only that step retries - your workflow continues. Configure max attempts and delays per step, no retry code needed. [Learn more →](/build/retrying-steps/)
  </Card>

  <Card title="⚡ Parallel array processing">
    Process arrays in parallel with independent retries per item. Batch 100 embeddings - if 3 fail, only those 3 retry while others continue. Perfect for AI workloads with unreliable APIs. [Learn more →](/build/process-arrays-in-parallel/)
  </Card>

  <Card title="🔌 Trigger from anywhere">
    Start workflows from database triggers, scheduled pg_cron jobs, browser clients, or RPC calls. Ultimate flexibility in how you start your workflows. [Learn more →](/build/starting-flows/)
  </Card>
</CardGrid>

## What Developers Are Saying

*Real comments after seeing early demos*

<TestimonialCarousel />

<div style="text-align: center; margin: 4rem 0 5rem;">

## Ready to get started?

</div>

<div style="max-width: 450px; margin: 0 auto;" class="cta-card">
  <LinkCard
    title="🚀 Install pgflow"
    href="/get-started/installation/"
    description="Five minutes to your first workflow.
Zero boilerplate required."
  />
</div>

<style>{`
  .cta-card {
    transform: scale(1.35);
    margin-top: 3rem;
  }

  @media (max-width: 768px) {
    .cta-card {
      transform: scale(1);
      max-width: 100%;
      margin-top: 2rem;
      padding: 0 1rem;
    }
  }

  .cta-card .sl-link-card {
    background: linear-gradient(135deg, color-mix(in srgb, var(--sl-color-accent-high) 6.4%, transparent) 0%, color-mix(in srgb, var(--sl-color-accent-high) 2.4%, transparent) 100%);
    box-shadow: 0 0 40px color-mix(in srgb, var(--sl-color-accent-high) 5%, transparent), 0 4px 20px color-mix(in srgb, var(--sl-color-accent-high) 3%, transparent);
    border: 1px solid color-mix(in srgb, var(--sl-color-accent-high) 16%, transparent);
    transition: all 0.3s ease;
    position: relative;
    overflow: hidden;
  }

  .cta-card .sl-link-card p {
    white-space: pre-line;
  }

  .cta-card .sl-link-card::before {
    content: '';
    position: absolute;
    top: 1px;
    left: -100%;
    right: 1px;
    bottom: 1px;
    width: calc(100% - 2px);
    height: calc(100% - 2px);
    background: linear-gradient(90deg,
      transparent 0%,
      rgba(255, 255, 255, 0.004) 48%,
      rgba(255, 255, 255, 0.008) 50%,
      rgba(255, 255, 255, 0.004) 52%,
      transparent 100%
    );
    transition: left 0.25s ease;
    z-index: 1;
  }

  .cta-card .sl-link-card:hover {
    background: linear-gradient(135deg, color-mix(in srgb, var(--sl-color-accent-high) 7.5%, transparent) 0%, color-mix(in srgb, var(--sl-color-accent-high) 3%, transparent) 100%);
    box-shadow: 0 0 60px color-mix(in srgb, var(--sl-color-accent-high) 8%, transparent), 0 4px 30px color-mix(in srgb, var(--sl-color-accent-high) 5%, transparent);
  }

  .cta-card .sl-link-card:hover::before {
    left: 100%;
    transition: left 0.5s ease;
  }

  .quickstart-section {
    margin-top: 6rem;
    margin-bottom: 3rem;
  }

  .comparison-highlights {
    font-size: 1.05rem;
    font-weight: 700;
    line-height: 1.8;
    margin: 1rem 0;
  }

  /* Steps disclaimer */
  .steps-disclaimer {
    font-size: 0.9rem;
    color: var(--sl-color-gray-3);
    margin-top: 1rem;
    font-style: italic;
  }

  /* Content wrappers */
  .left-content-wrapper {
    display: flex;
    flex-direction: column;
    min-height: 0;
    block-size: 100%; /* Create definite height chain from stretched grid row */
  }

  .right-content-wrapper {
    display: flex;
    flex-direction: column;
    flex: 1;
    min-height: 0;
    overflow: hidden;
  }

  /* Comparison disclaimers - left-aligned note about source pattern */
  .comparison-disclaimers {
    margin-top: 0.5rem;
    font-size: 0.9rem;
    color: var(--sl-color-gray-3);
    font-style: italic;
  }

  .disclaimer-left {
    padding: 0;
    margin: 0.5rem 0 0 0;
    line-height: 1.5;
    font-size: 0.9rem;
    color: var(--sl-color-gray-3);
    font-style: italic;
    flex-shrink: 0;
  }

  .disclaimer-left a {
    color: var(--sl-color-text-accent);
    text-decoration: none;
    border-bottom: 1px solid color-mix(in srgb, var(--sl-color-accent-high) 30%, transparent);
    transition: border-color 0.2s ease;
  }

  .disclaimer-left a:hover {
    border-bottom-color: var(--sl-color-accent-high);
  }

  /* Hide mobile disclaimer on desktop */
  .disclaimer-mobile {
    display: none;
  }

  /* Show desktop disclaimer on desktop */
  .disclaimer-desktop {
    display: block;
    margin-top: 0.5rem;
  }

  /* Comparison note wrapper - center and constrain width */
  .comparison-note-wrapper {
    max-width: 70%;
    margin: 3.5rem auto 0 auto;
  }

  /* Custom styling for the comparison aside */
  .comparison-note-wrapper .starlight-aside {
    background: linear-gradient(
      135deg,
      color-mix(in srgb, var(--sl-color-accent-high) 4%, transparent) 0%,
      color-mix(in srgb, var(--sl-color-accent-high) 1%, transparent) 100%
    );
    border-left: 3px solid color-mix(in srgb, var(--sl-color-accent-high) 50%, transparent);
    padding: 1.25rem 1.5rem;
  }

  .comparison-note-wrapper .starlight-aside__title {
    color: var(--sl-color-white);
    font-weight: 600;
    margin-bottom: 0.75rem;
  }

  .comparison-note-wrapper .starlight-aside__content {
    font-size: 0.95rem;
    line-height: 1.7;
    color: var(--sl-color-gray-2);
  }

  .comparison-note-wrapper .starlight-aside__content > p:first-child {
    margin-top: 0;
  }

  .comparison-note-wrapper .starlight-aside__content > p:last-child {
    margin-bottom: 0;
  }

  .comparison-note-wrapper .starlight-aside__content ul {
    margin: 0.75rem 0;
    padding-left: 1.5rem;
  }

  .comparison-note-wrapper .starlight-aside__content li {
    margin: 0.5rem 0;
  }

  .comparison-note-wrapper .starlight-aside__content strong {
    color: var(--sl-color-white);
    font-weight: 600;
  }

  .comparison-note-wrapper .starlight-aside__content a {
    color: var(--sl-color-text-accent);
    text-decoration: none;
    border-bottom: 1px solid color-mix(in srgb, var(--sl-color-accent-high) 30%, transparent);
    transition: border-color 0.2s ease;
    font-weight: 500;
  }

  .comparison-note-wrapper .starlight-aside__content a:hover {
    border-bottom-color: var(--sl-color-accent-high);
  }

  @media (max-width: 1024px) {
    .comparison-note-wrapper {
      max-width: 85%;
    }
  }

  @media (max-width: 768px) {
    .comparison-note-wrapper {
      max-width: 100%;
    }

    .comparison-note-wrapper .starlight-aside {
      padding: 1rem 1.25rem;
    }

    .comparison-note-wrapper .starlight-aside__content {
      font-size: 0.9rem;
    }

    /* Hide icon and reduce title font size on mobile */
    .comparison-note-wrapper .starlight-aside__icon {
      display: none;
    }

    .comparison-note-wrapper .starlight-aside__title {
      font-size: 0.9rem;
      line-height: 1.4;
    }
  }

  .comparison-container {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 2rem;
    margin: 2rem 0 0 0; /* Remove bottom margin */
    align-items: stretch; /* Make both columns same height */
  }

  .comparison-column {
    min-width: 0;
    display: flex;
    flex-direction: column;
    min-height: 0; /* CRITICAL: allows grid child to shrink */
    padding: 0;
    margin: 0;
    position: relative;
  }

  /* KEY: Prevent left column from contributing its content size to grid row height */
  .comparison-column:first-child {
    contain: size; /* Exclude from intrinsic track sizing - row height comes from RIGHT column */
    overflow: hidden; /* Allow internal scrolling */
  }

  @media (max-width: 1024px) {
    .comparison-container {
      grid-template-columns: 1fr;
      gap: 3rem;
    }

    .comparison-column pre {
      max-width: 100%;
    }

    /* Remove contain:size on mobile to make left column visible */
    .comparison-column:first-child {
      contain: none !important;
      overflow: visible !important;
    }

    /* Remove height constraints on mobile */
    .left-content-wrapper {
      block-size: auto !important;
      min-height: auto !important;
    }

    .right-content-wrapper {
      min-height: auto !important;
    }

    /* Set fixed height for scrollable containers on mobile to match "with pgflow" height */
    .scrollable-content {
      display: flex !important;
      flex-direction: column !important;
      max-height: 400px !important;
      height: 400px !important;
      overflow: hidden !important;
      border: 1px solid var(--sl-color-gray-5);
      border-radius: 0;
      padding: 0 !important;
    }

    .scrollable-inner {
      overflow-y: auto !important;
      overflow-x: hidden !important;
      flex: 1 !important;
      -webkit-overflow-scrolling: touch;
      padding: 0.5rem !important;
      min-height: 0 !important;
      max-height: none !important;
    }

    /* Remove padding from first element in scrollable inner */
    .scrollable-inner > *:first-child {
      margin-top: 0 !important;
      padding-top: 0 !important;
    }

    /* Keep overlay visible and interactive on mobile */
    .code-overlay {
      display: flex !important;
      top: 2rem !important;
      left: 0 !important;
      right: 0 !important;
      bottom: 0 !important;
      height: auto !important;
      pointer-events: auto !important;
    }

    .code-overlay.hidden {
      pointer-events: none !important;
    }

    .code-overlay .overlay-content {
      padding: 1rem;
      max-width: 100%;
    }

    .code-overlay .overlay-title {
      font-size: 1.5rem;
    }

    .code-overlay .overlay-list {
      font-size: 0.95rem;
      line-height: 2;
      margin-bottom: 1rem;
    }

    .code-overlay .reveal-button {
      font-size: 0.9rem !important;
      padding: 0.7rem 1rem !important;
    }

    /* Keep buttons functional on mobile - initially hidden */
    .reset-overlay-button {
      display: none;
      top: 0.3rem !important;
    }

    .scroll-top-button {
      display: none;
    }

    /* Show reset button after overlay is dismissed on mobile */
    .code-overlay.hidden ~ .reset-overlay-button {
      display: block !important;
    }

    /* Show mobile disclaimer, hide desktop disclaimer */
    .disclaimer-mobile {
      display: block !important;
    }

    .disclaimer-desktop {
      display: none !important;
    }
  }

  .comparison-column > h3 {
    margin-top: 0 !important;
    margin-bottom: 1.5rem;
    font-size: 1.25rem;
    color: var(--sl-color-text-accent);
    padding: 0 0 0.5rem;
    border-bottom: 2px solid var(--sl-color-gray-5);
    flex-shrink: 0;
  }

  .comparison-column .sl-heading-wrapper.level-h3 {
    margin-bottom: 2rem !important;
  }

  .comparison-column > h3 + * p:first-child {
    margin-top: 0 !important;
  }

  .comparison-column > *:nth-child(2) {
    margin-top: 0 !important;
    padding-top: 0 !important;
  }

  .comparison-column h4,
  .comparison-column strong {
    color: var(--sl-color-white);
    font-size: 0.95rem;
  }

  .comparison-column ul {
    font-size: 0.9rem;
    line-height: 1.6;
    margin-top: 0.5rem;
  }

  .comparison-column pre {
    overflow-y: hidden !important;
    overflow-x: hidden !important;
  }

  .comparison-column pre::-webkit-scrollbar {
    display: none;
  }

  .comparison-column pre code {
    overflow: hidden !important;
  }

  /* Mobile responsiveness for code blocks */
  @media (max-width: 768px) {
    /* Smaller font for code blocks on mobile */
    .comparison-column pre {
      font-size: 0.7rem;
    }

    .comparison-column code {
      font-size: 0.7rem;
    }

    /* Allow horizontal scrolling for code that's still too wide */
    .comparison-column pre {
      overflow-x: auto !important;
    }

    .comparison-column pre code {
      overflow-x: auto !important;
    }
  }

  @media (max-width: 480px) {
    /* Even smaller font for very small screens */
    .comparison-column pre {
      font-size: 0.65rem;
    }

    .comparison-column code {
      font-size: 0.65rem;
    }
  }
`}</style>