Chapter 7: The Architect's Crossroads: BaaS vs. ORM

Welcome to Part Four. Here we'll temporarily step back from "how to implement" and enter the architect's mindset of "why choose this approach." For a full-stack SAAS application, two critical decisions will determine your development speed, scalability, and long-term costs: database and authentication.

In the Python backend world, this choice is relatively "fixed": Django developers typically choose Django ORM + Django Auth. Flask developers might choose SQLAlchemy + JWT.

But in the Next.js full-stack ecosystem, you're standing at a crossroads. You have two distinctly different paths available, both highly popular but representing completely different development philosophies.

7.1. Why Architecture Matters? (Performance, Lock-in, Flexibility)

This choice is critical because it deeply binds your backend architecture:

1. Performance & Scalability: Especially in serverless environments (like Vercel), database connection management is a huge performance bottleneck. Can your choice efficiently handle thousands of ephemeral serverless function connections?
2. Vendor Lock-in: Does your chosen service "lock" your data and authentication logic onto its platform? If you need to migrate in the future, how high is the cost?
3. Flexibility & Control: How much control do you have over database schema, query performance, and authentication flows? When SAAS business logic becomes complex, will your chosen tools become a bottleneck?

Let's dive deep into these two paths.

7.2. Path A: BaaS Model (Supabase)

The outstanding representative of the BaaS (Backend as a Service) model is Supabase.

You can think of Supabase as "open-source Firebase," but built on top of PostgreSQL, which you're familiar with. It's not a library, but a platform that packages everything you need to build a backend.

7.2.1. Advantages: Rapid Development, Built-in Auth, Realtime, RLS

With Supabase, you get a complete backend almost from day one:

• Rapid Development: You don't need to separately configure a database, write authentication APIs, or set up object storage. Everything is ready.
• Built-in Auth: Supabase has a complete user authentication system built-in (JWT, OAuth, Magic Links), deeply integrated with the database.
• Realtime: You can "subscribe" to database changes. For example, you can easily implement multi-user collaboration or real-time notifications without building your own WebSocket server.
• Storage: Built-in S3-compatible object storage for handling user-uploaded images or files.
• RLS (Row-Level Security): This is the core of Supabase, which we'll discuss in detail later.

For Python developers, this is like getting a "super Django" that not only has ORM and Auth, but also built-in S3 and realtime features, and is fully managed.

7.2.2. Core Practice: Row-Level Security (RLS) (Rule 2)

This is the key to the Supabase philosophy. In traditional Django/Flask applications, where do you write your security logic? In the application layer (views.py):

# Flask/Django application-layer security
def get_project(project_id):
    project = Project.objects.get(id=project_id)
    if project.owner_id != g.user.id:  # Check permissions in code
        abort(403)
    return project.to_json()

The Supabase (and RLS) philosophy is: security policies should be enforced at the database layer.

You define policies directly in SQL:

-- Supabase RLS Policy (SQL)
CREATE POLICY "Users can only see their own projects"
ON projects FOR SELECT
USING ( auth.uid() = owner_id ); -- auth.uid() is a function provided by Supabase

With RLS enabled, when an authenticated user executes SELECT * FROM projects, the PostgreSQL database will automatically filter to only return rows where owner_id equals the current user's ID.

Advantage: Your application-layer code (whether Next.js or anything else) becomes extremely simple. You can even query the database directly from the client side, because security policies are enforced in the database.

7.2.3. Core Practice: Connection Pooling (PgBouncer) (Rule 1)

This is the critical pain point of serverless architecture.

• Problem: Serverless Functions on Vercel are ephemeral. Every API request (or Server Action) might create a new function instance. If each instance opens a new database connection, your 1000 concurrent users could instantly exhaust your database's 100-connection limit, causing the application to crash.
• Traditional Solution (Python): In WSGI/ASGI (like Gunicorn), you have a long-running process pool that can maintain persistent database connections (like SQLAlchemy's Pool).
• Supabase Solution: Supabase has PgBouncer built-in, a lightweight connection pool manager. Your Serverless Functions actually connect to PgBouncer, which then manages a small number of persistent connections to the real Postgres database.

Conclusion: Supabase is a powerful, "batteries-included" platform, especially suitable for rapid project launches and teams that need realtime features.

7.3. Path B: ORM Model (Drizzle) - [This Book's Project Choice]

Now, let's look at the other path: Bring Your Own stack. This path doesn't rely on a single platform, but combines various "best" components.

• Database: Any Postgres provider (Neon, Vercel Postgres, AWS RDS...)
• ORM: Drizzle ORM (our choice)
• Auth: Better Auth (Auth.js) (we'll discuss this in the next chapter)

7.3.1. Advantages: Full Control, Type Safety, SQL Proximity, No Vendor Lock-in

Choosing Drizzle represents a different philosophy: "I want complete control over my stack and ultimate type safety and performance."

1. Full Control: You're not "locked" into the Supabase platform. Tomorrow you want to switch from Vercel Postgres to Neon, or self-host Postgres? No problem, you don't need to change a single line of code.
2. SQL Proximity: Drizzle is not a "heavyweight" ORM like SQLAlchemy or Prisma. It's a TypeScript Query Builder. The Drizzle code you write maps almost 1:1 to SQL statements.
   • Python Comparison: SQLAlchemy ORM has high abstraction (user.projects.append(p)). Drizzle is more like SQLAlchemy Core, where you write closer to SQL (db.select().from(users).where(...)).
   • Advantage: No complex ORM black box, predictable performance, and you can use all advanced Postgres features.
3. Ultimate Type Safety: This is Drizzle's trump card that beats all competitors (including SQLAlchemy). Drizzle's drizzle-kit tool automatically infers TypeScript types for all query results based on your Schema.
4. No Vendor Lock-in: Drizzle is just a library. Your authentication (Better Auth) is also just a library. They can be independently upgraded, replaced, and configured.

7.3.2. [Code Analysis]: Analyzing Drizzle Schema in src/db/

In our实战项目, src/db/schema.ts (or src/db/schema/ directory) is our only "Single Source of Truth," replacing Django's models.py.

Let's see what it looks like:

// src/db/schema/users.ts
import { pgTable, text, varchar, timestamp, boolean } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
import { projectsTable } from "./projects"; // Import other tables for relationships

// 1. Define Users table
export const usersTable = pgTable("users", {
  id: varchar("id").primaryKey(), // Usually from Better Auth user ID
  name: text("name"),
  email: text("email").notNull().unique(),

  // For Stripe subscription
  stripeCustomerId: text("stripe_customer_id").unique(),
  stripeSubscriptionId: text("stripe_subscription_id").unique(),
  stripePriceId: text("stripe_price_id"),
  stripeCurrentPeriodEnd: timestamp("stripe_current_period_end"),

  // For AI SAAS credits
  credits: integer("credits").default(10).notNull(),
});

// 2. Define Users table relationships
// Drizzle separates relationship definitions from table structure, keeping schema clean
export const usersRelations = relations(usersTable, ({ many }) => ({
  // One user (one) can have multiple projects (many)
  projects: many(projectsTable),
}));

// src/db/schema/projects.ts
import { pgTable, text, varchar, timestamp } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
import { usersTable } from "./users";

// 3. Define Projects table
export const projectsTable = pgTable("projects", {
  id: varchar("id").primaryKey().$defaultFn(() => crypto.randomUUID()), // Auto-generate UUID
  name: text("name").notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),

  // 4. Define foreign key (ForeignKey)
  ownerId: varchar("owner_id").notNull()
    .references(() => usersTable.id, { onDelete: "cascade" }), // Cascade delete
});

// 5. Define Projects table relationships
export const projectsRelations = relations(projectsTable, ({ one }) => ({
  // One project (one) belongs to only one user (one)
  owner: one(usersTable, {
    fields: [projectsTable.ownerId],
    references: [usersTable.id],
  }),
}));

Key Points:

• Clear SQL Mapping: pgTable, varchar, timestamp all directly correspond to SQL types.
• Type-safe Relationships: relations defines relationships between tables, and Drizzle uses them to provide type-safe join queries.
• drizzle-kit: After defining the schema, you'll run pnpm db:push (a script), and drizzle-kit will automatically "push" this schema change to your Postgres database.

7.4. Conclusion: Why Our SAAS Template Chose Drizzle (Flexibility & Control)

BaaS (Supabase) offers amazing development speed, but at a cost: you're locked into its ecosystem, its authentication, its RLS logic, and its hosting solution. This is great for quickly validating MVPs (Minimum Viable Products).

However, for a template targeting long-term evolution, highly customizable enterprise SAAS, control and flexibility are paramount.

We chose the Drizzle + Better Auth + Any Postgres Provider combination because:

1. We Control Our Data: We can host our database anywhere and use all Postgres advanced features without platform limitations.
2. We Control Authentication: We can freely customize authentication flows (see next chapter) without being limited by Supabase Auth's rules.
3. We Control Performance: Drizzle's lightweight nature and SQL proximity allow us to write the most efficient queries, perfectly pairing with serverless databases like Vercel Postgres (which also have built-in connection pooling).
4. We Control Types: Drizzle provides unparalleled end-to-end type safety from database to frontend.

This path requires slightly more configuration work on day 1, but it provides infinite possibilities for scaling on day 100 and day 1000. This is the architect's tradeoff.