shipd 0.1.3 → 0.2.0

package/features/database/README.md

@@ -0,0 +1,312 @@
+# Database Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ✅ Yes (base database setup)
+
+---
+
+## Overview
+
+This module sets up PostgreSQL database connectivity using Drizzle ORM. It provides the foundation for database operations and can be extended by other modules (auth, payments) that add their own tables.
+
+**Key Features:**
+- PostgreSQL connection with Drizzle ORM
+- Drizzle Kit configuration for migrations
+- Base schema structure (extended by other modules)
+- Database scripts (push, generate, migrate, studio)
+- Support for Neon, Supabase, or any Postgres database
+
+---
+
+## Files Added
+
+### Configuration
+- `drizzle.config.ts` - Drizzle Kit configuration
+- `db/drizzle.ts` - Database connection setup
+- `db/schema.ts` - Base schema file (modules will add tables here)
+
+### Migrations
+- `db/migrations/` - Directory for database migrations
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `postgres@^3.4.4` - PostgreSQL client
+- `drizzle-orm@^0.41.0` - Drizzle ORM
+
+### Dev Dependencies
+- `drizzle-kit@^0.31.0` - Drizzle migration and studio tools
+
+### Package Scripts
+The following scripts will be added to `package.json`:
+- `db:push` - Push schema changes to database (development)
+- `db:generate` - Generate migration files
+- `db:migrate` - Run migrations
+- `db:studio` - Open Drizzle Studio (database GUI)
+
+---
+
+## Environment Variables
+
+Add this to your `.env.local`:
+
+```env
+# Database
+DATABASE_URL="postgresql://user:password@host:port/database"
+```
+
+**Required Variables:**
+- `DATABASE_URL` - PostgreSQL connection string
+
+**Where to get it:**
+- **Neon**: [neon.tech](https://neon.tech) - Free tier available
+- **Supabase**: [supabase.com](https://supabase.com) - Free tier available
+- **Local Postgres**: `postgresql://postgres:password@localhost:5432/mydb`
+- **Any Postgres**: Standard PostgreSQL connection string format
+
+---
+
+## Manual Integration Steps
+
+If you're appending this module to an existing project, follow these steps:
+
+### Step 1: Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+The append command automatically adds missing dependencies to `package.json`, but you need to install them.
+
+### Step 2: Add Environment Variable
+
+1. Copy `.env.example` to `.env.local` (if not exists)
+2. Add `DATABASE_URL` with your PostgreSQL connection string
+3. Get a database URL from:
+   - [Neon](https://neon.tech) (recommended for development)
+   - [Supabase](https://supabase.com)
+   - Your own PostgreSQL server
+
+### Step 3: Verify Installation
+
+1. Check that `drizzle.config.ts` exists in project root
+2. Check that `db/drizzle.ts` and `db/schema.ts` exist
+3. Verify package.json has database scripts
+
+### Step 4: Initialize Database (Optional)
+
+If you want to create an initial migration:
+
+```bash
+npm run db:generate
+npm run db:push
+```
+
+**Note:** The base schema is empty. Tables will be added when you install other modules (auth, payments, etc.).
+
+---
+
+## Usage Examples
+
+### Using the Database Connection
+
+```typescript
+import { db } from "@/db/drizzle";
+
+// Example query (after auth module adds user table)
+const users = await db.select().from(user);
+```
+
+### Generating Migrations
+
+After adding tables (via auth or payments modules):
+
+```bash
+# Generate migration files
+npm run db:generate
+
+# Review the generated migration in db/migrations/
+
+# Push to database (development)
+npm run db:push
+
+# Or run migrations (production)
+npm run db:migrate
+```
+
+### Opening Drizzle Studio
+
+```bash
+npm run db:studio
+```
+
+This opens a web-based database GUI at `http://localhost:4983`
+
+---
+
+## Customization
+
+### Database Connection
+
+Edit `db/drizzle.ts` to customize the connection:
+
+```typescript
+// For Supabase compatibility (prepared statements disabled)
+const client = postgres(connectionString, { prepare: false });
+
+// For other Postgres providers
+const client = postgres(connectionString);
+```
+
+### Schema Location
+
+The schema file is at `db/schema.ts`. Other modules will add their tables here. You can also add custom tables:
+
+```typescript
+// db/schema.ts
+export const myCustomTable = pgTable("my_custom_table", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  // ...
+});
+```
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**db/schema.ts**:
+- Other modules (auth, payments) will add their tables to this file
+- You can add custom tables here as well
+
+**drizzle.config.ts**:
+- Usually doesn't need changes
+- Modify if you need custom migration settings
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "Missing DATABASE_URL" error
+**Solution:**
+- Ensure `DATABASE_URL` is set in `.env.local`
+- Restart your dev server after adding env vars
+- Check the connection string format
+
+**Issue:** "Connection refused" or "ECONNREFUSED"
+**Solution:**
+- Verify your database is running
+- Check the connection string is correct
+- For cloud databases, ensure your IP is whitelisted (if required)
+
+**Issue:** "relation does not exist" error
+**Solution:**
+- Run migrations: `npm run db:push` or `npm run db:migrate`
+- Ensure other modules (auth, payments) have been installed and their tables added
+
+**Issue:** Supabase connection issues
+**Solution:**
+- The connection is configured with `prepare: false` for Supabase compatibility
+- If issues persist, check Supabase connection pooling settings
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Set up your database (Neon, Supabase, or local)
+2. Add `DATABASE_URL` to `.env.local`
+3. Install Auth module (will add user/session tables)
+4. Install Payments module (will add subscription table)
+5. Run `npm run db:push` to create tables
+
+---
+
+## Related Modules
+
+This module is required by:
+- **Auth Module** - Adds user, session, account, verification tables
+- **Payments Module** - Adds subscription table
+
+This module works well with:
+- **Auth Module** - For user authentication
+- **Payments Module** - For subscription management
+
+---
+
+## Module Status
+
+✅ **Standalone Package** - Can be installed independently  
+✅ **Base Setup** - Provides foundation for other modules  
+✅ **Ready to Use** - Works immediately after append  
+✅ **Well Documented** - Comprehensive integration guide
+
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the Database module into an existing Next.js application.
+
+```
+The Database module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- postgres@^3.4.4 - PostgreSQL client library
+- drizzle-orm@^0.41.0 - TypeScript ORM for PostgreSQL
+- drizzle-kit@^0.31.0 (dev) - Migration and database management tools
+
+**Files Added:**
+- drizzle.config.ts - Drizzle Kit configuration for migrations
+- db/drizzle.ts - Database connection setup with lazy initialization
+- db/schema.ts - Base schema file (currently empty, ready for modules to add tables)
+- db/migrations/ - Directory for database migration files
+
+**Package Scripts Added:**
+- npm run db:push - Push schema changes directly to database (development)
+- npm run db:generate - Generate migration files from schema changes
+- npm run db:migrate - Run pending migrations
+- npm run db:studio - Open Drizzle Studio GUI at http://localhost:4983
+
+**Environment Variables Required:**
+- DATABASE_URL - PostgreSQL connection string (format: postgresql://user:password@host:port/database)
+
+**Integration Steps:**
+1. Verify DATABASE_URL is set in .env.local. If missing, prompt user to add it.
+2. Check that db/drizzle.ts uses lazy connection pattern (allows app to run without DATABASE_URL configured).
+3. Verify db/schema.ts exists and is empty (other modules will add tables here).
+4. Ensure drizzle.config.ts points to correct schema path: "./db/schema.ts"
+5. Test database connection by running: npm run db:studio (if DATABASE_URL is set)
+
+**Key Integration Points:**
+- The database connection in db/drizzle.ts uses a Proxy pattern for lazy initialization
+- Other modules (auth, payments) will automatically merge their tables into db/schema.ts
+- The schema file should be imported as: import * as schema from "@/db/schema"
+- Database queries use Drizzle ORM syntax: db.select().from(table).where(eq(table.id, value))
+
+**Dependencies:**
+- This module has no dependencies on other Shipd modules
+- Other modules (auth, payments) require this module to be installed first
+
+**Common Issues to Check:**
+- If DATABASE_URL is missing, the app should still run (lazy connection), but database operations will fail
+- For Supabase compatibility, connection uses { prepare: false } option
+- Migration files are generated in db/migrations/ directory
+
+**Next Steps After Integration:**
+- If auth module is installed, it will add user/session/account/verification tables to schema
+- If payments module is installed, it will add subscription table to schema
+- After other modules add tables, run: npm run db:push to create tables in database
+```

package/features/database/db/drizzle.ts

@@ -0,0 +1,48 @@
+import postgres from "postgres";
+import { drizzle } from "drizzle-orm/postgres-js";
+
+// Lazy database connection - only connect when actually used
+// This allows the app to start even without DATABASE_URL configured
+let dbInstance: ReturnType<typeof drizzle> | null = null;
+let connectionError: Error | null = null;
+
+function getDb() {
+  if (dbInstance) {
+    return dbInstance;
+  }
+
+  if (connectionError) {
+    throw connectionError;
+  }
+
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) {
+    connectionError = new Error(
+      "Missing DATABASE_URL. Add it to your .env.local (or hosting provider env vars). " +
+        "You can use a Neon Postgres URL, Supabase, or any Postgres connection string."
+    );
+    throw connectionError;
+  }
+
+  try {
+    // Disable prepared statements for Supabase compatibility
+    const client = postgres(connectionString, { prepare: false });
+    dbInstance = drizzle(client);
+    return dbInstance;
+  } catch (error) {
+    connectionError = error instanceof Error ? error : new Error(String(error));
+    throw connectionError;
+  }
+}
+
+// Export a proxy that lazily initializes the database
+export const db = new Proxy({} as ReturnType<typeof drizzle>, {
+  get(_target, prop) {
+    const db = getDb();
+    const value = db[prop as keyof ReturnType<typeof drizzle>];
+    if (typeof value === 'function') {
+      return value.bind(db);
+    }
+    return value;
+  }
+});

package/features/database/db/schema.ts

@@ -0,0 +1,21 @@
+import {
+  boolean,
+  integer,
+  pgTable,
+  text,
+  timestamp,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Base Database Schema
+ * 
+ * This is the base schema. Other modules (auth, payments) will add their tables.
+ * When appending modules, their schema files will be merged into this file.
+ */
+
+// Auth tables will be added by the auth module
+// Subscription table will be added by the payments module
+
+// Base schema is empty - modules add their own tables
+// This file serves as the entry point for schema merging
+

package/features/database/drizzle.config.ts

@@ -0,0 +1,13 @@
+import { config } from 'dotenv';
+import { defineConfig } from "drizzle-kit";
+
+config({ path: '.env' });
+
+export default defineConfig({
+  schema: "./db/schema.ts",
+  out: "./db/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});

package/features/database/feature.config.json

@@ -0,0 +1,30 @@
+{
+  "name": "database",
+  "version": "1.0.0",
+  "description": "PostgreSQL database setup with Drizzle ORM",
+  "dependencies": {
+    "postgres": "^3.4.4",
+    "drizzle-orm": "^0.41.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.0"
+  },
+  "envVars": [
+    "DATABASE_URL"
+  ],
+  "files": [
+    "drizzle.config.ts",
+    "db/drizzle.ts",
+    "db/schema.ts",
+    "db/migrations"
+  ],
+  "packageJsonScripts": {
+    "db:push": "drizzle-kit push",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  },
+  "requires": [],
+  "conflicts": []
+}
+