Drizzle ORM & PostgreSQL

Vibestacks uses Drizzle ORM with PostgreSQL. Drizzle provides a type-safe, SQL-like query builder that feels natural if you know SQL, while giving you full TypeScript autocomplete and compile-time error checking.

Database Options

docker compose up -d

DATABASE_URL="postgresql://postgres:password@localhost:5432/vibestacks_db"

DATABASE_URL="postgresql://user:password@ep-xxx.region.aws.neon.tech/neondb?sslmode=require"

DATABASE_URL="postgresql://postgres:[password]@db.[ref].supabase.co:5432/postgres"

Project Structure

Here's how the database layer is organized:

Connection Setup

The database client is configured in db/index.ts:

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";
import { env } from "@/env";

const pool = new Pool({
  connectionString: env.DATABASE_URL,
});

export const db = drizzle(pool, { schema });

Import db anywhere in your application to run queries:

import { db } from "@/db";
import { user } from "@/db/schema";

const users = await db.select().from(user);

Schema Overview

Vibestacks comes with authentication tables pre-configured for Better Auth. These tables are defined in db/auth-schema.ts.

Included Tables

Schema Conventions

All tables in Vibestacks follow these conventions:

export const example = pgTable("example", {
  id: text("id").primaryKey(),
  // ... your fields
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at")
    .defaultNow()
    .$onUpdate(() => new Date())
    .notNull(),
});

• id - Text primary key (we use nanoid for generation)
• createdAt - Auto-set on insert
• updatedAt - Auto-updated on every change
• Indexes - Added on foreign keys for query performance
• Cascade deletes - Related records are cleaned up automatically

Development Workflow

During development, use db:push for fast iteration. This syncs your schema directly to the database without generating migration files.

export * from "./auth-schema";
export * from "./posts-schema";  // Add new schema

import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
import { user } from "./auth-schema";

export const post = pgTable("post", {
  id: text("id").primaryKey(),
  title: text("title").notNull(),
  content: text("content"),
  authorId: text("author_id")
    .notNull()
    .references(() => user.id, { onDelete: "cascade" }),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at")
    .defaultNow()
    .$onUpdate(() => new Date())
    .notNull(),
});

pnpm db:push

pnpm db:studio

Production Workflow

For production deployments, use the generate + migrate workflow. This creates version-controlled SQL migration files that can be reviewed, tested, and applied consistently across environments.

pnpm db:generate

pnpm db:migrate

Recommended Workflow

Available Commands

Drizzle Studio

Drizzle Studio is a visual database browser that lets you inspect and edit your data without writing queries.

pnpm db:studio

This opens local.drizzle.studio in your browser.

Features:

• Browse all tables and their data
• Run custom SQL queries
• Edit records directly
• View table relationships

Troubleshooting

Connection refused errors

Make sure your database is running:

# For Docker
docker compose up -d

# Check container status
docker ps

For cloud databases (Neon/Supabase), verify:

• Your IP isn't blocked by firewall rules
• The connection string includes ?sslmode=require
• The database hasn't been paused due to inactivity (free tier)

"Relation does not exist" errors

Your schema hasn't been pushed to the database yet:

pnpm db:push

Migration conflicts

If you have conflicts between local changes and existing migrations:

# Reset local database (development only!)
docker compose down -v
docker compose up -d
pnpm db:push

Type errors after schema changes

Restart your TypeScript server to pick up new types:

• VS Code/Cursor: Cmd+Shift+P → "TypeScript: Restart TS Server"
• Or restart your dev server: pnpm dev

Vercel deployment fails with database errors

1. Verify DATABASE_URL is set in Vercel environment variables
2. Ensure the variable is available for the correct environments (Production, Preview, Development)
3. Check that migrations have been generated and committed:

pnpm db:generate
git add drizzle/
git commit -m "Add database migrations"

Next Steps

• IDE Setup - Configure your editor for the best experience
• Authentication - Learn how Better Auth uses these tables