Documentation

Supabase Setup

SaleX uses Supabase as a hosted PostgreSQL database. Prisma talks to it directly over a standard Postgres connection. This page shows the exact setup, and what Supabase is not used for.

Supabase is optional. SaleX works with any PostgreSQL database. If you prefer to host the database on your own server, skip this page and follow DigitalOcean VPS Setup → Install PostgreSQL.
On this page

How SaleX uses Supabase

Supabase featureUsed by SaleX?Notes
Postgres databaseYesAll data (products, orders, vendors, shipping, settings) lives here, managed by Prisma.
Supabase AuthNoLogin uses NextAuth with email + password and bcrypt. Users are rows in the SaleX tables, not in Supabase Auth.
Supabase StorageNot by defaultUploads go to the server's storage/ folder. See Media and Supabase Storage.
Realtime, Edge FunctionsNoNot required to run SaleX.
No Supabase API keys needed You do not need the Supabase anon or service_role keys. Only the database connection strings are used.

1. Create the project

  1. Sign in and create a project

    Go to supabase.com, create a new project, pick the region closest to your server, and set a strong database password. Save that password now — you cannot view it later, only reset it.

  2. Wait for provisioning

    It takes a minute or two.

    ✓ Success: the project dashboard opens and shows the project as healthy.

2. Copy the connection strings

In the dashboard click Connect at the top of the project. You need two strings that differ by port and host:

PurposeTypical portGoes in
Pooled connection (Supavisor, transaction mode)6543DATABASE_URL — used by the running app
Direct connection (or session-mode pooler)5432DIRECT_URL — used by npm run db:deploy
IPv6 and the direct string Supabase's direct connection host can be IPv6-only. If db:deploy cannot connect from your computer or VPS, use the session pooler string (port 5432 on the pooler host) for DIRECT_URL instead. Both support migrations. Supabase's dashboard shows which options are available for your project.

3. Fill in .env

DATABASE_URL="postgresql://postgres.PROJECT_REF:YOUR_DB_PASSWORD@aws-0-REGION.pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres.PROJECT_REF:YOUR_DB_PASSWORD@aws-0-REGION.pooler.supabase.com:5432/postgres"
APP_URL="http://localhost:3000"
AUTH_SECRET="generate with: openssl rand -base64 32"

4. Apply migrations and seed

npm install
npm run db:generate
npm run db:deploy
npm run db:seed

✓ Success: in Supabase → Table Editor you see the SaleX tables, and Table Editor → the users table contains your seeded admin.

Run db:seed once. Set SEED_SUPER_ADMIN_EMAIL and a password (or the HASH variant) first — see Environment Configuration.

Media and Supabase Storage

By default SaleX writes uploads to the server's storage/ folder. That works on a VPS with a persistent disk. On serverless hosts (for example Vercel) the disk is temporary and uploads will vanish.

SaleX also accepts external image URLs per product. A no-code workaround for serverless hosting:

  1. In Supabase → Storage create a public bucket, for example products.
  2. Upload your images there and copy each file's public URL.
  3. Paste the URL into the product image field in the admin or vendor panel.
Not automatic This is a manual workflow. Vendors' in-panel uploads still target local disk. Fully automatic Supabase Storage uploads would require a code change to the upload handler, which is not included.

Security notes

Backups

pg_dump "YOUR_DIRECT_URL" | gzip > salex-$(date +%F).sql.gz

Also back up any uploaded media (the storage/ folder or your Supabase bucket). See Security & Backups.

Free projects pause Supabase may pause inactive free-tier projects. A paused database makes the whole store return errors until you restore it from the dashboard. Use a paid plan for a live store.

Common Supabase problems

SymptomLikely causeFix
db:deploy hangs or times outPooled string used for migrationsPut the direct or session-pooler string in DIRECT_URL.
Cannot reach host / network unreachableIPv6-only direct hostUse the session-pooler string for DIRECT_URL.
“prepared statement already exists”Missing pgbouncer=true on the pooled URLAdd ?pgbouncer=true to DATABASE_URL and restart.
Authentication failedWrong or un-encoded password, wrong user formatPooler users look like postgres.PROJECT_REF. Reset the password in Project Settings → Database and re-encode it.
Sudden connection errors on a quiet storeFree project pausedRestore the project in the dashboard.
“too many connections”Direct URL used by the running appThe app must use the pooled DATABASE_URL.