Neon Postgres
La base de données est optionnelle (AGENTS.md §0.5) : utilisez-la uniquement lorsque l'application a besoin de données qui survivent à une session de navigateur ou qui sont partagées entre appareils. Sinon, n'envoyez pas de migrations, n'importez pas @/lib/db, et conservez l'état dans localStorage / zustand.
Ce modèle fournit une intégration de base de données double mode prête à l'emploi :
- Configuré (variable d'environnement définie, par ex. déployé) : vrai Neon Postgres.
- Non configuré (prévisualisation en direct dans le bac à sable) : la base de données tombe en recours sur un PGLite local (Postgres WASM embarqué), de sorte que la prévisualisation s'affiche toujours. Construisez votre code contre l'assistant
@/lib/db; les deux modes fonctionnent avec la même API.
Les packages sont préinstallés — ne lancez pas npm install : pg (node-postgres, le pilote Postgres standard) et @electric-sql/pglite (recours local de base de données).
Pour les comptes utilisateurs, la connexion et la lecture de l'utilisateur courant, consultez la compétence auth séparée — cette compétence ne concerne que la base de données.
Activer la base de données
Définissez deploy.database sur true dans .grok/app-env.json :
{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
C'est ce qui indique à la plateforme de provisionner Neon pour l'application déployée ; laissez false et le déploiement n'obtiendra pas de DATABASE_URL, l'application s'exécutera donc silencieusement sur un PGLite jetable qui perdra ses lignes. Envoyer des fichiers migrations/*.sql, ou activer la connexion, provisionne une base de données indépendamment de ce drapeau — ce drapeau est destiné aux applications qui interrogent @/lib/db sans l'un ni l'autre. Ce n'est pas une clé VITE_ et n'atteint jamais le navigateur.
Variables d'environnement — ne créez pas de fichier .env
N'écrivez jamais de fichier .env / .env.local / .env.example pour la base de données. Dans la prévisualisation en direct du bac à sable, laissez DATABASE_URL non définie — @/lib/db utilise automatiquement PGLite embarqué. Lorsque l'application est déployée, la plateforme injecte DATABASE_URL (Neon) ; vous ne la provisionnez ni ne l'écrivez vous-même.
| Var | Emplacement | Objectif |
|---|---|---|
DATABASE_URL | serveur | Chaîne de connexion Neon en déploiement (optionnelle — recours PGLite si non définie) |
Ne la codez jamais en dur ; n'exposez jamais de variables non VITE_ au client.
Base de données (serveur uniquement)
@/lib/db exporte getSql() et dbSource : un pilote Postgres standard (node-postgres, pg) utilisant DATABASE_URL, ou un recours local PGLite lorsqu'elle n'est pas définie. Même API dans les deux cas — un modèle avec balises (et .query()) résolvant en rows[]. Appelez UNIQUEMENT depuis un gestionnaire createServerFn / chargeur serveur, jamais depuis un composant client. Définissez le schéma dans migrations/, pas en ligne.
import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";
export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
const sql = await getSql();
// Tapez la forme de la ligne — la valeur de retour d'une fonction serveur doit être prouvablement sérialisable.
return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
// ou : return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});
Données par utilisateur (uniquement une fois que l'application a la connexion). Un pilote standard a un accès complet à la base de données, donc limitez chaque requête à l'utilisateur authentifié côté serveur — ne faites jamais confiance à un identifiant envoyé par le client. Utilisez le authMiddleware pré-câblé pour obtenir un context.userId vérifié, puis filtrez par celui-ci. Le modèle complet (intergiciel, appel depuis le code client, sémantique de fermeture en cas d'échec) se trouve dans la compétence auth :
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`;
});
// les mutations doivent également limiter les écritures : `... where id = ${id} and user_id = ${context.userId}`
Sans connexion (par défaut), n'utilisez PAS authMiddleware / requireUserId. L'utilisateur de développement auquel ils recourent est une commodité limitée à la prévisualisation. Le VITE_AUTH_ENABLED d'une application déployée est défini par la plateforme, pas par cet espace de travail (aujourd'hui, le déployeur le met toujours à "true"), donc une fois déployé, les deux rejettent chaque visiteur — et une application sans authentification n'offre pas de route de connexion pour qu'ils puissent récupérer. Une application utilisant uniquement la base de données conserve ses lignes sans propriétaire : pas de colonne user_id, ou une constante littérale. Ajoutez l'intergiciel dans le cadre de l'activation de la connexion (les étapes de mise à niveau de la compétence auth), et ré-affectez ou supprimez ces lignes à ce moment-là.
Les lignes sans propriétaire sont lisibles et modifiables par le monde entier via vos fonctions serveur publiques : ne persistez jamais de données personnelles ou sensibles (noms, e-mails, texte libre sur une personne) dans ce mode, et évitez les mutations destructrices en masse (supprimer tout, remplacer tout) — si l'application en a besoin, proposez plutôt la connexion.
Migrations
Les fichiers migrations/*.sql sont la source unique du schéma. Ils s'appliquent à Neon lors du déploiement (npm run build exécute db:migrate contre DATABASE_URL, donc Vercel livre le schéma prêt) et à la prévisualisation PGLite automatiquement au démarrage, de sorte que le développement corresponde à la production.
Aucun des deux applicateurs ne descend dans les sous-répertoires, donc le schéma Better Auth dans migrations/auth/0001_auth.sql n'est pas appliqué à moins que l'application n'active la connexion et ne le copie (ne le modifiez pas — voir la compétence auth). Placez le schéma de votre application dans de NOUVEAUX fichiers ordonnés commençant à 0002 :
-- migrations/0002_schema.sql — exemple pour une application de tâches ; utilisez LES TABLES de VOTRE application
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);
Ne modifiez jamais un fichier déjà appliqué — il est suivi par nom dans _migrations et ne sera pas réexécuté (ajoutez plutôt un nouveau fichier ; les nouveaux fichiers s'appliquent à la prévisualisation en cours d'exécution lors de la prochaine requête). Préférez les instructions idempotentes (… if not exists). Les tables contenant des données par utilisateur doivent avoir une colonne user_id text not null (TEXT, pas UUID — l'identifiant de l'utilisateur de développement en prévisualisation est la chaîne 'dev-user').
Parité prévisualisation ↔ production
getSql() normalise les types de résultat pour que les deux moteurs renvoient des formes identiques et sûres pour JSON : bigint/count(*) → number, date → chaîne 'YYYY-MM-DD', interval → texte, numeric → chaîne. Différences restantes à respecter :
- Les
bigintdépassant 2^53 perdent en précision en tant que nombre — castez::textsi vous avez besoin d'entiers très grands (les comptages de lignes sont corrects). - La base de données de prévisualisation est en mémoire : effacée au redémarrage du serveur de développement, connexion unique (pas de conflit de verrouillage ni de conflit d'écriture concurrente), et ne charge aucune extension — n'utilisez pas
create extension; contentez-vous du Postgres de base. - Le point de terminaison poolé de Neon ne conserve pas d'état de session — ne comptez pas sur
SET,LISTEN/NOTIFY, ou les verrous consultatifs de session. - Conservez les colonnes
user_identext— la prévisualisation utilise'dev-user', la production utilise les identifiants textuels de Better Auth ; une colonneuuidcasse les insertions en prévisualisation. - Les requêtes Neon déployées traversent le réseau (et peuvent être reprises à froid) — évitez les motifs de requête N+1 qui semblent gratuits contre la base de données de prévisualisation en processus.