@voltade/pg-serverless

A PostgreSQL storage and vector provider for Mastra using the Neon Serverless Driver. This package provides the same functionality as @mastra/pg but is designed for serverless environments like Vercel Edge Functions, Cloudflare Workers, and other edge runtimes.

Features

• Serverless-optimized: Uses the Neon serverless driver which works over HTTP and WebSockets
• Full feature parity: Implements all features from @mastra/pg
• Vector storage: pgvector support for vector similarity search
• Edge-compatible: Works in serverless and edge environments without native dependencies

Installation

pnpm add @voltade/pg-serverless

Usage

PostgresStore (Storage)

import { PostgresStore } from '@voltade/pg-serverless';

const store = new PostgresStore({
  id: 'my-store',
  connectionString: process.env.DATABASE_URL,
});

await store.init();

// Save and retrieve threads
await store.saveThread({ thread: myThread });
const thread = await store.getThreadById({ threadId: 'thread-123' });

// Save and retrieve messages
await store.saveMessages({ messages: myMessages });

PgVector (Vector Storage)

import { PgVector } from '@voltade/pg-serverless';

const vector = new PgVector({
  id: 'my-vector-store',
  connectionString: process.env.DATABASE_URL,
});

// Create an index
await vector.createIndex({
  indexName: 'my_embeddings',
  dimension: 1536,
  metric: 'cosine',
});

// Upsert vectors
await vector.upsert({
  indexName: 'my_embeddings',
  vectors: [[0.1, 0.2, ...]],
  metadata: [{ title: 'My Document' }],
});

// Query vectors
const results = await vector.query({
  indexName: 'my_embeddings',
  queryVector: [0.1, 0.2, ...],
  topK: 10,
});

Configuration

Connection String

const store = new PostgresStore({
  id: 'my-store',
  connectionString: 'postgresql://user:password@host:5432/database',
  ssl: true, // optional
});

Host-based Configuration

const store = new PostgresStore({
  id: 'my-store',
  host: 'localhost',
  port: 5432,
  database: 'mastra',
  user: 'postgres',
  password: 'password',
  ssl: true, // optional
});

Schema Configuration

const store = new PostgresStore({
  id: 'my-store',
  connectionString: process.env.DATABASE_URL,
  schemaName: 'my_schema', // Use a custom schema
});

Differences from @mastra/pg

| Feature | @mastra/pg | @voltade/pg-serverless | |---------|-----------|----------------------| | Driver | pg-promise / pg | @neondatabase/serverless | | Edge Support | ❌ | ✅ | | WebSocket Support | ❌ | ✅ | | HTTP Queries | ❌ | ✅ | | Native Dependencies | Yes | No |

Requirements

• Node.js 18+ (or edge runtime)
• PostgreSQL 14+ with pgvector extension
• Neon database required: The @neondatabase/serverless driver only works with Neon cloud PostgreSQL instances. It cannot connect to local or self-hosted PostgreSQL databases.

Important Notes

Neon Database Requirement

This package uses the @neondatabase/serverless driver which is designed exclusively for Neon cloud PostgreSQL databases. Unlike the standard pg driver, it:

• Connects over HTTP/WebSocket to Neon's infrastructure (port 443)
• Cannot connect to local PostgreSQL instances
• Cannot connect to self-hosted PostgreSQL or other cloud providers (AWS RDS, Azure, etc.)

If you need to connect to a non-Neon PostgreSQL database, use @mastra/pg instead.

Running Tests

Tests require a Neon database connection. Set the NEON_DATABASE_URL environment variable:

NEON_DATABASE_URL=postgresql://user:[email protected]/dbname pnpm test

Tests will be skipped if NEON_DATABASE_URL is not set.

License

Apache-2.0