@dotdo/postgres 0.1.0

package/src/extensions/pgmq-lite.ts

@@ -0,0 +1,770 @@
+/**
+ * PGMQ-Lite: Pure SQL Message Queue for PGLite
+ *
+ * A lightweight message queue implementation that works with single-connection
+ * PGLite instances. Unlike full PGMQ which requires PostgreSQL extensions,
+ * this implementation uses pure SQL and works entirely within PGLite.
+ *
+ * Features:
+ * - Message queues with visibility timeout
+ * - Transactional outbox pattern support
+ * - Dead letter queue support
+ * - Message archival
+ * - Atomic read/delete operations
+ *
+ * @example
+ * ```typescript
+ * import { PGMQLite } from '@dotdo/postgres/extensions'
+ *
+ * // Initialize the queue system
+ * await db.exec(PGMQLite.createSchemaSQL())
+ *
+ * // Create a queue
+ * await db.exec(PGMQLite.createQueueSQL('my_queue'))
+ *
+ * // Send a message
+ * await db.exec(PGMQLite.sendSQL('my_queue', { task: 'process', data: 123 }))
+ *
+ * // Read messages (with 30 second visibility timeout)
+ * const result = await db.query(PGMQLite.readSQL('my_queue', 30, 10))
+ *
+ * // Delete processed message
+ * await db.exec(PGMQLite.deleteSQL('my_queue', msgId))
+ * ```
+ *
+ * @module extensions/pgmq-lite
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Message queue message structure
+ */
+export interface QueueMessage<T = unknown> {
+  /** Unique message ID */
+  msg_id: bigint
+  /** Number of times message has been read */
+  read_ct: number
+  /** When the message was enqueued */
+  enqueued_at: Date
+  /** When the message becomes visible again (null if visible) */
+  vt: Date | null
+  /** The message payload */
+  message: T
+}
+
+/**
+ * Queue metadata
+ */
+export interface QueueMetadata {
+  /** Queue name */
+  queue_name: string
+  /** Whether the queue is paused */
+  is_paused: boolean
+  /** Creation timestamp */
+  created_at: Date
+}
+
+/**
+ * Options for creating a queue
+ */
+export interface CreateQueueOptions {
+  /** Enable dead letter queue */
+  enableDLQ?: boolean
+  /** Max delivery attempts before moving to DLQ (default: 5) */
+  maxDeliveryAttempts?: number
+}
+
+/**
+ * Options for reading messages
+ */
+export interface ReadOptions {
+  /** Visibility timeout in seconds (default: 30) */
+  visibilityTimeout?: number
+  /** Maximum number of messages to read (default: 1) */
+  limit?: number
+}
+
+/**
+ * Options for the transactional outbox
+ */
+export interface OutboxOptions {
+  /** Queue to route messages to */
+  targetQueue: string
+  /** Optional routing key for message filtering */
+  routingKey?: string
+}
+
+// ============================================================================
+// SQL Generation Utilities
+// ============================================================================
+
+/**
+ * Escape a string value for SQL (basic escaping)
+ */
+function escapeSQL(value: string): string {
+  return value.replace(/'/g, "''")
+}
+
+/**
+ * Serialize a value to JSON string for SQL
+ */
+function toJSONSQL(value: unknown): string {
+  return `'${escapeSQL(JSON.stringify(value))}'::jsonb`
+}
+
+// ============================================================================
+// PGMQ-Lite Implementation
+// ============================================================================
+
+/**
+ * PGMQ-Lite: Pure SQL Message Queue for PGLite
+ *
+ * Provides SQL generation for message queue operations that work
+ * entirely within PGLite without requiring external extensions.
+ */
+export const PGMQLite = {
+  name: 'pgmq_lite' as const,
+  displayName: 'PGMQ-Lite' as const,
+  description: 'Lightweight message queue for PGLite using pure SQL',
+
+  // ==========================================================================
+  // Schema Management
+  // ==========================================================================
+
+  /**
+   * Generate SQL to create the pgmq_lite schema and metadata tables
+   *
+   * @returns SQL string to create the schema
+   */
+  createSchemaSQL(): string {
+    return `
+-- PGMQ-Lite Schema
+-- Lightweight message queue for PGLite
+
+-- Create schema if not exists
+CREATE SCHEMA IF NOT EXISTS pgmq_lite;
+
+-- Queue metadata table
+CREATE TABLE IF NOT EXISTS pgmq_lite.meta (
+  queue_name TEXT PRIMARY KEY,
+  is_paused BOOLEAN DEFAULT FALSE,
+  is_unlogged BOOLEAN DEFAULT FALSE,
+  max_delivery_attempts INTEGER DEFAULT 5,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Archive table for processed messages
+CREATE TABLE IF NOT EXISTS pgmq_lite.archive (
+  msg_id BIGINT,
+  queue_name TEXT NOT NULL,
+  read_ct INTEGER DEFAULT 0,
+  enqueued_at TIMESTAMPTZ DEFAULT NOW(),
+  archived_at TIMESTAMPTZ DEFAULT NOW(),
+  message JSONB NOT NULL,
+  PRIMARY KEY (queue_name, msg_id)
+);
+
+-- Dead letter queue table
+CREATE TABLE IF NOT EXISTS pgmq_lite.dlq (
+  msg_id BIGINT,
+  queue_name TEXT NOT NULL,
+  read_ct INTEGER DEFAULT 0,
+  enqueued_at TIMESTAMPTZ DEFAULT NOW(),
+  moved_at TIMESTAMPTZ DEFAULT NOW(),
+  message JSONB NOT NULL,
+  error_reason TEXT,
+  PRIMARY KEY (queue_name, msg_id)
+);
+
+-- Transactional outbox table
+CREATE TABLE IF NOT EXISTS pgmq_lite.outbox (
+  id BIGSERIAL PRIMARY KEY,
+  target_queue TEXT NOT NULL,
+  routing_key TEXT,
+  message JSONB NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  processed_at TIMESTAMPTZ,
+  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'completed', 'failed'))
+);
+
+-- Index for outbox processing
+CREATE INDEX IF NOT EXISTS pgmq_lite_outbox_status_idx ON pgmq_lite.outbox (status, created_at) WHERE status = 'pending';
+`.trim()
+  },
+
+  /**
+   * Generate SQL to drop the pgmq_lite schema and all queues
+   *
+   * @returns SQL string to drop everything
+   */
+  dropSchemaSQL(): string {
+    return `DROP SCHEMA IF EXISTS pgmq_lite CASCADE;`
+  },
+
+  // ==========================================================================
+  // Queue Management
+  // ==========================================================================
+
+  /**
+   * Generate SQL to create a new message queue
+   *
+   * @param queueName - Name of the queue to create
+   * @param options - Queue creation options
+   * @returns SQL string to create the queue
+   */
+  createQueueSQL(queueName: string, options: CreateQueueOptions = {}): string {
+    const { enableDLQ = false, maxDeliveryAttempts = 5 } = options
+    const escapedName = escapeSQL(queueName)
+
+    return `
+-- Create queue: ${escapedName}
+CREATE TABLE IF NOT EXISTS pgmq_lite.q_${escapedName} (
+  msg_id BIGSERIAL PRIMARY KEY,
+  read_ct INTEGER DEFAULT 0,
+  enqueued_at TIMESTAMPTZ DEFAULT NOW(),
+  vt TIMESTAMPTZ DEFAULT NOW(),
+  message JSONB NOT NULL
+);
+
+-- Create index for visibility timeout
+CREATE INDEX IF NOT EXISTS pgmq_lite_q_${escapedName}_vt_idx
+  ON pgmq_lite.q_${escapedName} (vt ASC)
+  WHERE vt <= NOW();
+
+-- Register queue in metadata
+INSERT INTO pgmq_lite.meta (queue_name, max_delivery_attempts)
+VALUES ('${escapedName}', ${maxDeliveryAttempts})
+ON CONFLICT (queue_name) DO NOTHING;
+${enableDLQ ? `
+-- Create DLQ for this queue
+CREATE TABLE IF NOT EXISTS pgmq_lite.q_${escapedName}_dlq (
+  msg_id BIGSERIAL PRIMARY KEY,
+  original_msg_id BIGINT,
+  read_ct INTEGER DEFAULT 0,
+  enqueued_at TIMESTAMPTZ DEFAULT NOW(),
+  moved_at TIMESTAMPTZ DEFAULT NOW(),
+  message JSONB NOT NULL,
+  error_reason TEXT
+);
+` : ''}
+`.trim()
+  },
+
+  /**
+   * Generate SQL to drop a queue
+   *
+   * @param queueName - Name of the queue to drop
+   * @returns SQL string to drop the queue
+   */
+  dropQueueSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+    return `
+DROP TABLE IF EXISTS pgmq_lite.q_${escapedName};
+DROP TABLE IF EXISTS pgmq_lite.q_${escapedName}_dlq;
+DELETE FROM pgmq_lite.meta WHERE queue_name = '${escapedName}';
+DELETE FROM pgmq_lite.archive WHERE queue_name = '${escapedName}';
+DELETE FROM pgmq_lite.dlq WHERE queue_name = '${escapedName}';
+`.trim()
+  },
+
+  /**
+   * Generate SQL to list all queues
+   *
+   * @returns SQL string to list queues
+   */
+  listQueuesSQL(): string {
+    return `SELECT queue_name, is_paused, created_at FROM pgmq_lite.meta ORDER BY created_at;`
+  },
+
+  /**
+   * Generate SQL to get queue depth (number of messages)
+   *
+   * @param queueName - Name of the queue
+   * @returns SQL string to get queue depth
+   */
+  queueDepthSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+    return `SELECT COUNT(*) as depth FROM pgmq_lite.q_${escapedName} WHERE vt <= NOW();`
+  },
+
+  /**
+   * Generate SQL to pause a queue
+   *
+   * @param queueName - Name of the queue
+   * @returns SQL string to pause the queue
+   */
+  pauseQueueSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+    return `UPDATE pgmq_lite.meta SET is_paused = TRUE WHERE queue_name = '${escapedName}';`
+  },
+
+  /**
+   * Generate SQL to resume a queue
+   *
+   * @param queueName - Name of the queue
+   * @returns SQL string to resume the queue
+   */
+  resumeQueueSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+    return `UPDATE pgmq_lite.meta SET is_paused = FALSE WHERE queue_name = '${escapedName}';`
+  },
+
+  // ==========================================================================
+  // Message Operations
+  // ==========================================================================
+
+  /**
+   * Generate SQL to send a message to a queue
+   *
+   * @param queueName - Name of the queue
+   * @param message - Message payload (will be JSON serialized)
+   * @param delay - Optional delay in seconds before message becomes visible
+   * @returns SQL string to send the message
+   */
+  sendSQL(queueName: string, message: unknown, delay: number = 0): string {
+    const escapedName = escapeSQL(queueName)
+    const vtClause = delay > 0 ? `NOW() + INTERVAL '${delay} seconds'` : 'NOW()'
+
+    return `
+INSERT INTO pgmq_lite.q_${escapedName} (message, vt)
+VALUES (${toJSONSQL(message)}, ${vtClause})
+RETURNING msg_id, read_ct, enqueued_at, vt, message;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to send multiple messages to a queue
+   *
+   * @param queueName - Name of the queue
+   * @param messages - Array of message payloads
+   * @param delay - Optional delay in seconds
+   * @returns SQL string to send the messages
+   */
+  sendBatchSQL(queueName: string, messages: unknown[], delay: number = 0): string {
+    const escapedName = escapeSQL(queueName)
+    const vtClause = delay > 0 ? `NOW() + INTERVAL '${delay} seconds'` : 'NOW()'
+
+    const values = messages.map((msg) => `(${toJSONSQL(msg)}, ${vtClause})`).join(',\n  ')
+
+    return `
+INSERT INTO pgmq_lite.q_${escapedName} (message, vt)
+VALUES
+  ${values}
+RETURNING msg_id, read_ct, enqueued_at, vt, message;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to read messages from a queue (with visibility timeout)
+   *
+   * Messages become invisible to other readers for the duration of the
+   * visibility timeout. If not deleted/archived, they become visible again.
+   *
+   * @param queueName - Name of the queue
+   * @param visibilityTimeout - Seconds before message becomes visible again (default: 30)
+   * @param limit - Maximum number of messages to read (default: 1)
+   * @returns SQL string to read messages
+   */
+  readSQL(queueName: string, visibilityTimeout: number = 30, limit: number = 1): string {
+    const escapedName = escapeSQL(queueName)
+
+    return `
+WITH readable AS (
+  SELECT msg_id
+  FROM pgmq_lite.q_${escapedName}
+  WHERE vt <= NOW()
+  ORDER BY msg_id ASC
+  LIMIT ${limit}
+  FOR UPDATE SKIP LOCKED
+)
+UPDATE pgmq_lite.q_${escapedName} q
+SET
+  vt = NOW() + INTERVAL '${visibilityTimeout} seconds',
+  read_ct = q.read_ct + 1
+FROM readable r
+WHERE q.msg_id = r.msg_id
+RETURNING q.msg_id, q.read_ct, q.enqueued_at, q.vt, q.message;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to read a single message and delete it atomically (pop)
+   *
+   * @param queueName - Name of the queue
+   * @returns SQL string to pop a message
+   */
+  popSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+
+    return `
+WITH popped AS (
+  DELETE FROM pgmq_lite.q_${escapedName}
+  WHERE msg_id = (
+    SELECT msg_id
+    FROM pgmq_lite.q_${escapedName}
+    WHERE vt <= NOW()
+    ORDER BY msg_id ASC
+    LIMIT 1
+    FOR UPDATE SKIP LOCKED
+  )
+  RETURNING msg_id, read_ct, enqueued_at, vt, message
+)
+SELECT * FROM popped;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to delete a message from a queue
+   *
+   * @param queueName - Name of the queue
+   * @param msgId - Message ID to delete
+   * @returns SQL string to delete the message
+   */
+  deleteSQL(queueName: string, msgId: bigint | number | string): string {
+    const escapedName = escapeSQL(queueName)
+    return `DELETE FROM pgmq_lite.q_${escapedName} WHERE msg_id = ${msgId} RETURNING msg_id;`
+  },
+
+  /**
+   * Generate SQL to delete multiple messages from a queue
+   *
+   * @param queueName - Name of the queue
+   * @param msgIds - Array of message IDs to delete
+   * @returns SQL string to delete the messages
+   */
+  deleteBatchSQL(queueName: string, msgIds: (bigint | number | string)[]): string {
+    const escapedName = escapeSQL(queueName)
+    const ids = msgIds.join(', ')
+    return `DELETE FROM pgmq_lite.q_${escapedName} WHERE msg_id IN (${ids}) RETURNING msg_id;`
+  },
+
+  /**
+   * Generate SQL to archive a message (move to archive table)
+   *
+   * @param queueName - Name of the queue
+   * @param msgId - Message ID to archive
+   * @returns SQL string to archive the message
+   */
+  archiveSQL(queueName: string, msgId: bigint | number | string): string {
+    const escapedName = escapeSQL(queueName)
+
+    return `
+WITH archived AS (
+  DELETE FROM pgmq_lite.q_${escapedName}
+  WHERE msg_id = ${msgId}
+  RETURNING msg_id, read_ct, enqueued_at, message
+)
+INSERT INTO pgmq_lite.archive (msg_id, queue_name, read_ct, enqueued_at, message)
+SELECT msg_id, '${escapedName}', read_ct, enqueued_at, message
+FROM archived
+RETURNING msg_id;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to change message visibility timeout
+   *
+   * @param queueName - Name of the queue
+   * @param msgId - Message ID
+   * @param visibilityTimeout - New visibility timeout in seconds
+   * @returns SQL string to change visibility
+   */
+  setVisibilityTimeoutSQL(
+    queueName: string,
+    msgId: bigint | number | string,
+    visibilityTimeout: number
+  ): string {
+    const escapedName = escapeSQL(queueName)
+    return `
+UPDATE pgmq_lite.q_${escapedName}
+SET vt = NOW() + INTERVAL '${visibilityTimeout} seconds'
+WHERE msg_id = ${msgId}
+RETURNING msg_id, vt;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to release a message back to the queue (make visible immediately)
+   *
+   * @param queueName - Name of the queue
+   * @param msgId - Message ID
+   * @returns SQL string to release the message
+   */
+  releaseSQL(queueName: string, msgId: bigint | number | string): string {
+    const escapedName = escapeSQL(queueName)
+    return `
+UPDATE pgmq_lite.q_${escapedName}
+SET vt = NOW()
+WHERE msg_id = ${msgId}
+RETURNING msg_id, vt;
+`.trim()
+  },
+
+  // ==========================================================================
+  // Dead Letter Queue Operations
+  // ==========================================================================
+
+  /**
+   * Generate SQL to move a message to the dead letter queue
+   *
+   * @param queueName - Name of the source queue
+   * @param msgId - Message ID to move
+   * @param errorReason - Optional reason for moving to DLQ
+   * @returns SQL string to move message to DLQ
+   */
+  moveToDLQSQL(
+    queueName: string,
+    msgId: bigint | number | string,
+    errorReason?: string
+  ): string {
+    const escapedName = escapeSQL(queueName)
+    const reasonValue = errorReason ? `'${escapeSQL(errorReason)}'` : 'NULL'
+
+    return `
+WITH moved AS (
+  DELETE FROM pgmq_lite.q_${escapedName}
+  WHERE msg_id = ${msgId}
+  RETURNING msg_id, read_ct, enqueued_at, message
+)
+INSERT INTO pgmq_lite.dlq (msg_id, queue_name, read_ct, enqueued_at, message, error_reason)
+SELECT msg_id, '${escapedName}', read_ct, enqueued_at, message, ${reasonValue}
+FROM moved
+RETURNING msg_id;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to read messages from the dead letter queue
+   *
+   * @param queueName - Name of the original queue (or null for all)
+   * @param limit - Maximum number of messages to read
+   * @returns SQL string to read DLQ messages
+   */
+  readDLQSQL(queueName?: string, limit: number = 10): string {
+    if (queueName) {
+      const escapedName = escapeSQL(queueName)
+      return `
+SELECT msg_id, queue_name, read_ct, enqueued_at, moved_at, message, error_reason
+FROM pgmq_lite.dlq
+WHERE queue_name = '${escapedName}'
+ORDER BY moved_at DESC
+LIMIT ${limit};
+`.trim()
+    }
+    return `
+SELECT msg_id, queue_name, read_ct, enqueued_at, moved_at, message, error_reason
+FROM pgmq_lite.dlq
+ORDER BY moved_at DESC
+LIMIT ${limit};
+`.trim()
+  },
+
+  /**
+   * Generate SQL to requeue a message from DLQ back to the original queue
+   *
+   * @param queueName - Name of the queue
+   * @param msgId - Message ID in DLQ
+   * @returns SQL string to requeue the message
+   */
+  requeueFromDLQSQL(queueName: string, msgId: bigint | number | string): string {
+    const escapedName = escapeSQL(queueName)
+
+    return `
+WITH requeued AS (
+  DELETE FROM pgmq_lite.dlq
+  WHERE msg_id = ${msgId} AND queue_name = '${escapedName}'
+  RETURNING message
+)
+INSERT INTO pgmq_lite.q_${escapedName} (message, vt)
+SELECT message, NOW()
+FROM requeued
+RETURNING msg_id, read_ct, enqueued_at, vt, message;
+`.trim()
+  },
+
+  // ==========================================================================
+  // Transactional Outbox Pattern
+  // ==========================================================================
+
+  /**
+   * Generate SQL to add a message to the transactional outbox
+   *
+   * Use this within the same transaction as your business logic to ensure
+   * messages are only sent if the transaction commits.
+   *
+   * @param targetQueue - Queue to eventually send the message to
+   * @param message - Message payload
+   * @param routingKey - Optional routing key for filtering
+   * @returns SQL string to add to outbox
+   */
+  outboxAddSQL(targetQueue: string, message: unknown, routingKey?: string): string {
+    const escapedQueue = escapeSQL(targetQueue)
+    const routingKeyValue = routingKey ? `'${escapeSQL(routingKey)}'` : 'NULL'
+
+    return `
+INSERT INTO pgmq_lite.outbox (target_queue, routing_key, message)
+VALUES ('${escapedQueue}', ${routingKeyValue}, ${toJSONSQL(message)})
+RETURNING id, target_queue, routing_key, message, created_at, status;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to process pending outbox messages
+   *
+   * This should be called periodically by a background worker to move
+   * messages from the outbox to their target queues.
+   *
+   * @param limit - Maximum number of messages to process
+   * @returns SQL string to process outbox
+   */
+  outboxProcessSQL(limit: number = 100): string {
+    return `
+WITH pending AS (
+  SELECT id, target_queue, message
+  FROM pgmq_lite.outbox
+  WHERE status = 'pending'
+  ORDER BY created_at ASC
+  LIMIT ${limit}
+  FOR UPDATE SKIP LOCKED
+),
+updated AS (
+  UPDATE pgmq_lite.outbox o
+  SET status = 'processing'
+  FROM pending p
+  WHERE o.id = p.id
+)
+SELECT id, target_queue, message FROM pending;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to mark outbox messages as completed
+   *
+   * @param ids - Array of outbox message IDs
+   * @returns SQL string to mark as completed
+   */
+  outboxCompleteSQL(ids: (bigint | number | string)[]): string {
+    const idList = ids.join(', ')
+    return `
+UPDATE pgmq_lite.outbox
+SET status = 'completed', processed_at = NOW()
+WHERE id IN (${idList})
+RETURNING id;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to mark outbox messages as failed
+   *
+   * @param ids - Array of outbox message IDs
+   * @returns SQL string to mark as failed
+   */
+  outboxFailSQL(ids: (bigint | number | string)[]): string {
+    const idList = ids.join(', ')
+    return `
+UPDATE pgmq_lite.outbox
+SET status = 'failed'
+WHERE id IN (${idList})
+RETURNING id;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to retry failed outbox messages
+   *
+   * @returns SQL string to retry failed messages
+   */
+  outboxRetryFailedSQL(): string {
+    return `
+UPDATE pgmq_lite.outbox
+SET status = 'pending', processed_at = NULL
+WHERE status = 'failed'
+RETURNING id;
+`.trim()
+  },
+
+  /**
+   * Generate SQL to clean up completed outbox messages
+   *
+   * @param olderThanHours - Remove messages older than this many hours
+   * @returns SQL string to clean up outbox
+   */
+  outboxCleanupSQL(olderThanHours: number = 24): string {
+    return `
+DELETE FROM pgmq_lite.outbox
+WHERE status = 'completed'
+  AND processed_at < NOW() - INTERVAL '${olderThanHours} hours'
+RETURNING id;
+`.trim()
+  },
+
+  // ==========================================================================
+  // Maintenance Operations
+  // ==========================================================================
+
+  /**
+   * Generate SQL to purge all messages from a queue
+   *
+   * @param queueName - Name of the queue
+   * @returns SQL string to purge the queue
+   */
+  purgeQueueSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+    return `DELETE FROM pgmq_lite.q_${escapedName} RETURNING msg_id;`
+  },
+
+  /**
+   * Generate SQL to get queue statistics
+   *
+   * @param queueName - Name of the queue
+   * @returns SQL string to get queue stats
+   */
+  queueStatsSQL(queueName: string): string {
+    const escapedName = escapeSQL(queueName)
+
+    return `
+SELECT
+  '${escapedName}' as queue_name,
+  COUNT(*) as total_messages,
+  COUNT(*) FILTER (WHERE vt <= NOW()) as visible_messages,
+  COUNT(*) FILTER (WHERE vt > NOW()) as invisible_messages,
+  MIN(enqueued_at) as oldest_message_at,
+  MAX(enqueued_at) as newest_message_at,
+  AVG(read_ct)::NUMERIC(10,2) as avg_read_count
+FROM pgmq_lite.q_${escapedName};
+`.trim()
+  },
+
+  /**
+   * Generate SQL to clean up old archived messages
+   *
+   * @param queueName - Name of the queue (or null for all)
+   * @param olderThanDays - Remove messages older than this many days
+   * @returns SQL string to clean up archive
+   */
+  cleanupArchiveSQL(queueName?: string, olderThanDays: number = 30): string {
+    if (queueName) {
+      const escapedName = escapeSQL(queueName)
+      return `
+DELETE FROM pgmq_lite.archive
+WHERE queue_name = '${escapedName}'
+  AND archived_at < NOW() - INTERVAL '${olderThanDays} days'
+RETURNING msg_id;
+`.trim()
+    }
+    return `
+DELETE FROM pgmq_lite.archive
+WHERE archived_at < NOW() - INTERVAL '${olderThanDays} days'
+RETURNING msg_id, queue_name;
+`.trim()
+  },
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default PGMQLite