How to Integrate Bolt.new with PostgreSQL

Before writing any code, understand the WebContainer constraint and pick the right approach for your use case. Bolt's WebContainer runs Node.js inside a browser tab via WebAssembly. The browser security model prevents raw TCP socket connections, which means the standard pg (node-postgres) driver cannot connect to PostgreSQL servers during development. When you run pool.query() in the Bolt preview, the call will hang or throw a connection error — not because your connection string is wrong, but because TCP is blocked at the WebAssembly layer. Here is the decision tree for choosing your PostgreSQL approach: **Option 1: Bolt Database (auto-provisioned)** — Best for new projects where you want zero setup. Bolt provisions a Supabase PostgreSQL database automatically. Use @supabase/supabase-js for queries. Works in preview. Limitation: Supabase JS client works only with Vite projects per current Bolt documentation, not Next.js within Bolt's WebContainer. **Option 2: Supabase + @supabase/supabase-js** — Best for apps needing auth, real-time, and storage alongside the database. Use with Vite. PostgREST exposes your tables as REST endpoints over HTTP. Works in preview. **Option 3: Neon + @neondatabase/serverless** — Best for raw SQL with Vite or Next.js. Neon's serverless driver has HTTP mode that works in WebContainer. Supports tagged template literals for safe SQL. Works in preview. **Option 4: pg driver after deployment** — Best when you need connection pooling, transactions, or stored procedures that require the full pg driver. Write the code in Bolt, test by deploying to Netlify. This is the path for production apps with complex query requirements. All four paths lead to the same PostgreSQL — the difference is the client library and when you can test it. For most Bolt apps, start with Option 2 or 3.

1// Summary of PostgreSQL options in Bolt.new:
2
3// OPTION 1: Supabase (works in Bolt preview - Vite projects only)
4// Uses PostgREST over HTTP
5import { createClient } from '@supabase/supabase-js';
6const supabase = createClient(
7  import.meta.env.VITE_SUPABASE_URL,
8  import.meta.env.VITE_SUPABASE_ANON_KEY
9);
10// Usage: await supabase.from('products').select('*')
11
12// OPTION 2: Neon serverless (works in Bolt preview)
13// Uses HTTP transport
14import { neon } from '@neondatabase/serverless';
15const sql = neon(import.meta.env.VITE_DATABASE_URL);
16// Usage: await sql`SELECT * FROM products WHERE id = ${id}`
17
18// OPTION 3: Standard pg driver (FAILS in Bolt preview - TCP blocked)
19// Use ONLY in deployed Next.js API routes, NOT in browser/Vite
20import { Pool } from 'pg';
21const pool = new Pool({ connectionString: process.env.DATABASE_URL });
22// Usage: await pool.query('SELECT * FROM products WHERE id = $1', [id])
23// Error in Bolt preview: ECONNREFUSED / timeout (TCP blocked by WebContainer)

Neon is a serverless PostgreSQL provider that offers the best balance of flexibility and WebContainer compatibility for Bolt apps. Create a free account at neon.tech and provision a new database. On the Neon dashboard, find your connection string under 'Connection Details' — it looks like postgresql://user:password@ep-something.us-east-2.aws.neon.tech/neondb. Install @neondatabase/serverless. The package exports a neon function that creates a tagged template literal query executor using HTTP mode — no TCP, fully WebContainer compatible. Import and initialize neon() with your connection string from an environment variable. Neon's tagged template literal syntax automatically parameterizes query values, preventing SQL injection. Write queries like: const users = await sql`SELECT * FROM users WHERE email = ${email}`. The ${email} is a parameterized value, not string interpolation — safe and correct. For multiple results, the response is an array of row objects with typed properties matching your column names. For Next.js projects using Neon with API routes: use the neon function in your Route Handler files (app/api/*/route.ts). For Vite projects: you can use neon directly in client components only if you include the DATABASE_URL with the VITE_ prefix — but this exposes your database credentials client-side. Prefer putting Neon queries in a server context or API layer whenever possible. Neon also supports Prisma through the @prisma/adapter-neon package, which uses HTTP/WebSocket instead of TCP — making Prisma + Neon work in the WebContainer for a fully type-safe ORM experience.

1// lib/db.ts — Neon serverless client
2import { neon } from '@neondatabase/serverless';
3
4const connectionString = process.env.DATABASE_URL;
5
6if (!connectionString) {
7  throw new Error('DATABASE_URL environment variable is required');
8}
9
10export const sql = neon(connectionString);
11
12// Type helper for rows
13export type QueryResult<T> = T[];
14
15// app/api/users/route.ts — Using neon sql tag
16import { NextResponse } from 'next/server';
17import { sql } from '@/lib/db';
18
19interface User {
20  id: number;
21  name: string;
22  email: string;
23  created_at: string;
24}
25
26export async function GET() {
27  try {
28    const users = await sql<User[]>`
29      SELECT id, name, email, created_at
30      FROM users
31      ORDER BY created_at DESC
32      LIMIT 50
33    `;
34    return NextResponse.json(users);
35  } catch (error: unknown) {
36    const e = error as { message: string };
37    return NextResponse.json({ error: e.message }, { status: 500 });
38  }
39}
40
41export async function POST(request: Request) {
42  try {
43    const { name, email } = await request.json();
44    if (!name || !email) {
45      return NextResponse.json({ error: 'name and email required' }, { status: 400 });
46    }
47    const [user] = await sql<User[]>`
48      INSERT INTO users (name, email)
49      VALUES (${name}, ${email})
50      RETURNING *
51    `;
52    return NextResponse.json(user, { status: 201 });
53  } catch (error: unknown) {
54    const e = error as { message: string; code?: string };
55    if (e.code === '23505') {
56      return NextResponse.json({ error: 'Email already exists' }, { status: 409 });
57    }
58    return NextResponse.json({ error: e.message }, { status: 500 });
59  }
60}

Supabase is the recommended PostgreSQL option for Vite-based Bolt projects. Supabase provides PostgreSQL via PostgREST (a REST API layer) and real-time subscriptions via WebSocket — both protocols work in the WebContainer. Create a Supabase project at supabase.com, find your project URL and anon key in Settings → API. Install @supabase/supabase-js. Initialize the client with your Supabase URL and anon key (the anon key is safe to use client-side — it's a public key protected by Row Level Security). The client's .from() method chains query operators: .select(), .eq(), .gt(), .order(), .limit() for filtering; .insert(), .update(), .delete() for mutations; .subscribe() for real-time. Create your database tables either through Supabase's Table Editor GUI (supabase.com → your project → Table Editor) or by prompting Bolt to generate and run SQL migrations. Enable RLS (Row Level Security) on tables that contain user-specific data — without RLS, anyone with your anon key can read all rows. Bolt generates RLS policies automatically when you describe your access rules. Supabase real-time works through WebSocket channels. Subscribe to table changes: supabase.channel('orders').on('postgres_changes', {event: 'INSERT', schema: 'public', table: 'orders'}, callback).subscribe(). The callback receives a payload with the new row data. Unsubscribe in React's useEffect cleanup to prevent memory leaks. Important Bolt-specific limitation: @supabase/supabase-js in the WebContainer works with Vite projects. For Next.js API routes that need direct PostgreSQL access with complex queries, use @neondatabase/serverless instead of Supabase's client library.

1// lib/supabase.ts
2import { createClient } from '@supabase/supabase-js';
3
4const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
5const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;
6
7if (!supabaseUrl || !supabaseAnonKey) {
8  throw new Error('Missing VITE_SUPABASE_URL or VITE_SUPABASE_ANON_KEY');
9}
10
11export const supabase = createClient(supabaseUrl, supabaseAnonKey);
12
13// Migration SQL (run in Supabase SQL editor):
14/*
15CREATE TABLE todos (
16  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
17  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
18  title TEXT NOT NULL,
19  completed BOOLEAN NOT NULL DEFAULT false,
20  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
21);
22
23ALTER TABLE todos ENABLE ROW LEVEL SECURITY;
24
25CREATE POLICY "Users see own todos" ON todos
26  FOR ALL USING (auth.uid() = user_id);
27*/
28
29// Real-time subscription pattern:
30// const channel = supabase
31//   .channel('todos-changes')
32//   .on('postgres_changes', {
33//     event: '*',
34//     schema: 'public',
35//     table: 'todos',
36//     filter: `user_id=eq.${userId}`
37//   }, (payload) => {
38//     if (payload.eventType === 'INSERT') setTodos(prev => [payload.new as Todo, ...prev]);
39//     if (payload.eventType === 'UPDATE') setTodos(prev => prev.map(t => t.id === payload.new.id ? payload.new as Todo : t));
40//     if (payload.eventType === 'DELETE') setTodos(prev => prev.filter(t => t.id !== payload.old.id));
41//   })
42//   .subscribe();
43//
44// return () => supabase.removeChannel(channel); // Cleanup

After deploying to Netlify or Bolt Cloud, the TCP restriction is lifted — your code runs in a real Node.js environment where pg connects normally to PostgreSQL. This opens up advanced database patterns not possible in the WebContainer: connection pooling, transactions, prepared statements, stored procedures, COPY commands for bulk operations, and listen/notify for pub/sub. For serverless deployments on Netlify (and Vercel), use a connection pooler in front of your PostgreSQL database. Serverless functions create a new Node.js process for each request — without pooling, each function invocation would open a new PostgreSQL connection, quickly exhausting the database's connection limit. Neon's pooler endpoint (add -pooler to hostname) or PgBouncer handles this automatically. Supabase also exposes a pooler connection string in its dashboard under Settings → Database → Connection pooling. The pg Pool pattern for Next.js API routes: create a connection pool in a module-level variable. Node.js caches module imports, so the Pool object persists across API route invocations in the same Lambda container — connections are reused rather than created fresh each time. Export the pool from a lib/db.ts file and import it in your API routes. For Prisma users: Prisma works excellently with PostgreSQL after deployment. Use @prisma/adapter-neon for Neon (works in both WebContainer HTTP mode and deployed TCP mode), or configure the standard prisma/client with DATABASE_URL pointing to your deployed database. Run prisma db push or prisma migrate deploy in your Netlify build command to apply schema changes on deployment.

1// lib/pg-pool.ts
2// NOTE: This module uses TCP connections and only works AFTER DEPLOYMENT
3// to Netlify, Vercel, or similar Node.js environments.
4// In Bolt's WebContainer preview, queries will fail with ECONNREFUSED or timeout.
5import { Pool } from 'pg';
6
7const connectionString = process.env.DATABASE_URL;
8
9if (!connectionString) {
10  throw new Error('DATABASE_URL environment variable is required');
11}
12
13export const pool = new Pool({
14  connectionString,
15  max: 5, // Max connections in pool (keep low for serverless)
16  idleTimeoutMillis: 30000, // Release idle connections after 30s
17  connectionTimeoutMillis: 5000, // Fail fast if connection takes >5s
18  ssl: { rejectUnauthorized: false }, // Required for Neon/Supabase/RDS
19});
20
21// Graceful shutdown
22process.on('SIGTERM', () => pool.end());
23
24// Helper for parameterized queries
25export async function query<T>(
26  text: string,
27  params?: (string | number | boolean | null | undefined)[]
28): Promise<T[]> {
29  const { rows } = await pool.query(text, params);
30  return rows as T[];
31}
32
33// Transaction helper
34export async function withTransaction<T>(
35  callback: (client: { query: (text: string, params?: unknown[]) => Promise<{ rows: T[] }> }) => Promise<T>
36): Promise<T> {
37  const client = await pool.connect();
38  try {
39    await client.query('BEGIN');
40    const result = await callback(client);
41    await client.query('COMMIT');
42    return result;
43  } catch (error) {
44    await client.query('ROLLBACK');
45    throw error;
46  } finally {
47    client.release();
48  }
49}