Database & Storage
How SaleX stores data: a PostgreSQL database managed by Prisma, plus an uploads folder for media. This page covers creating the database, running migrations, seeding, and storage behavior.
On this page
How SaleX uses the database
prisma/schema.prisma— the complete data model (products, orders, vendors, shipping zones, and ~100 more tables).prisma/migrations/— 70+ ordered SQL files that build the schema step by step. Never edit these by hand.src/generated/— auto-generated database client code. Never edit; regenerate withnpm run db:generate.
Creating a database
SaleX needs one empty PostgreSQL database. It creates the tables itself.
# Local PostgreSQL — Windows (enter your postgres password when asked)
psql -U postgres -c "CREATE DATABASE salex;"
# Local PostgreSQL — macOS/Linux (Homebrew)
createdb salexOr create it in your provider's dashboard (Supabase: a project gives you a database automatically; copy its connection string).
Migrations explained
| Command | When to use | What it does |
|---|---|---|
npm run db:deploy | Local setup & production | Applies all pending migration files in order. Safe, repeatable — the usual choice. |
npm run db:migrate | Developers only | Creates new migrations from schema edits. Can reset data. Do not run on production. |
npm run db:validate | Debugging | Checks the schema file is valid without touching the database. |
npm run db:generate | After code updates | Regenerates the TypeScript database client from the schema. |
✓ After npm run db:deploy succeeds, all tables exist. Run it again any time — it skips what is already applied.
db:deploy hangs or times out, 95% of the time DATABASE_URL or DIRECT_URL is wrong. Recheck the password, host, port, and database name. On pooled providers, DIRECT_URL must be the direct connection string.Seeding starter data
npm run db:seedWhat the seed creates:
- The first administrator account — email/password from
SEED_SUPER_ADMIN_EMAIL/SEED_SUPER_ADMIN_PASSWORDin.env(a precomputedSEED_SUPER_ADMIN_PASSWORD_HASHis preferred on real servers). - Platform settings (store name, currency defaults), RBAC roles and permissions
- Demo catalog: vendors, products, categories, banners — so you can see a working storefront immediately
- A default homepage section layout
Two optional extra seeds exist for demo purposes: npm run db:seed:shipping (sample shipping zones/methods/rates — useful to preview the shipping system) and npm run db:seed:classified-images (adds sample photos to demo classified ads). Both are safe to skip and re-runnable.
Self-hosted PostgreSQL on a VPS (no Supabase)
You do not need a hosted database. On an Ubuntu VPS you can install PostgreSQL next to SaleX and connect over localhost:
sudo apt install -y postgresql postgresql-contrib
DB_PASS=$(openssl rand -hex 24) && echo "Save this password: $DB_PASS"
sudo -u postgres psql <<SQL
CREATE USER salex WITH PASSWORD '$DB_PASS';
CREATE DATABASE salex OWNER salex;
SQLThen set the same value in both variables (no pooler, so no ?pgbouncer=true) and run npm run db:deploy:
DATABASE_URL="postgresql://salex:DB_PASSWORD@localhost:5432/salex"
DIRECT_URL="postgresql://salex:DB_PASSWORD@localhost:5432/salex"Using a hosted database (Supabase/Neon)
Create a project
Sign up, create a new project, and wait for it to initialize.
Copy the connection strings
Find “Connection string” in the dashboard. Supabase shows a pooled URI (port 6543) and a direct URI (port 5432). Put the pooled one in
DATABASE_URLand the direct one inDIRECT_URL. Replace the placeholder password with your database password.Apply migrations
Run
npm run db:deployfrom your machine — it connects to the hosted database over the internet.Verify
The provider's table browser shows ~100
saletablesafter seeding.
✓ Success: your local dev server now shows the same data as the hosted database.
File uploads & storage
- Product/category images uploaded through the admin or vendor panels are processed with Sharp and stored in the
storage/folder on the server disk; the database records each file's path. - Uploaded files are served through
/api/media/…with permission checks for private files. - External image URLs are also supported (the demo data uses them), so you can point products at a CDN if you prefer.
storage/ folder. One without the other gives you products with missing images. See Security & Backups.