Documentation

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

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 salex

Or create it in your provider's dashboard (Supabase: a project gives you a database automatically; copy its connection string).

Migrations explained

CommandWhen to useWhat it does
npm run db:deployLocal setup & productionApplies all pending migration files in order. Safe, repeatable — the usual choice.
npm run db:migrateDevelopers onlyCreates new migrations from schema edits. Can reset data. Do not run on production.
npm run db:validateDebuggingChecks the schema file is valid without touching the database.
npm run db:generateAfter code updatesRegenerates 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.

Migration errors = wrong connection string If 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:seed

What the seed creates:

Demo data is safe to delete Once you take over, you can remove demo vendors/products from the admin panel — or keep them for testing. Seeding again does not duplicate your own content.

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;
SQL

Then 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"
Keep port 5432 closed to the internet and schedule your own nightly backups — nobody else is doing it for you. The full guide, including firewall and a ready-made backup script, is in DigitalOcean VPS Setup.

Using a hosted database (Supabase/Neon)

  1. Create a project

    Sign up, create a new project, and wait for it to initialize.

  2. 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_URL and the direct one in DIRECT_URL. Replace the placeholder password with your database password.

  3. Apply migrations

    Run npm run db:deploy from your machine — it connects to the hosted database over the internet.

  4. Verify

    The provider's table browser shows ~100 saletables after seeding.

✓ Success: your local dev server now shows the same data as the hosted database.

File uploads & storage

Back up both A full backup = database dump plus the storage/ folder. One without the other gives you products with missing images. See Security & Backups.