feat(db): replace UUID with prefixed CUID2 IDs (#2162)

Author: koistya

apps/api/lib/auth.ts

@@ -1,6 +1,6 @@
 import { passkey } from "@better-auth/passkey";
 import { stripe } from "@better-auth/stripe";
-import { schema as Db } from "@repo/db";
+import { schema as Db, generateAuthId, type AuthModel } from "@repo/db";
 import { betterAuth } from "better-auth";
 import type { DB } from "better-auth/adapters/drizzle";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
@@ -101,7 +101,7 @@ function stripePlugin(db: DB, env: AuthEnv) {
  * Key behaviors:
  * - Uses custom 'identity' table instead of default 'account' model for OAuth accounts
  * - Allows users to create up to 5 organizations with 'owner' role as creator
- * - Delegates ID generation to database (schema defaults to gen_random_uuid)
+ * - Generates prefixed CUID2 IDs at application level (e.g. usr_..., ses_...)
  * - Supports anonymous authentication alongside email/password and Google OAuth
  *
  * @param db Drizzle database instance - must include all required auth tables (user, session, identity, organization, member, invitation, verification)
@@ -201,7 +201,7 @@ export function createAuth(
 
     advanced: {
       database: {
-        generateId: false,
+        generateId: ({ model }) => generateAuthId(model as AuthModel),
       },
     },
 

bun.lock

@@ -1,7 +1,7 @@
 ## Schema Conventions
 
 - Drizzle `casing: "snake_case"` — use camelCase in TypeScript, columns map to snake_case in DB.
-- All primary keys: `text().primaryKey().default(sql`gen_random_uuid()`)`.
+- All primary keys: `text().primaryKey().$defaultFn(() => generateAuthId(...))` — application-generated prefixed CUID2 IDs (e.g. `usr_ght4k2jxm7pqbv01`). See `db/schema/id.ts` for prefix map.
 - Timestamps: `timestamp({ withTimezone: true, mode: "date" })`. Every table has `createdAt` (`.defaultNow().notNull()`) and `updatedAt` (`.defaultNow().$onUpdate(() => new Date()).notNull()`).
 - `identity` table = Better Auth's `account` table, renamed via `account.modelName: "identity"` in auth config.
 - `member.role` and `invitation.status` are free `text`, not pgEnum — avoids fragile coupling with Better Auth's values.

db/AGENTS.md

@@ -90,16 +90,6 @@ import { organization, member } from "@/db/schema/organization";
 - Wrong environment: confirm `ENVIRONMENT`/`NODE_ENV` matches the target and the corresponding `.env.*` file exists.
 - Drift/conflicts: run `bun --filter @repo/db check`; regenerate migrations if schema and migrations diverge.
 
-## UUID v7
+## ID Generation
 
-The schema uses `gen_random_uuid()` by default for maximum compatibility. For time-ordered UUIDs (better index locality), replace with:
-
-- **PostgreSQL 18+**: `uuidv7()` (native)
-- **Earlier versions**: `uuid_generate_v7()` (requires [pg_uuidv7](https://github.com/fboulnois/pg_uuidv7) extension
-
-```typescript
-// Example: enable UUID v7 in schema
-id: text()
-  .primaryKey()
-  .default(sql`uuidv7()`);
-```
+All primary keys use application-generated prefixed CUID2 IDs (e.g. `usr_ght4k2jxm7pqbv01`). IDs are generated at the application level via `$defaultFn()` — no database-level defaults. See `db/schema/id.ts` for the prefix map and `docs/specs/prefixed-ids.md` for design rationale.

db/README.md

@@ -1,5 +1,5 @@
 CREATE TABLE "invitation" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"email" text NOT NULL,
 	"inviter_id" text NOT NULL,
 	"organization_id" text NOT NULL,
@@ -14,7 +14,7 @@ CREATE TABLE "invitation" (
 );
 --> statement-breakpoint
 CREATE TABLE "passkey" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"name" text,
 	"public_key" text NOT NULL,
 	"user_id" text NOT NULL,
@@ -33,7 +33,7 @@ CREATE TABLE "passkey" (
 );
 --> statement-breakpoint
 CREATE TABLE "member" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"user_id" text NOT NULL,
 	"organization_id" text NOT NULL,
 	"role" text NOT NULL,
@@ -43,7 +43,7 @@ CREATE TABLE "member" (
 );
 --> statement-breakpoint
 CREATE TABLE "organization" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"name" text NOT NULL,
 	"slug" text NOT NULL,
 	"logo" text,
@@ -55,7 +55,7 @@ CREATE TABLE "organization" (
 );
 --> statement-breakpoint
 CREATE TABLE "identity" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"account_id" text NOT NULL,
 	"provider_id" text NOT NULL,
 	"user_id" text NOT NULL,
@@ -72,7 +72,7 @@ CREATE TABLE "identity" (
 );
 --> statement-breakpoint
 CREATE TABLE "session" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"expires_at" timestamp with time zone NOT NULL,
 	"token" text NOT NULL,
 	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
@@ -85,7 +85,7 @@ CREATE TABLE "session" (
 );
 --> statement-breakpoint
 CREATE TABLE "subscription" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"plan" text NOT NULL,
 	"reference_id" text NOT NULL,
 	"stripe_customer_id" text,
@@ -108,7 +108,7 @@ CREATE TABLE "subscription" (
 );
 --> statement-breakpoint
 CREATE TABLE "user" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"name" text NOT NULL,
 	"email" text NOT NULL,
 	"email_verified" boolean DEFAULT false NOT NULL,
@@ -121,7 +121,7 @@ CREATE TABLE "user" (
 );
 --> statement-breakpoint
 CREATE TABLE "verification" (
-	"id" text PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
 	"identifier" text NOT NULL,
 	"value" text NOT NULL,
 	"expires_at" timestamp with time zone NOT NULL,

db/migrations/0000_init.sql

@@ -12,8 +12,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "email": {
           "name": "email",
@@ -166,8 +165,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "name": {
           "name": "name",
@@ -305,8 +303,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "user_id": {
           "name": "user_id",
@@ -413,8 +410,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "name": {
           "name": "name",
@@ -483,8 +479,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "account_id": {
           "name": "account_id",
@@ -609,8 +604,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "expires_at": {
           "name": "expires_at",
@@ -726,8 +720,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "plan": {
           "name": "plan",
@@ -895,8 +888,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "name": {
           "name": "name",
@@ -973,8 +965,7 @@
           "name": "id",
           "type": "text",
           "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
+          "notNull": true
         },
         "identifier": {
           "name": "identifier",

db/migrations/meta/0000_snapshot.json

@@ -44,5 +44,8 @@
     "drizzle-kit": "^0.31.9",
     "drizzle-orm": "^0.45.1",
     "typescript": "~5.9.3"
+  },
+  "dependencies": {
+    "@paralleldrive/cuid2": "^3.3.0"
   }
 }

db/package.json

@@ -0,0 +1,50 @@
+// Prefixed CUID2 ID generation for all database entities.
+// Format: {prefix}_{body} e.g. "usr_ght4k2jxm7pqbv01" (20 chars total)
+// See docs/specs/prefixed-ids.md for design rationale.
+
+import { init } from "@paralleldrive/cuid2";
+
+// Keys are Better Auth's internal model names (not table names).
+// "account" maps to the "identity" table via account.modelName config.
+const AUTH_PREFIX = {
+  user: "usr",
+  session: "ses",
+  account: "idn", // "identity" table — avoids confusion with user/billing account
+  verification: "vfy",
+  organization: "org",
+  member: "mem",
+  invitation: "inv",
+  passkey: "pky",
+  subscription: "sub",
+} as const;
+
+export type AuthModel = keyof typeof AUTH_PREFIX;
+
+const ID_LENGTH = 16;
+let _createId: (() => string) | null = null;
+
+function createId(): string {
+  if (!_createId) _createId = init({ length: ID_LENGTH });
+  return _createId();
+}
+
+/** Generate a prefixed ID for a Better Auth model (e.g. `"user"` → `"usr_..."`) */
+export function generateAuthId(model: AuthModel): string {
+  const prefix = AUTH_PREFIX[model];
+  if (!prefix) {
+    throw new Error(
+      `Unknown auth model "${String(model)}". Add it to AUTH_PREFIX in db/schema/id.ts`,
+    );
+  }
+  return `${prefix}_${createId()}`;
+}
+
+/** Generate a prefixed ID for non-auth tables (e.g. `generateId("upl")`) */
+export function generateId(prefix: string): string {
+  if (!/^[a-z]{3}$/.test(prefix)) {
+    throw new Error(
+      `ID prefix must be exactly 3 lowercase letters, got "${prefix}"`,
+    );
+  }
+  return `${prefix}_${createId()}`;
+}

db/schema/id.ts

@@ -1,3 +1,4 @@
+export * from "./id";
 export * from "./invitation";
 export * from "./organization";
 export * from "./passkey";

db/schema/index.ts

@@ -1,7 +1,8 @@
 // Better Auth invitation system for organization invites
 
-import { relations, sql } from "drizzle-orm";
+import { relations } from "drizzle-orm";
 import { index, pgTable, text, timestamp, unique } from "drizzle-orm/pg-core";
+import { generateAuthId } from "./id";
 import { organization } from "./organization";
 import { user } from "./user";
 
@@ -18,7 +19,7 @@ export const invitation = pgTable(
   {
     id: text()
       .primaryKey()
-      .default(sql`gen_random_uuid()`),
+      .$defaultFn(() => generateAuthId("invitation")),
     email: text().notNull(),
     inviterId: text()
       .notNull()