paymentsdb

A drop-in replacement for the Stripe SDK that reads from your local PostgreSQL database instead of hitting the Stripe API. When your backend and database are co-located (same region/network), reads can be up to 100x faster with zero rate limits.

Installation

npm install paymentsdb
# or
bun add paymentsdb

Usage

Simply replace your Stripe import:

- import Stripe from "stripe";
+ import { StripeProxy as Stripe } from "paymentsdb";

That's it. Your existing code works exactly the same:

import { StripeProxy as Stripe } from "paymentsdb";

const stripe = new Stripe("sk_test_...");

// Reads from your database (fast, no API rate limits)
const products = await stripe.products.list();
const customer = await stripe.customers.retrieve("cus_123");

// Writes always go to Stripe API (then sync to your DB via webhooks)
const newProduct = await stripe.products.create({ name: "My Product" });

Configuration

Database Connection

The proxy reads from your database when available. Configure it via:

Environment variable (recommended):

DATABASE_URL=postgres://user:pass@localhost:5432/mydb

Or pass it explicitly:

const stripe = new Stripe("sk_test_...", {
  databaseUrl: "postgres://user:pass@localhost:5432/mydb",
});

Or use a pool config object:

const stripe = new Stripe("sk_test_...", {
  databaseUrl: {
    host: "localhost",
    port: 5432,
    database: "mydb",
    user: "user",
    password: "pass",
  },
});

Custom Schema

By default, tables are expected in the stripe schema. Customize it:

const stripe = new Stripe("sk_test_...", {
  databaseUrl: "postgres://...",
  schema: "my_custom_schema",
});

API Key from Environment

Like the official SDK, you can omit the API key if STRIPE_SECRET_KEY is set:

// Reads STRIPE_SECRET_KEY from environment
const stripe = new Stripe();

How It Works

| Operation | Behavior | | ------------ | --------------------------------------------- | | list() | Reads from database, falls back to Stripe API | | retrieve() | Reads from database, falls back to Stripe API | | create() | Always calls Stripe API | | update() | Always calls Stripe API | | del() | Always calls Stripe API |

When no database is configured, all operations go directly to the Stripe API (identical to the official SDK).

Supported Resources

All standard Stripe resources are supported:

• products
• prices
• customers
• subscriptions
• invoices
• charges
• paymentIntents
• paymentMethods
• setupIntents
• plans
• coupons
• refunds
• disputes

Pass-through resources (no DB caching):

• checkout
• billingPortal
• webhooks
• webhookEndpoints

Additional APIs

// Check if database is connected
if (stripe.hasDatabase) {
  console.log("Reading from local DB");
}

// Access the underlying Stripe instance
const rawStripe = stripe.raw;

// Clean up database connections
await stripe.close();

Database Schema

Your database needs tables matching Stripe's data structure. Visit paymentsdb.com for easy ways to sync your Stripe data to your database.

Expected table structure (in stripe schema by default):

stripe.products
stripe.prices
stripe.customers
stripe.subscriptions
stripe.invoices
stripe.charges
stripe.payment_intents
stripe.payment_methods
stripe.setup_intents
stripe.plans
stripe.coupons
stripe.refunds
stripe.disputes

License

MIT