Configura il database

Cos'è una migrazione

Un database appena creato è vuoto — non ha tabelle per utenti, workspace o record. Una migrazione è una modifica del database salvata e ordinata: un file che dice crea questa tabella, aggiungi quella colonna. Il kit include le sue migrazioni già pronte; il comando db:migrate applica tutte quelle in sospeso al database indicato da DATABASE_URL.

Eseguirla non è una configurazione facoltativa — è ciò che trasforma un Postgres vuoto nel database della tua app. Login, workspace, record di fatturazione e dati salvati vivono tutti in quelle tabelle.

Ecco perché gli account si rompono se il login avviene prima delle migrazioni: l'app scrive il nuovo utente in una tabella che non esiste ancora, lasciando un account creato a metà. Esegui sempre prima le migrazioni — i passaggi di configurazione qui sotto fanno esattamente quello prima del primo login reale.

Installazione e configurazione

Prima di qualsiasi passaggio, leggere Prima di iniziare e Nozioni di base sui terminali. Queste istruzioni presuppongono che tu abbia aperto l'intero supastack monorepo in VS Code; la sua radice package.json contrassegna la radice del repository. Nei comandi pnpm, un pacchetto dell'area di lavoro è un'app o una cartella di codice condiviso; nel prodotto, uno spazio di lavoro è il contenitore dei dati di un team e il limite di sicurezza. corepack pnpm --filter ... seleziona un pacchetto dal monorepo mentre i comandi vengono eseguiti dalla sua radice. Se hai aperto solo una cartella mobile o desktop sincronizzata, non contiene il backend Web, la configurazione di Docker o gli script root: esegui il backend da questo monorepo o da un server ospitato raggiungibile e utilizza gli script della cartella della piattaforma. Una variabile di ambiente è un'impostazione denominata memorizzata in un file .env locale o nel dashboard dell'hosting; riavvia l'app pertinente dopo averla modificata e mantieni i segreti del server fuori dai valori NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. Installa e avvia Docker Desktop.

2. Copia .env.example in .env nella root per gli strumenti di migrazione e in apps/web/.env.local per Next.js (PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp .env.esempio apps/web/.env.local). Mantieni DATABASE_URL uguale in entrambi i file; l'esempio corrisponde già al database Docker locale.

3. Dal repository root esegui docker compose up -d postgres e docker compose ps; attendere fino a quando Postgres non verrà riportato integro.

4. Eseguire corepack pnpm --filter @supastack/db db:migrate dalla root per applicare le migrazioni già fornite con il kit. Solo dopo aver modificato packages/db/src/schema.ts, esegui db:generate, ispeziona lo SQL generato, quindi esegui db:migrate. Previsto: il contenitore Postgres locale è integro e l'app Web utilizza il relativo database migrato. Non indirizzare mai questa prima esecuzione alla produzione.

Configura DATABASE_URL per il database Postgres target nell'ambiente server. Usa un database usa-e-getta separato per l'accettazione di integrazione. Non puntare mai le migrazioni di test verso un database di produzione.

Il workspace database esporta le definizioni dello schema e gli helper di persistenza. Rivedi packages/db/src/schema.ts e la directory delle migrazioni prima di introdurre una tabella o una colonna.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction

Comandi da copiare

Segui i commenti per vedere in quale cartella viene eseguito un comando. Se due terminali sono etichettati, apri due finestre di terminale e mantieni il primo comando in esecuzione mentre usi il secondo.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Flusso di implementazione

Genera una migrazione dopo aver modificato lo schema, ispeziona l'SQL generato e committalo con il cambio di schema. Pianifica come i record esistenti ricevono i valori prima di aggiungere una colonna obbligatoria.

Includi workspaceId in ogni record posseduto dall'utente e porta quel confine attraverso letture e scritture. Usa uno storico immutabile modello-prezzo per la contabilità AI invece di riscrivere i prezzi referenziati da record di utilizzo esistenti.

Verifica e risoluzione dei problemi

Se Docker dice che non può connettersi al suo motore, avvia Docker Desktop e attendi che finisca il caricamento. Se postgres non è integro, esegui docker compose logs postgres dalla root e correggi l'errore prima della migrazione. Se Web dice che manca DATABASE_URL, controlla apps/web/.env.local; se db:migrate non riesce a connettersi, controlla il root .env. Se cambi database, aggiorna entrambi i file. Leggere la prima istruzione di migrazione non riuscita prima di riprovare; non ripeterlo mai contro la produzione.

Applica le migrazioni su un database isolato ed esegui su di esso i test condizionati dal database. Credenziali mancanti devono produrre un cancello esplicitamente saltato, non un'affermazione di persistenza riuscita. Se una migrazione fallisce, ispeziona quale istruzione è fallita e lo schema corrente prima di riprovare.