Was macht Neon Postgres?
Die Datenbank ist opt-in (AGENTS.md §0.5): Verwende sie nur, wenn die App Daten benötigt, die eine Browser-Sitzung überdauern oder geräteübergreifend geteilt werden. Andernfalls versende keine Migrationen, importiere kein @/lib/db und behalte den Zustand in localStorage/zustand.
Diese Vorlage enthält eine vorgefertigte, zweigleisige Datenbankintegration:
- Konfiguriert (Umgebungsvariable gesetzt, z. B. bereitgestellt): Echte Neon Postgres.
- Nicht konfiguriert (Sandbox-Live-Vorschau): Die Datenbank fällt auf ein lokales PGLite (eingebettetes WASM Postgres) zurück, sodass die Vorschau immer rendert. Entwickle gegen den
@/lib/db-Helfer; beide Modi arbeiten mit derselben API.
Pakete sind vorinstalliert — npm install sie nicht: pg (node-postgres, der normale Postgres-Treiber) und @electric-sql/pglite (lokaler DB-Fallback).
Für Benutzerkonten, Anmeldung und Lesen des aktuellen Benutzers siehe das separate auth-Skill – dieses Skill ist nur die Datenbank.
Datenbank einschalten
Setze deploy.database in .grok/app-env.json auf true:
{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
Das sagt der Plattform, dass sie Neon für die bereitgestellte App bereitstellen soll; lass es auf false und die Bereitstellung bekommt keine DATABASE_URL, sodass die App stillschweigend auf einem flüchtigen PGLite läuft, das seine Zeilen verliert. Das Ausliefern von migrations/*.sql oder einer Anmeldung stellt unabhängig davon eine bereit – dieses Flag ist für eine App, die @/lib/db abfragt, ohne eines von beidem zu haben. Es ist kein VITE_-Schlüssel und erreicht nie den Browser.
Umgebungsvariablen — keine .env-Datei erstellen
Erstelle niemals eine .env / .env.local / .env.example für die Datenbank. In der Sandbox-Live-Vorschau lasse DATABASE_URL ungesetzt – @/lib/db verwendet automatisch die eingebettete PGLite. Wenn die App bereitgestellt wird, injiziert die Plattform DATABASE_URL (Neon); du stellst sie nicht selbst bereit oder schreibst sie.
| Var | Wo | Zweck |
|---|---|---|
DATABASE_URL | Server | Neon-Verbindungszeichenfolge bei Bereitstellung (optional – PGLite-Fallback, wenn nicht gesetzt) |
Hartcodiere sie niemals; setze niemals Nicht-VITE_-Variablen dem Client aus.
Datenbank (nur Server)
@/lib/db exportiert getSql() und dbSource: einen normalen Postgres-Treiber (node-postgres, pg) gegen DATABASE_URL oder einen lokalen PGLite-Fallback, wenn nicht gesetzt. In beiden Fällen dieselbe API – ein getaggtes Template (und .query()), das zu rows[] auflöst. Rufe NUR innerhalb eines createServerFn-Handlers / Server-Loaders auf, niemals in einer Client-Komponente. Definiere das Schema in migrations/, nicht inline.
import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";
export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
const sql = await getSql();
// Typisiere die Zeilenform – der Rückgabewert einer Server-Funktion muss nachweislich serialisierbar sein.
return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
// oder: return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});
Benutzerspezifische Daten (nur wenn die App eine Anmeldung hat). Ein normaler Treiber hat vollen DB-Zugriff. Daher begrenze jede Abfrage serverseitig auf den authentifizierten Benutzer – vertraue niemals einer vom Client gesendeten ID. Verwende die vorgefertigte authMiddleware, um eine verifizierte context.userId zu erhalten, und filtere dann danach. Das vollständige Muster (Middleware, Aufruf vom Client-Code, Fail-Closed-Semantik) ist im auth-Skill:
import { authMiddleware } from "@/lib/auth/middleware";
export const listTodos = createServerFn({ method: "GET" })
.middleware([authMiddleware])
.handler(async ({ context }) => {
const sql = await getSql();
return sql<{ id: number; title: string }>`select id, title from todos where user_id = ${context.userId} order by id desc`;
});
// Mutationen müssen ebenfalls Schreibvorgänge begrenzen: `... where id = ${id} and user_id = ${context.userId}`
Ohne Anmeldung (Standard) verwende NICHT authMiddleware / requireUserId.
Der Entwickler-Benutzer, auf den sie zurückfallen, ist ein reiner Vorschau-Komfort. VITE_AUTH_ENABLED einer bereitgestellten App wird von der Plattform gesetzt, nicht von diesem Workspace (heute setzt der Deployer sie immer auf "true"). Daher weisen beide, wenn sie bereitgestellt sind, jeden Besucher ab – und eine App ohne Authentifizierung liefert keine Anmelderoute, um sich davon zu erholen. Eine reine Datenbank-App behält ihre Zeilen ohne Besitzer: keine user_id-Spalte oder eine einzige literale Konstante. Füge die Middleware als Teil des Einschaltens der Anmeldung hinzu (die Upgrade-Schritte des auth-Skills) und passe dann den Gültigkeitsbereich dieser Zeilen an oder verwerfe sie.
Unbesitzerte Zeilen sind über deine öffentlichen Server-Funktionen weltweit les- und schreibbar: Persistiere in diesem Modus niemals persönliche oder sensible Daten (Namen, E-Mails, freier Text über eine Person) und verzichte auf zerstörerische Massenmutationen (alle löschen, alle überschreiben) – wenn die App sie benötigt, schlage stattdessen eine Anmeldung vor.
Migrationen
migrations/*.sql sind die einzige Schema-Quelle. Sie werden bei Bereitstellung auf Neon (npm run build führt db:migrate gegen DATABASE_URL aus, sodass Vercel mit dem fertigen Schema ausgeliefert wird) und auf der PGLite-Vorschau automatisch beim Start angewendet, sodass Entwicklung und Produktion übereinstimmen.
Keiner der Anwender durchsucht Unterverzeichnisse, daher wird das Better-Auth-Schema in migrations/auth/0001_auth.sql nicht angewendet, es sei denn, die App schaltet die Anmeldung ein und kopiert es nach oben (bearbeite es nicht – siehe das auth-Skill). Platziere das Schema deiner App in NEUEN, nummerierten Dateien, beginnend mit 0002:
-- migrations/0002_schema.sql — Beispiel für eine Todo-App; verwende die Tabellen DEINER App
create table if not exists todos (
id serial primary key,
user_id text not null,
title text not null,
done boolean not null default false,
created_at timestamptz not null default now()
);
create index if not exists todos_user_id_idx on todos (user_id);
Bearbeite niemals eine angewendete Datei – sie wird namentlich in _migrations verfolgt und nicht erneut ausgeführt (füge stattdessen eine neue Datei hinzu; neue Dateien werden bei der nächsten Anfrage auf die laufende Vorschau angewendet). Bevorzuge idempotente Anweisungen (… if not exists). Tabellen mit benutzerspezifischen Daten sollten eine user_id text not null-Spalte enthalten (TEXT, nicht UUID – die Vorschau-Entwickler-Benutzer-ID ist der String 'dev-user').
Vorschau ↔ Produktionsparität
getSql() normalisiert Ergebnistypen, sodass beide Backends identische, JSON-sichere Formen zurückgeben: bigint/count(*) → number, date → 'YYYY-MM-DD'-String, interval → Text, numeric → String. Verbleibende Unterschiede, die zu beachten sind:
bigintjenseits von 2^53 verliert Genauigkeit als Zahl – wandle mit::textum, falls du jemals große Ganzzahlen benötigst (Zeilenanzahlen sind in Ordnung).- Vorschau-DB ist im Arbeitsspeicher: wird bei Neustart des Entwicklungsservers gelöscht, Einzelverbindung (keine Sperrkonflikte oder gleichzeitige Schreibkonflikte) und lädt keine Erweiterungen – führe kein
create extensionaus; bleibe bei Kern-Postgres. - Neons gepoolter Endpunkt behält keinen Sitzungszustand – verlasse dich nicht auf
SET,LISTEN/NOTIFYoder Sitzungsberatungssperren. - Halte
user_id-Spalten alstext– die Vorschau verwendet'dev-user', die Produktion Better Auths Text-IDs; eineuuid-Spalte bricht Vorschau-Einfügungen. - Bereitgestellte Neon-Abfragen durchlaufen das Netzwerk (und können kalt neu starten) – vermeide N+1-Abfragemuster, die sich gegen die prozessinterne Vorschau-DB kostenlos anfühlen.