Postgres / Prisma Backend

The commerce layer ships with a server-side Prisma/PostgreSQL adapter that is a drop-in replacement for the default Firebase backend: same CommerceServices interface, same lifecycle events, same read shapes. It lets you run the entire store — catalog, carts, quote requests, orders, discounts — on any Postgres database you control (local, Supabase, Neon, RDS, a container).

• Adapter: src/lib/commerce/server/prisma.ts → export const prismaCommerce
• Schema: prisma/schema.prisma
• CLI config: prisma.config.ts

Prisma Postgres / Accelerate is NOT used

Prisma 7 specifics

This project ships Prisma 7, which changes two things the adapter relies on:

1. No datasource.url in schema.prisma. Prisma 7 removed that property. The connection string the CLI needs lives in prisma.config.ts instead (datasource.url = env("DATABASE_URL")), and the runtime client gets it through a driver adapter.
2. The runtime client needs a driver adapter (not a bare URL). This adapter builds a @prisma/adapter-pg client over DATABASE_URL. The @prisma/client, @prisma/adapter-pg, and pg packages ship in the base dependencies — no extra install is needed; you only generate the client once a DATABASE_URL is set.

import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: env("DATABASE_URL"),
  },
});

Setup

# Local Postgres
DATABASE_URL="postgresql://user:password@localhost:5432/ecommerce"

# Supabase (Project Settings → Database). The pooled "Transaction"
# string works well for serverless:
DATABASE_URL="postgresql://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres"

npm run prisma:generate   # == npx prisma generate

npm run prisma:push   # == npx prisma db push

npx prisma migrate dev --name init

insert into admins (uid) values ('<firebase-auth-uid>')
on conflict (uid) do nothing;

NEXT_PUBLIC_COMMERCE_BACKEND=postgres   # browser: route commerce calls to the RPC layer
COMMERCE_BACKEND=postgres               # server: run the Prisma adapter

Bundling: serverComponentsExternalPackages

The optional SQL-backend packages are kept out of the bundle and require()d at runtime inside the adapter. next.config.mjs lists them as external so a default (Firebase) build succeeds even without a generated client, and so the Postgres adapter can load the generated client at runtime:

experimental: {
  serverComponentsExternalPackages: [
    "@prisma/client",
    "@prisma/adapter-pg",
    "pg",
  ],
},

This pairs with the adapter's lazy client: @prisma/client and @prisma/adapter-pg are loaded via require inside getPrisma() (not a top-level import) so the file type-checks and builds with no generated client. The instance is cached on globalThis so hot reload does not open a new pool per edit, and the first actual operation — not import — throws if DATABASE_URL is unset.

Deploying on Postgres

A fresh CI environment has no generated client, so the Prisma client must be generated during the build. Set the build command (or add a postinstall) to run generation first:

npm run prisma:generate && npm run build

The deploy environment must include:

Run npm run prisma:push (or your migration step) against the production database once, out of band, to create the tables.

Data model

The schema (prisma/schema.prisma) mirrors the Firestore layout the Firebase adapter uses, with loose/schemaless documents stored in Json columns so unknown fields round-trip exactly like Firestore documents.

Behavioral notes worth knowing:

• Prefix search uses COLLATE "C". products.search pins its range bounds and ordering to byte-order collation so results match Firestore's code-point ordering regardless of the database's default collation.
• Per-customer quote/order copies are flattened. listForCustomer is a WHERE customer_id = $uid query; the copy identity is synthesized on read (id === quoteNumber/orderNumber, mainQuoteId === <main record id> on quotes).
• carts.listen polls (immediate fetch + 5s interval) — realtime push is Firestore-only for now. The callback contract is otherwise identical.
• PageCursor is a base64url-encoded keyset token (JSON-serializable so it survives HTTP round-trips), not a Firestore snapshot.

Using a different database

The schema uses no Postgres-only features (no scalar lists, enums, or @db.* native types), so the same adapter code runs on MySQL or SQLite. Change datasource.provider in prisma/schema.prisma, swap the driver-adapter package passed to new PrismaClient({ adapter }) in src/lib/commerce/server/prisma.ts (e.g. @prisma/adapter-mariadb for MySQL, @prisma/adapter-better-sqlite3 for SQLite), give products.search an engine-appropriate binary collation (MySQL utf8mb4_bin, SQLite COLLATE BINARY), then regenerate and migrate.