proagents 1.0.0

package/proagents/database/examples/001-create-users.sql

@@ -0,0 +1,129 @@
+-- Migration: Create users table
+-- Author: ProAgents
+-- Date: 2024-01-15
+-- Risk Level: Low
+-- Requires Approval: No
+-- Estimated Duration: < 1 second
+
+-- Description:
+-- Creates the core users table with essential fields for authentication
+-- and profile information. This is typically one of the first migrations
+-- in a new project.
+
+-- ============================================
+-- UP MIGRATION
+-- ============================================
+
+-- Create enum for user status
+CREATE TYPE user_status AS ENUM ('active', 'inactive', 'suspended', 'pending');
+
+-- Create enum for user role
+CREATE TYPE user_role AS ENUM ('admin', 'developer', 'viewer', 'guest');
+
+-- Create users table
+CREATE TABLE users (
+    -- Primary key
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+    -- Authentication fields
+    email VARCHAR(255) NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+
+    -- Profile fields
+    first_name VARCHAR(100),
+    last_name VARCHAR(100),
+    display_name VARCHAR(100),
+    avatar_url TEXT,
+
+    -- Status and role
+    status user_status NOT NULL DEFAULT 'pending',
+    role user_role NOT NULL DEFAULT 'viewer',
+
+    -- Email verification
+    email_verified BOOLEAN NOT NULL DEFAULT FALSE,
+    email_verified_at TIMESTAMP WITH TIME ZONE,
+
+    -- Timestamps
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    last_login_at TIMESTAMP WITH TIME ZONE,
+
+    -- Soft delete
+    deleted_at TIMESTAMP WITH TIME ZONE
+);
+
+-- Create unique index on email (excluding soft-deleted users)
+CREATE UNIQUE INDEX idx_users_email_unique
+    ON users (email)
+    WHERE deleted_at IS NULL;
+
+-- Create index for common queries
+CREATE INDEX idx_users_status ON users (status) WHERE deleted_at IS NULL;
+CREATE INDEX idx_users_role ON users (role) WHERE deleted_at IS NULL;
+CREATE INDEX idx_users_created_at ON users (created_at);
+
+-- Create updated_at trigger function (reusable)
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply trigger to users table
+CREATE TRIGGER trigger_users_updated_at
+    BEFORE UPDATE ON users
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+
+-- Add table comment
+COMMENT ON TABLE users IS 'Core user accounts for authentication and authorization';
+
+-- ============================================
+-- DOWN MIGRATION (Rollback)
+-- ============================================
+
+-- WARNING: This will delete all user data!
+-- Ensure you have a backup before running rollback.
+
+-- Drop trigger
+DROP TRIGGER IF EXISTS trigger_users_updated_at ON users;
+
+-- Drop function (only if not used by other tables)
+-- DROP FUNCTION IF EXISTS update_updated_at_column();
+
+-- Drop table
+DROP TABLE IF EXISTS users;
+
+-- Drop enums
+DROP TYPE IF EXISTS user_role;
+DROP TYPE IF EXISTS user_status;
+
+-- ============================================
+-- VERIFICATION
+-- ============================================
+
+-- Run these queries to verify the migration succeeded:
+
+-- Check table exists
+SELECT EXISTS (
+    SELECT FROM information_schema.tables
+    WHERE table_name = 'users'
+);
+
+-- Check columns
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = 'users'
+ORDER BY ordinal_position;
+
+-- Check indexes
+SELECT indexname, indexdef
+FROM pg_indexes
+WHERE tablename = 'users';
+
+-- Check trigger
+SELECT trigger_name
+FROM information_schema.triggers
+WHERE event_object_table = 'users';

package/proagents/database/examples/002-add-preferences.sql

@@ -0,0 +1,94 @@
+-- Migration: Add user preferences column
+-- Author: ProAgents
+-- Date: 2024-01-16
+-- Risk Level: Low
+-- Requires Approval: No
+-- Estimated Duration: < 1 second
+
+-- Description:
+-- Adds a JSONB column to store user preferences like theme, language,
+-- notification settings, etc. Using JSONB allows flexible schema-less
+-- storage with indexing capabilities.
+
+-- ============================================
+-- UP MIGRATION
+-- ============================================
+
+-- Add preferences column with default empty object
+ALTER TABLE users
+ADD COLUMN preferences JSONB NOT NULL DEFAULT '{}'::jsonb;
+
+-- Add GIN index for JSONB queries
+-- This enables fast queries like: WHERE preferences @> '{"theme": "dark"}'
+CREATE INDEX idx_users_preferences
+    ON users USING GIN (preferences);
+
+-- Add specific index for common preference queries
+CREATE INDEX idx_users_preferences_theme
+    ON users ((preferences->>'theme'))
+    WHERE preferences->>'theme' IS NOT NULL;
+
+-- Add column comment
+COMMENT ON COLUMN users.preferences IS 'User preferences stored as JSONB. Keys: theme, language, notifications, timezone, etc.';
+
+-- Optionally set default preferences for existing users
+UPDATE users
+SET preferences = jsonb_build_object(
+    'theme', 'light',
+    'language', 'en',
+    'notifications', jsonb_build_object(
+        'email', true,
+        'push', true,
+        'weekly_digest', false
+    ),
+    'timezone', 'UTC'
+)
+WHERE preferences = '{}'::jsonb;
+
+-- ============================================
+-- DOWN MIGRATION (Rollback)
+-- ============================================
+
+-- Drop indexes first
+DROP INDEX IF EXISTS idx_users_preferences_theme;
+DROP INDEX IF EXISTS idx_users_preferences;
+
+-- Remove column
+ALTER TABLE users DROP COLUMN IF EXISTS preferences;
+
+-- ============================================
+-- VERIFICATION
+-- ============================================
+
+-- Check column exists
+SELECT column_name, data_type, column_default
+FROM information_schema.columns
+WHERE table_name = 'users' AND column_name = 'preferences';
+
+-- Check indexes exist
+SELECT indexname
+FROM pg_indexes
+WHERE tablename = 'users' AND indexname LIKE '%preferences%';
+
+-- Test JSONB query performance
+EXPLAIN ANALYZE
+SELECT id, email, preferences->>'theme' as theme
+FROM users
+WHERE preferences @> '{"theme": "dark"}';
+
+-- ============================================
+-- EXAMPLE USAGE
+-- ============================================
+
+-- Query users by preference
+-- SELECT * FROM users WHERE preferences->>'theme' = 'dark';
+
+-- Update a single preference
+-- UPDATE users
+-- SET preferences = jsonb_set(preferences, '{theme}', '"dark"')
+-- WHERE id = '...';
+
+-- Add new preference key
+-- UPDATE users
+-- SET preferences = preferences || '{"sidebar_collapsed": true}'::jsonb
+-- WHERE id = '...';

package/proagents/database/examples/003-add-index.sql

@@ -0,0 +1,105 @@
+-- Migration: Add performance index on users.email
+-- Author: ProAgents
+-- Date: 2024-01-17
+-- Risk Level: Medium
+-- Requires Approval: Team Lead
+-- Estimated Duration: Depends on table size (1-5 minutes for large tables)
+
+-- Description:
+-- Adds a B-tree index on the email column to improve login query performance.
+-- Uses CONCURRENTLY to avoid locking the table during index creation.
+--
+-- IMPORTANT: CONCURRENTLY cannot be used inside a transaction block.
+-- Run this migration outside of a transaction.
+
+-- ============================================
+-- PRE-FLIGHT CHECKS
+-- ============================================
+
+-- Check table size before creating index
+SELECT
+    pg_size_pretty(pg_total_relation_size('users')) as table_size,
+    (SELECT count(*) FROM users) as row_count;
+
+-- Estimate index creation time (rough)
+-- Rule of thumb: ~1 minute per 10 million rows
+
+-- ============================================
+-- UP MIGRATION
+-- ============================================
+
+-- Create index concurrently (non-blocking)
+-- NOTE: Cannot run inside transaction
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email_lookup
+    ON users (LOWER(email))
+    WHERE deleted_at IS NULL;
+
+-- Create composite index for common queries
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_status_created
+    ON users (status, created_at DESC)
+    WHERE deleted_at IS NULL;
+
+-- Create partial index for active users only
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_active
+    ON users (last_login_at DESC)
+    WHERE status = 'active' AND deleted_at IS NULL;
+
+-- ============================================
+-- DOWN MIGRATION (Rollback)
+-- ============================================
+
+-- Drop indexes (also use CONCURRENTLY for safety)
+DROP INDEX CONCURRENTLY IF EXISTS idx_users_active;
+DROP INDEX CONCURRENTLY IF EXISTS idx_users_status_created;
+DROP INDEX CONCURRENTLY IF EXISTS idx_users_email_lookup;
+
+-- ============================================
+-- VERIFICATION
+-- ============================================
+
+-- Check indexes were created
+SELECT
+    indexname,
+    indexdef,
+    pg_size_pretty(pg_relation_size(indexname::regclass)) as index_size
+FROM pg_indexes
+WHERE tablename = 'users'
+ORDER BY indexname;
+
+-- Verify index is being used
+EXPLAIN ANALYZE
+SELECT id, email
+FROM users
+WHERE LOWER(email) = 'test@example.com'
+  AND deleted_at IS NULL;
+
+-- Check for invalid indexes (failed CONCURRENTLY)
+SELECT indexrelid::regclass as index_name, indisvalid
+FROM pg_index
+WHERE NOT indisvalid;
+
+-- ============================================
+-- TROUBLESHOOTING
+-- ============================================
+
+-- If CONCURRENTLY fails, the index may be in invalid state.
+-- Check and drop invalid indexes:
+--
+-- SELECT indexrelid::regclass
+-- FROM pg_index
+-- WHERE NOT indisvalid;
+--
+-- DROP INDEX CONCURRENTLY idx_users_email_lookup;
+-- Then retry the CREATE INDEX CONCURRENTLY.
+
+-- ============================================
+-- PERFORMANCE COMPARISON
+-- ============================================
+
+-- Before index (sequential scan):
+-- Seq Scan on users  (cost=0.00..1234.00 rows=1 width=36)
+--   Filter: (lower((email)::text) = 'test@example.com'::text)
+
+-- After index (index scan):
+-- Index Scan using idx_users_email_lookup on users  (cost=0.42..8.44 rows=1 width=36)
+--   Index Cond: (lower((email)::text) = 'test@example.com'::text)

package/proagents/database/examples/004-rename-column.sql

@@ -0,0 +1,122 @@
+-- Migration: Rename column from 'name' to 'display_name'
+-- Author: ProAgents
+-- Date: 2024-01-18
+-- Risk Level: Medium
+-- Requires Approval: Team Lead
+-- Estimated Duration: < 1 second (metadata only)
+
+-- Description:
+-- Renames the 'name' column to 'display_name' for clarity.
+-- Column rename is a metadata-only operation in PostgreSQL,
+-- but requires application code updates.
+--
+-- IMPORTANT: Coordinate this migration with application deployment.
+-- Consider using the expand-contract pattern for zero-downtime.
+
+-- ============================================
+-- EXPAND-CONTRACT PATTERN (Zero Downtime)
+-- ============================================
+
+-- Phase 1: EXPAND - Add new column (this migration)
+-- Phase 2: MIGRATE - Update application to write to both columns
+-- Phase 3: BACKFILL - Copy data from old to new column
+-- Phase 4: CONTRACT - Update application to read from new column only
+-- Phase 5: CLEANUP - Drop old column (separate migration)
+
+-- ============================================
+-- UP MIGRATION (Simple approach - requires brief downtime)
+-- ============================================
+
+-- Option A: Direct rename (brief lock, simple)
+ALTER TABLE users
+RENAME COLUMN name TO display_name;
+
+-- Update any views that reference this column
+-- (Example if you have views)
+-- CREATE OR REPLACE VIEW user_profiles AS
+-- SELECT id, display_name, email FROM users;
+
+-- ============================================
+-- UP MIGRATION (Zero-downtime approach)
+-- ============================================
+
+-- -- Step 1: Add new column
+-- ALTER TABLE users ADD COLUMN display_name VARCHAR(100);
+--
+-- -- Step 2: Create trigger to sync columns during transition
+-- CREATE OR REPLACE FUNCTION sync_name_columns()
+-- RETURNS TRIGGER AS $$
+-- BEGIN
+--     IF TG_OP = 'INSERT' OR TG_OP = 'UPDATE' THEN
+--         IF NEW.display_name IS NULL AND NEW.name IS NOT NULL THEN
+--             NEW.display_name = NEW.name;
+--         ELSIF NEW.name IS NULL AND NEW.display_name IS NOT NULL THEN
+--             NEW.name = NEW.display_name;
+--         END IF;
+--     END IF;
+--     RETURN NEW;
+-- END;
+-- $$ LANGUAGE plpgsql;
+--
+-- CREATE TRIGGER trigger_sync_name_columns
+--     BEFORE INSERT OR UPDATE ON users
+--     FOR EACH ROW
+--     EXECUTE FUNCTION sync_name_columns();
+--
+-- -- Step 3: Backfill existing data
+-- UPDATE users SET display_name = name WHERE display_name IS NULL;
+--
+-- -- Step 4: After application updated, drop trigger and old column
+-- DROP TRIGGER IF EXISTS trigger_sync_name_columns ON users;
+-- DROP FUNCTION IF EXISTS sync_name_columns();
+-- ALTER TABLE users DROP COLUMN name;
+
+-- ============================================
+-- DOWN MIGRATION (Rollback)
+-- ============================================
+
+-- Option A: Simple rollback
+ALTER TABLE users
+RENAME COLUMN display_name TO name;
+
+-- Option B: Zero-downtime rollback (reverse the expand)
+-- ALTER TABLE users DROP COLUMN display_name;
+
+-- ============================================
+-- VERIFICATION
+-- ============================================
+
+-- Check column was renamed
+SELECT column_name
+FROM information_schema.columns
+WHERE table_name = 'users'
+  AND column_name IN ('name', 'display_name');
+
+-- Verify no broken views
+SELECT viewname
+FROM pg_views
+WHERE definition LIKE '%users.name%';
+
+-- Check for broken functions/procedures
+SELECT proname
+FROM pg_proc
+WHERE prosrc LIKE '%users.name%';
+
+-- ============================================
+-- APPLICATION CODE UPDATES REQUIRED
+-- ============================================
+
+-- Before migration:
+-- const user = await db.user.findUnique({ where: { id } });
+-- console.log(user.name);
+
+-- After migration:
+-- const user = await db.user.findUnique({ where: { id } });
+-- console.log(user.display_name);  // Updated field name
+
+-- ORM model update (Prisma example):
+-- model User {
+--   id           String   @id @default(uuid())
+--   display_name String?  @map("display_name")  // Updated from "name"
+--   email        String   @unique
+-- }

package/proagents/database/examples/005-add-foreign-key.sql

@@ -0,0 +1,142 @@
+-- Migration: Add foreign key relationship (users -> teams)
+-- Author: ProAgents
+-- Date: 2024-01-19
+-- Risk Level: Medium
+-- Requires Approval: Team Lead
+-- Estimated Duration: Depends on table size
+
+-- Description:
+-- Adds a team_id foreign key to the users table, establishing a
+-- many-to-one relationship between users and teams.
+--
+-- IMPORTANT: Existing users will have NULL team_id unless backfilled.
+
+-- ============================================
+-- PRE-FLIGHT CHECKS
+-- ============================================
+
+-- Ensure teams table exists
+SELECT EXISTS (
+    SELECT FROM information_schema.tables
+    WHERE table_name = 'teams'
+);
+
+-- Check for orphan data that would violate constraint
+-- (Run this BEFORE adding constraint)
+SELECT COUNT(*) as orphan_count
+FROM users u
+WHERE u.team_id IS NOT NULL
+  AND NOT EXISTS (SELECT 1 FROM teams t WHERE t.id = u.team_id);
+
+-- ============================================
+-- UP MIGRATION
+-- ============================================
+
+-- Step 1: Add the column (nullable first for safety)
+ALTER TABLE users
+ADD COLUMN team_id UUID;
+
+-- Step 2: Add index on foreign key column (important for JOIN performance)
+CREATE INDEX CONCURRENTLY idx_users_team_id
+    ON users (team_id)
+    WHERE team_id IS NOT NULL;
+
+-- Step 3: Add foreign key constraint
+-- Using NOT VALID first to avoid full table scan
+ALTER TABLE users
+ADD CONSTRAINT fk_users_team
+    FOREIGN KEY (team_id)
+    REFERENCES teams(id)
+    ON DELETE SET NULL  -- When team deleted, set user's team_id to NULL
+    ON UPDATE CASCADE   -- When team id changes, update users
+    NOT VALID;          -- Don't validate existing rows yet
+
+-- Step 4: Validate the constraint (can be done later, non-blocking)
+ALTER TABLE users
+VALIDATE CONSTRAINT fk_users_team;
+
+-- Add column comment
+COMMENT ON COLUMN users.team_id IS 'Reference to the team this user belongs to';
+
+-- ============================================
+-- ALTERNATIVE: Strict relationship (required team)
+-- ============================================
+
+-- If team_id should be required:
+--
+-- Step 1: Create default team
+-- INSERT INTO teams (id, name) VALUES ('00000000-0000-0000-0000-000000000000', 'Default');
+--
+-- Step 2: Add column with default
+-- ALTER TABLE users
+-- ADD COLUMN team_id UUID NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000';
+--
+-- Step 3: Add foreign key with RESTRICT
+-- ALTER TABLE users
+-- ADD CONSTRAINT fk_users_team
+--     FOREIGN KEY (team_id)
+--     REFERENCES teams(id)
+--     ON DELETE RESTRICT  -- Prevent team deletion if users exist
+--     ON UPDATE CASCADE;
+
+-- ============================================
+-- DOWN MIGRATION (Rollback)
+-- ============================================
+
+-- Drop constraint first
+ALTER TABLE users
+DROP CONSTRAINT IF EXISTS fk_users_team;
+
+-- Drop index
+DROP INDEX CONCURRENTLY IF EXISTS idx_users_team_id;
+
+-- Drop column
+ALTER TABLE users
+DROP COLUMN IF EXISTS team_id;
+
+-- ============================================
+-- VERIFICATION
+-- ============================================
+
+-- Check constraint exists
+SELECT constraint_name, constraint_type
+FROM information_schema.table_constraints
+WHERE table_name = 'users'
+  AND constraint_name = 'fk_users_team';
+
+-- Check foreign key details
+SELECT
+    kcu.column_name,
+    ccu.table_name AS foreign_table_name,
+    ccu.column_name AS foreign_column_name,
+    rc.delete_rule,
+    rc.update_rule
+FROM information_schema.key_column_usage kcu
+JOIN information_schema.constraint_column_usage ccu
+    ON kcu.constraint_name = ccu.constraint_name
+JOIN information_schema.referential_constraints rc
+    ON kcu.constraint_name = rc.constraint_name
+WHERE kcu.table_name = 'users'
+  AND kcu.constraint_name = 'fk_users_team';
+
+-- Test constraint enforcement
+-- This should fail:
+-- INSERT INTO users (email, password_hash, team_id)
+-- VALUES ('test@example.com', 'hash', '00000000-0000-0000-0000-000000000001');
+-- Error: insert or update on table "users" violates foreign key constraint
+
+-- ============================================
+-- BACKFILL EXISTING USERS
+-- ============================================
+
+-- Option 1: Assign all existing users to a default team
+-- UPDATE users
+-- SET team_id = (SELECT id FROM teams WHERE name = 'Default' LIMIT 1)
+-- WHERE team_id IS NULL;
+
+-- Option 2: Assign users based on email domain
+-- UPDATE users
+-- SET team_id = t.id
+-- FROM teams t
+-- WHERE users.email LIKE '%@' || t.domain
+--   AND users.team_id IS NULL;