> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Database e migrazioni

Prepara Postgres ed evolvi lo schema Drizzle con migrazioni committate.

## Installazione e configurazione

Prima di qualsiasi passaggio, leggere [Prima di iniziare](https://supastack.dev/it/docs/web/before-you-start.md) e [Nozioni di base sui terminali](https://supastack.dev/it/docs/web/terminal-basics.md). 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.


Per continuare la configurazione, leggi [Configura i pagamenti](https://supastack.dev/it/docs/web/setup-payments.md).


## Successivo

[Modulo database](https://supastack.dev/it/docs/modules/database.md)