Database instellen

Wat een migratie is

Een nieuwe database is leeg — er zijn geen tabellen voor gebruikers, werkruimtes of records. Een migratie is een opgeslagen, geordende databasewijziging: een bestand dat zegt maak deze tabel aan, voeg die kolom toe. De kit levert zijn migraties kant-en-klaar mee; het commando db:migrate past elke nog niet uitgevoerde migratie toe op de database die DATABASE_URL noemt.

Het uitvoeren ervan is geen optionele installatie — het is wat een lege Postgres verandert in de database van uw app. Aanmelden, werkruimtes, factureringsrecords en opgeslagen data leven allemaal in die tabellen.

Daarom breken accounts als aanmelden vóór de migraties gebeurt: de app schrijft de nieuwe gebruiker naar een tabel die nog niet bestaat, waardoor een half aangemaakt account ontstaat. Migreer altijd eerst — de onderstaande installatiestappen doen precies dat vóór de eerste echte aanmelding.

Setup en configuratie

Lees vóór elke stap Voordat u begint en Basisbeginselen van de terminal. Deze instructies gaan ervan uit dat je de volledige supastack monorepo in VS Code hebt geopend; zijn root package.json markeert de root van de repository. In pnpm-opdrachten is een werkruimtepakket een app of map met gedeelde code; in het product is een werkruimte de gegevenscontainer en de beveiligingsgrens van een team. corepack pnpm --filter ... selecteert één pakket uit de monorepo terwijl opdrachten vanuit de root worden uitgevoerd. Als u alleen een gesynchroniseerde mobiele map of desktopmap hebt geopend, bevat deze niet de webbackend, Docker-installatie of rootscripts: voer de backend uit vanaf deze monorepo of een bereikbare gehoste server en gebruik de eigen scripts van de platformmap. Een omgevingsvariabele is een benoemde instelling die is opgeslagen in een lokaal .env-bestand of op uw hostingdashboard; start de relevante app opnieuw nadat u deze hebt gewijzigd en houd servergeheimen buiten de NEXT_PUBLIC_- en EXPO_PUBLIC_-waarden.

1. Installeer en start Docker Desktop.

2. Kopieer .env.example naar .env in de root voor migratietools en naar apps/web/.env.local voor 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.voorbeeld apps/web/.env.local). Houd DATABASE_URL hetzelfde in beide bestanden; het voorbeeld komt al overeen met de lokale Docker-database.

3. Voer vanuit de root van de repository docker compose up -d postgres en docker compose ps uit; wacht tot postgres gezond meldt.

4. Voer corepack pnpm --filter @supastack/db db:migrate uit vanuit de root om de migraties toe te passen die al bij de kit zijn geleverd. Pas na het bewerken van packages/db/src/schema.ts voert u db:generate uit, inspecteert u de gegenereerde SQL en voert u vervolgens db:migrate uit. Verwacht: de lokale Postgres-container is in orde en de webapp gebruikt de gemigreerde database. Richt deze eerste run nooit op productie.

Configureer DATABASE_URL voor de bedoelde Postgres-database in de serveromgeving. Gebruik een aparte wegwerp-database voor integratieacceptatie. Richt testmigraties nooit op een productiedatabase.

De databaseworkspace exporteert schemadefinities en persistentiehelpers. Review packages/db/src/schema.ts en de migratiemap voordat je een tabel of kolom introduceert.

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

Commando's om te kopiëren

Volg de opmerkingen om te zien in welke map een opdracht wordt uitgevoerd. Als twee terminals zijn gelabeld, opent u twee terminalvensters en laat u de eerste opdracht draaien terwijl u de tweede gebruikt.

# 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

Implementatieworkflow

Genereer een migratie na het bewerken van het schema, inspecteer de gegenereerde SQL en commit hem met de schemawijziging. Plan hoe bestaande records waarden ontvangen voordat je een verplichte kolom toevoegt.

Neem workspaceId op in elk record van een gebruiker en draag die scope mee in reads en writes. Gebruik immutable model-prijshistorie voor AI-accounting in plaats van prijzen te herschrijven die door bestaande usagerecords worden gebruikt.

Verificatie en probleemoplossing

Als Docker zegt dat het geen verbinding kan maken met de engine, start dan Docker Desktop en wacht tot het laden is voltooid. Als postgres niet in orde is, voert u docker compose logs postgres uit vanuit de root en herstelt u de fout voordat u migreert. Als Web zegt dat DATABASE_URL ontbreekt, controleer dan apps/web/.env.local; als db:migrate geen verbinding kan maken, controleer dan de root .env. Als u van database verandert, update dan beide bestanden. Lees de eerste mislukte migratieverklaring voordat u het opnieuw probeert; herhaal het nooit tegen de productie.

Pas migraties toe op een geïsoleerde database en draai database-gated tests daar. Ontbrekende credentials moeten een expliciete skipped gate opleveren, geen bewering dat persistentie slaagde. Als een migratie faalt, inspecteer welk statement faalde en het huidige schema voordat je opnieuw probeert.