clear references

tasks/kordant-unified-restructure/10-db-connection-migrations.md

@@ -1,25 +1,25 @@
-# 10. Database — PostgreSQL Connection, Migrations, and Seed Data
+# 10. Database — Turso (SQLite) Connection, Migrations, and Seed Data
 
 meta:
   id: kordant-unified-restructure-10
   feature: kordant-unified-restructure
   priority: P0
   depends_on: [kordant-unified-restructure-09]
-  tags: [backend, database, drizzle, postgres]
+  tags: [backend, database, drizzle, turso, sqlite]
 
 objective:
-- Set up the database connection layer, migration tooling, and seed data for the unified monolith. Replace the current SQLite setup in `web/` with PostgreSQL, matching the production database used by the legacy `packages/db`.
+- Set up the database connection layer, migration tooling, and seed data for the unified monolith. Configure Turso (libsql/SQLite) as the database backend, matching the production database used by the legacy `packages/db`.
 
 deliverables:
 - `web/src/server/db/index.ts` — Database connection module:
-  - Creates PostgreSQL connection pool using `pg` or `@neondatabase/serverless`
+  - Creates Turso (libsql) client using `@libsql/client`
   - Exports `db` instance initialized with Drizzle ORM
-  - Handles connection string from environment variables
-  - Graceful shutdown hook to close pool
+  - Handles connection URL and auth token from environment variables
+  - Graceful shutdown hook to close client
 - `web/drizzle.config.ts` — Drizzle Kit configuration:
-  - Points to `src/server/db/schema.ts`
-  - Specifies PostgreSQL dialect
-  - Reads database URL from env
+  - Points to `src/server/db/schema/index.ts`
+  - Specifies `turso` dialect
+  - Reads database URL and auth token from env
 - `web/src/server/db/migrate.ts` — Migration runner script:
   - Programmatically runs pending migrations on startup
   - Can be called from `entry-server.tsx` or a standalone script
@@ -28,35 +28,39 @@ deliverables:
   - Idempotent: can be run multiple times without duplicates
   - Useful for development and demo environments
 - Environment configuration:
-  - `DATABASE_URL` in `.env` and `.env.example`
-  - Connection pooling settings (max connections, timeout)
+  - `DATABASE_URL` and `DATABASE_AUTH_TOKEN` in `.env` and `.env.example`
 
 steps:
 1. Install dependencies in `web/`:
    - `drizzle-orm`, `drizzle-kit`
-   - `pg` (for local/dev) or `@neondatabase/serverless` (for serverless deploy)
-   - `@types/pg` if using `pg`
+   - `@libsql/client` (Turso/libsql client)
 2. Create `web/src/server/db/index.ts`:
    ```ts
-   import { drizzle } from 'drizzle-orm/node-postgres';
-   import { Pool } from 'pg';
+   import { createClient } from '@libsql/client';
+   import { drizzle } from 'drizzle-orm/libsql';
    import * as schema from './schema';
 
-   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-   export const db = drizzle(pool, { schema });
+   const client = createClient({
+     url: process.env.DATABASE_URL,
+     authToken: process.env.DATABASE_AUTH_TOKEN,
+   });
+   export const db = drizzle(client, { schema });
    ```
 3. Update `web/drizzle.config.ts`:
    ```ts
    import { defineConfig } from 'drizzle-kit';
    export default defineConfig({
-     schema: './src/server/db/schema.ts',
+     schema: './src/server/db/schema/index.ts',
      out: './drizzle',
-     dialect: 'postgresql',
-     dbCredentials: { url: process.env.DATABASE_URL! },
+     dialect: 'turso',
+     dbCredentials: {
+       url: process.env.DATABASE_URL!,
+       authToken: process.env.DATABASE_AUTH_TOKEN,
+     },
    });
    ```
 4. Create `web/src/server/db/migrate.ts`:
-   - Import `migrate` from `drizzle-orm/node-postgres/migrator`
+   - Import `migrate` from `drizzle-orm/libsql/migrator`
    - Run migrations from `./drizzle` folder
    - Log success or error
 5. Create `web/src/server/db/seed.ts`:
@@ -64,50 +68,40 @@ steps:
    - Create: 2-3 users, 1 family group, 2 subscriptions (basic + premium), 3-5 watchlist items, 2-3 exposures, 5-10 alerts, 3 blog posts, 2 property watchlist items, 1 removal request
    - Use deterministic IDs or check for existing data before inserting
 6. Add `db:migrate`, `db:generate`, `db:push`, `db:seed` scripts to `web/package.json`.
-7. Create `.env.example` in `web/` with `DATABASE_URL=postgresql://...`
+7. Create `.env.example` in `web/` with `DATABASE_URL=libsql://...` and `DATABASE_AUTH_TOKEN`
 8. Test locally:
-   - Start PostgreSQL (Docker or local install)
+   - Create a Turso database (or use local SQLite with `libsql://./dev.db`)
    - Run `pnpm db:generate` to create migration SQL
    - Run `pnpm db:push` to apply schema
    - Run `pnpm db:seed` to populate data
-   - Verify tables exist with correct data using `psql` or a GUI tool
+   - Verify tables exist with correct data using `turso db shell` or a SQLite GUI tool
 9. Update `web/src/server/db/schema.ts` from task 09 if any adjustments are needed based on migration output.
 
 steps:
 - Integration: `pnpm db:generate` produces valid SQL
-- Integration: `pnpm db:push` creates all tables in local PostgreSQL
+- Integration: `pnpm db:push` creates all tables in local Turso/SQLite
 - Integration: `pnpm db:seed` populates tables without errors
 - Integration: Application can query seeded data via `db.select()`
 
 acceptance_criteria:
-- [ ] `web/src/server/db/index.ts` exports a working Drizzle `db` instance
-- [ ] `drizzle.config.ts` is correctly configured for PostgreSQL
+- [ ] `web/src/server/db/index.ts` exports a working Drizzle `db` instance with Turso client
+- [ ] `drizzle.config.ts` is correctly configured for Turso (dialect: 'turso')
 - [ ] `pnpm db:generate` creates migration files in `web/drizzle/`
-- [ ] `pnpm db:push` applies schema to a PostgreSQL database successfully
+- [ ] `pnpm db:push` applies schema to a Turso database successfully
 - [ ] `pnpm db:seed` populates all relevant tables with sample data
 - [ ] The app can perform `db.select().from(users)` and return seeded users
 - [ ] Environment variables are documented in `.env.example`
 
 validation:
 - `cd web && pnpm db:generate` — check `drizzle/` folder for SQL files
-- `cd web && pnpm db:push` — verify tables created via `psql -d kordant -c "\dt"`
-- `cd web && pnpm db:seed` — verify data exists via `psql -d kordant -c "SELECT COUNT(*) FROM users;"`
+- `cd web && pnpm db:push` — verify tables created via `turso db shell <database> "SELECT name FROM sqlite_master WHERE type='table';"`
+- `cd web && pnpm db:seed` — verify data exists via `turso db shell <database> "SELECT COUNT(*) FROM users;"`
 - Create a temporary test route that queries `db.select().from(users)` and renders results
 
 notes:
-- The legacy project used Prisma + PostgreSQL in production. We are keeping PostgreSQL but switching to Drizzle ORM.
-- For local development, Docker Compose with PostgreSQL is recommended:
-  ```yaml
-  services:
-    postgres:
-      image: postgres:16-alpine
-      environment:
-        POSTGRES_USER: kordant
-        POSTGRES_PASSWORD: kordant
-        POSTGRES_DB: kordant
-      ports:
-        - "5432:5432"
-  ```
-- If deploying to Vercel/Netlify serverless, use `@neondatabase/serverless` instead of `pg`.
+- We are using Turso (libsql/SQLite) as the database backend with Drizzle ORM.
+- For local development, you can use a local SQLite file (`libsql://./dev.db`) or create a Turso database.
+- Turso provides edge-distributed SQLite with fast read replicas — no connection pooling needed.
 - Migration files should be committed to git so all environments run the same migrations.
-- The seed script should be idempotent. Use `ON CONFLICT DO NOTHING` or check existence before inserting.
+- The seed script should be idempotent. Use `INSERT OR IGNORE` or check existence before inserting.
+- SQLite doesn't support `DROP COLUMN` or `ALTER TABLE` extensively — plan schema changes carefully or use Turso's rewrap for migrations.