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.
On this page
How SaleX uses Supabase
| Supabase feature | Used by SaleX? | Notes |
|---|---|---|
| Postgres database | Yes | All data (products, orders, vendors, shipping, settings) lives here, managed by Prisma. |
| Supabase Auth | No | Login uses NextAuth with email + password and bcrypt. Users are rows in the SaleX tables, not in Supabase Auth. |
| Supabase Storage | Not by default | Uploads go to the server's storage/ folder. See Media and Supabase Storage. |
| Realtime, Edge Functions | No | Not required to run SaleX. |
anon or service_role keys. Only the database connection strings are used.1. Create the project
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.
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:
| Purpose | Typical port | Goes in |
|---|---|---|
| Pooled connection (Supavisor, transaction mode) | 6543 | DATABASE_URL — used by the running app |
| Direct connection (or session-mode pooler) | 5432 | DIRECT_URL — used by npm run db:deploy |
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"- Copy the real hostnames from your dashboard. The values above are placeholders and the exact pooler host differs per project.
- The
?pgbouncer=trueflag is needed for Prisma on the transaction pooler (port 6543). - If your password contains special characters (
@ : / ? #), URL-encode them, for example@becomes%40.
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:
- In Supabase → Storage create a public bucket, for example
products. - Upload your images there and copy each file's public URL.
- Paste the URL into the product image field in the admin or vendor panel.
Security notes
- Never expose the database password or connection strings to the browser. They belong only in server-side
.envor your host's secret settings. - SaleX enforces access rules in its own server code, not through Supabase Row Level Security. Do not publish the Supabase API keys as a substitute for access control.
- If your Supabase dashboard shows a warning that tables have RLS disabled, that concerns Supabase's auto-generated REST API. Since SaleX does not use that API, keep it unexposed: in Project Settings → API you can review and restrict the exposed schemas.
- Restrict database access with Network Restrictions where your plan allows, and rotate the database password if it ever leaks (then update both env values and restart).
Backups
- Check your plan's backup policy in Supabase → Database → Backups. Free-tier projects have limited or no restore options, so take your own dumps.
- Manual dump using the direct or session-pooler string:
pg_dump "YOUR_DIRECT_URL" | gzip > salex-$(date +%F).sql.gzAlso back up any uploaded media (the storage/ folder or your Supabase bucket). See Security & Backups.
Common Supabase problems
| Symptom | Likely cause | Fix |
|---|---|---|
db:deploy hangs or times out | Pooled string used for migrations | Put the direct or session-pooler string in DIRECT_URL. |
| Cannot reach host / network unreachable | IPv6-only direct host | Use the session-pooler string for DIRECT_URL. |
| “prepared statement already exists” | Missing pgbouncer=true on the pooled URL | Add ?pgbouncer=true to DATABASE_URL and restart. |
| Authentication failed | Wrong or un-encoded password, wrong user format | Pooler users look like postgres.PROJECT_REF. Reset the password in Project Settings → Database and re-encode it. |
| Sudden connection errors on a quiet store | Free project paused | Restore the project in the dashboard. |
| “too many connections” | Direct URL used by the running app | The app must use the pooled DATABASE_URL. |