Neon Postgres
データベースはオプトインです(AGENTS.md §0.5):ブラウザセッションを超えて存続するデータ、またはデバイス間で共有されるデータがアプリに必要な場合にのみ使用してください。それ以外の場合は、マイグレーションを含めず、@/lib/dbをインポートせず、localStorage / zustandで状態を管理してください。
このテンプレートには、すぐに使えるデュアルモードのデータベース統合が含まれています:
- 設定済み(環境変数が設定されている、例:デプロイ済み):実際のNeon Postgres。
- 未設定(サンドボックスライブプレビュー):DBはローカルのPGLite(埋め込みWASM Postgres)にフォールバックするため、プレビューは常にレンダリングされます。
@/lib/dbヘルパーを対象にビルドしてください。どちらのモードも同じAPIで動作します。
パッケージはプリインストール済みです — npm install しないでください:pg(node-postgres、通常のPostgresドライバー)と@electric-sql/pglite(ローカルDBフォールバック)が含まれています。
ユーザーアカウント、サインイン、現在のユーザーの読み取りについては、別の**authスキル**を参照してください — このスキルはデータベースのみを扱います。
データベースを有効にする
.grok/app-env.json で deploy.database を true に設定します:
{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
これにより、デプロイされたアプリにNeonをプロビジョニングするようプラットフォームに指示します。falseのままにすると、デプロイには DATABASE_URL が設定されず、アプリは行が失われる使い捨てのPGLite上でサイレントに実行されます。migrations/*.sql の出荷、またはサインインは、このフラグに関係なくNeonをプロビジョニングします — このフラグは、@/lib/db をクエリするが、それらのどちらも持たないアプリのためのものです。これは VITE_ キーではなく、ブラウザに渡されることはありません。
環境変数 — .env ファイルを作成しないでください
データベース用の .env / .env.local / .env.example を決して作成しないでください。サンドボックスライブプレビューでは、DATABASE_URL を未設定のままにしてください — @/lib/db は自動的に埋め込みPGLiteを使用します。アプリがデプロイされると、プラットフォームが DATABASE_URL(Neon)を注入します。自分でプロビジョニングしたり記述したりする必要はありません。
| 変数 | 場所 | 目的 |
|---|---|---|
DATABASE_URL | サーバー | デプロイ時のNeon接続文字列(オプション — 未設定の場合はPGLiteにフォールバック) |
決してハードコードしないでください。VITE_ 以外の変数をクライアントに公開しないでください。
データベース(サーバー専用)
@/lib/db は getSql() と dbSource をエクスポートします:DATABASE_URL に対する通常のPostgresドライバー(node-postgres、pg)、または未設定の場合のローカルPGLiteフォールバックです。どちらの場合も同じAPI — タグ付きテンプレート(および .query())で、rows[] に解決されます。createServerFn ハンドラー / サーバーローダーからのみ呼び出し、クライアントコンポーネントからは決して呼び出さないでください。スキーマはインラインではなく migrations/ で定義します。
import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";
export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
const sql = await getSql();
// 行の型を指定 — サーバー関数の戻り値は確実にシリアライズ可能である必要があります。
return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
// または:return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});
ユーザーごとのデータ(アプリにサインイン機能が追加された後のみ)。 通常のドライバーはDBへのフルアクセスを持つため、すべてのクエリをサーバーサイドで認証済みユーザーにスコープし、クライアントから送信されたIDを決して信頼しないでください。プリワイヤードの authMiddleware を使用して検証済みの context.userId を取得し、それでフィルタリングします。完全なパターン(ミドルウェア、クライアントコードからの呼び出し、フェイルクローズドセマンティクス)は 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`;
});
// ミューテーションも書き込みをスコープする必要があります:`... where id = ${id} and user_id = ${context.userId}`
サインインなし(デフォルト)の場合、authMiddleware / requireUserId を使用しないでください**。フォールバックする開発ユーザーはプレビュー専用の便宜的なものです。デプロイされたアプリの VITE_AUTH_ENABLED は、このワークスペースではなくプラットフォームによって設定されるため(現在、デプロイヤーは常に "true" に設定します)、デプロイされると、両方ともすべての訪問者を拒否します — そして認証オフのアプリには、ユーザーが回復するためのサインインルートがありません。データベース専用アプリは、行を所有権なしに保ちます(user_id カラムなし、またはリテラル定数)。ミドルウェアは、サインインをオンにする(authスキルのアップグレード手順)一部として追加し、その時に行を再スコープまたは削除します。
所有権のない行は、パブリックサーバー関数を通じてワールドリーダブルかつワールドライタブルです:個人データや機密データ(名前、メールアドレス、個人に関するフリーテキスト)をこのモードで永続化せず、破壊的な一括ミューテーション(全削除、全上書き)も含めないでください — アプリがそれらを必要とする場合は、代わりにサインインを提案してください。
マイグレーション
migrations/*.sql が唯一のスキーマソースです。これらはデプロイ時のNeon(npm run build は DATABASE_URL に対して db:migrate を実行するため、Vercelはスキーマが準備された状態で出荷されます)とPGLiteプレビューに起動時に自動的に適用されるため、開発環境と本番環境が一致します。
どちらの適用ツールもサブディレクトリには降りないため、migrations/auth/0001_auth.sql のBetter Authスキーマは、アプリがサインインをオンにしてそれをコピーしない限り適用されません(編集しないでください — authスキルを参照)。アプリのスキーマは 0002 から始まる新しい順序付きファイルに配置します:
-- migrations/0002_schema.sql — todosアプリの例。YOURアプリのテーブルを使用してください
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);
適用済みのファイルは決して編集しないでください — 名前で _migrations に追跡され、再実行されません(代わりに新しいファイルを追加してください。新しいファイルは次のリクエスト時に実行中のプレビューに適用されます)。べき等なステートメント(… if not exists)を推奨します。ユーザーごとのデータを持つテーブルには user_id text not null カラムを含める必要があります(TEXT、UUIDではありません — プレビューの開発ユーザーIDは文字列 'dev-user' です)。
プレビュー ↔ 本番のパリティ
getSql() は結果の型を正規化し、両方のバックエンドが同一のJSONセーフな形状を返すようにします:bigint/count(*) → number、date → 'YYYY-MM-DD' 文字列、interval → テキスト、numeric → 文字列。注意すべき残りの相違点:
- 2^53を超える
bigintはnumberとして精度を失います — 巨大な整数が必要な場合は::textにキャストしてください(行数は問題ありません)。 - プレビューDBはインメモリです:開発サーバー再起動時にクリアされ、シングル接続(ロック競合や同時書き込み競合なし)、拡張機能はロードされません —
create extensionはしないでください。コアPostgresに限定してください。 - Neonのプールエンドポイントはセッション状態を保持しません —
SET、LISTEN/NOTIFY、セッションアドバイザリロックに依存しないでください。 user_idカラムはtextのままにしてください — プレビューは'dev-user'を使用し、本番はBetter AuthのテキストIDを使用します。uuidカラムはプレビューの挿入を壊します。- デプロイされたNeonクエリはネットワークを経由し(コールドリジュームの可能性あり) — インプロセスのプレビューDBに対して気軽に使えるN+1クエリパターンを避けてください。