CSV GENERATION SCRIPT (COMPLETE):
- Completed scripts/generate_csv_data.py
- Generates 100K customers, 150K accounts, 50K merchants
- Generates 200K cards, 75K devices
- Generates 5M transactions with 7% fraud rate
- Generates alerts, fraud cases, customer segments, CLV data
- All data has proper relationships and realistic values
- Generates in 2-5 minutes (vs 15-30 minutes with bash)
CSV BULK IMPORT SCRIPT (NEW):
- Created scripts/import_csv_data.sh
- Uses PostgreSQL COPY command for fast bulk loading
- 10-100x faster than INSERT statements
- Imports in correct order respecting foreign keys
- Clears existing data before import (idempotent)
- Shows import statistics and duration
- Verifies data integrity after import
- Checks for orphaned records
DEPLOY SCRIPT INTEGRATION:
- Updated deploy.sh to use CSV-based approach
- Step 7: Generate CSV files with Python
- Step 7: Import CSV files with bulk COPY
- Reduced time estimate from 15-30 min to 2-5 min
- Added error checking for both generation and import
- Exits on failure with clear error messages
BENEFITS:
- Data persists correctly (no more 0 rows after generation)
- 5-10x faster than bash-based generation
- Uses PostgreSQL best practices (COPY command)
- Atomic operations - all or nothing
- Easy to debug - can inspect CSV files
- Idempotent - safe to run multiple times
- Scalable - can generate millions of rows quickly
FILES CHANGED:
- scripts/generate_csv_data.py (completed)
- scripts/import_csv_data.sh (new)
- deploy.sh (updated to use CSV approach)
FIXES:
- Solves the data persistence issue (0 rows after generation)
- Transaction commit problems eliminated
- Much more reliable and production-ready
CUSTOMER SEGMENTS QUERY FIX:
- Fixed column names in verification query [5/5]
- Changed from segment_code to segment_name
- Changed from description to segment_description
- Matches actual table schema in 01-create-tables.sql
TABLE SCHEMA:
CREATE TABLE customer_segments (
segment_id SERIAL PRIMARY KEY,
segment_name VARCHAR(100) NOT NULL UNIQUE,
segment_description TEXT,
...
);
IMPACT:
- All 5 verification queries now work correctly
- No more column does not exist errors
- Setup script completes successfully
MERCHANT CATEGORIES FIX:
- Fixed duplicate category_code '7995' (Gambling vs Online Gambling)
- Changed Online Gambling code from '7995' to '7996'
- Fixed duplicate 'Direct Marketing' names to be unique
- Changed to 'Direct Marketing Inbound' and 'Direct Marketing Outbound'
- This was causing UNIQUE constraint violation preventing merchant_categories from loading
FRAUD TYPES QUERY FIX:
- Fixed column names in verification query
- Changed from fraud_type_code to fraud_code
- Changed from fraud_type_name to fraud_name
- Matches actual table schema in 01-create-tables.sql
IMPACT:
- Merchant categories will now load correctly (33 categories)
- Fraud types verification query will work without errors
- Setup script will complete all 5 verification queries successfully
DEPLOY SCRIPT IMPROVEMENTS:
- Start PostgreSQL first with --no-deps flag
- Wait for PostgreSQL to be healthy (increased to 120 seconds)
- Start pgAdmin separately after PostgreSQL is ready
- Added note that pgAdmin takes 30-60 seconds to initialize
- pgAdmin startup no longer blocks database operations
DOCKER COMPOSE FIX:
- Removed health check condition from pgAdmin depends_on
- Changed from 'condition: service_healthy' to simple dependency
- pgAdmin can start independently without waiting for PostgreSQL health
- Prevents 'Container is unhealthy' errors during startup
TROUBLESHOOTING SECTION:
- Added troubleshooting tips to deploy.sh output
- Command to check pgAdmin status: docker logs business_analytics_ui
- Instructions to wait for pgAdmin initialization
- Look for 'Listening at: http://[::]:80' in logs
BENEFITS:
- No more 'Container is unhealthy' errors
- Database operations can proceed while pgAdmin initializes
- Clear user expectations about pgAdmin startup time
- Better error handling and troubleshooting guidance
NEW SCRIPT: deploy.sh - Master deployment automation
- Tears down existing containers and volumes
- Fixes file permissions automatically
- Starts fresh containers
- Initializes database schema
- Generates test data
- Verifies deployment
- IDEMPOTENT: Safe to run multiple times
FEATURES:
- Beautiful colored output with progress indicators
- Confirmation prompt before destructive operations
- Waits for PostgreSQL to be healthy before proceeding
- Comprehensive access information at completion
- Useful commands reference
DOCUMENTATION:
- Updated README.md with Option A (one-command) and Option B (manual)
- Updated QUICKSTART.md with super quick start section
- Manual steps now in collapsible section
USER EXPERIENCE:
- Clone repo + run deploy.sh = DONE
- No more complex multi-step setup
- Perfect for demos and quick testing
- Rebuilds from scratch every time (no stale data)
PGADMIN FIX:
- Changed email from admin@businessanalytics.local to admin@example.com
- pgAdmin rejects .local domains as invalid email addresses
- Updated all documentation with correct email
SETUP VERIFICATION:
- Added 5 SQL verification queries to setup-database.sh
- Query 1: Sample countries (top 5)
- Query 2: Sample merchant categories (top 5)
- Query 3: All transaction types with descriptions
- Query 4: All fraud types ordered by severity
- Query 5: All customer segments with descriptions
BENEFITS:
- Users can immediately see that data was loaded correctly
- Provides visual confirmation of schema setup
- Shows sample data structure before generating full dataset
- Helps troubleshoot setup issues early
DOCKER COMPOSE:
- Replaced ghcr.io/n7olkachev/db-ui with dpage/pgadmin4:latest
- Added pgadmin_data volume for persistent configuration
- Configured pgAdmin with default credentials
- Port mapping: 3000:80 (pgAdmin runs on port 80 internally)
DOCUMENTATION:
- Updated README.md with pgAdmin login instructions and first-time setup
- Updated QUICKSTART.md with detailed pgAdmin configuration steps
- Added server connection details for easy setup
BENEFITS:
- pgAdmin has proper multi-platform support (linux/amd64, linux/arm64, etc.)
- Industry-standard PostgreSQL management tool
- More features: query builder, schema visualization, data import/export
- Better documentation and community support
Explicitly set platform: linux/amd64 for db-ui service
Fixes: no matching manifest for linux/amd64 error
The db-ui image has limited platform support, forcing amd64 ensures compatibility on x86_64 Linux systems
DOCKER COMPOSE:
- Removed obsolete 'version' attribute from docker-compose.yml
- Keeps db-ui image as ghcr.io/n7olkachev/db-ui:latest
SCRIPT PERMISSIONS:
- Updated README.md with recursive chmod command: find . -name '*.sh' -exec chmod +x {} \;
- Updated QUICKSTART.md with Step 0: Make Scripts Executable
- Removed individual chmod commands from each step
- Single command makes all .sh files executable at once
DOCUMENTATION:
- Renumbered steps in QUICKSTART.md for clarity
- Step 0: Make Scripts Executable
- Step 1: Install Dependencies (Optional)
- Step 2: Start Docker Containers
- Step 3: Initialize Database Schema
- Step 4: Generate Test Data
This resolves the Docker Compose warning and simplifies the setup process with a single chmod command.
DEPENDENCY MANAGEMENT:
- Created scripts/install-dependencies.sh - automatic installer for all required packages
- Detects OS (Ubuntu, Debian, CentOS, RHEL, Fedora, Arch, macOS)
- Installs PostgreSQL client (psql) automatically
- Installs Docker & Docker Compose if missing
- Installs utility packages (curl, wget, git)
SCRIPT ENHANCEMENTS:
- Updated setup-database.sh with dependency checking
- Updated generate_data.sh with dependency checking
- Updated verify-setup.sh with dependency checking
- All scripts now prompt to run installer if dependencies are missing
- Interactive prompts guide users through installation
DOCUMENTATION:
- Updated README.md with dependency installation instructions
- Updated QUICKSTART.md with Step 0: Install Dependencies
- Added supported OS list
- Added automatic dependency check notes
USER EXPERIENCE:
- No more manual package installation required
- Scripts fail gracefully with helpful error messages
- One-command installation: ./scripts/install-dependencies.sh
- Automatic detection and installation on Linux/macOS
- Clear instructions for Windows users
This ensures users can get started immediately without hunting for package installation commands.
- Docker setup with PostgreSQL 16 and DB-UI web interface
- Comprehensive 20+ table schema with fraud detection patterns
- Idempotent shell scripts for data generation (no Python dependency)
- Realistic geographic data (100 US cities, 210 world cities)
- 5M+ transactions with embedded fraud patterns (velocity, geographic, structuring, etc.)
- Progressive SQL exercises from beginner to advanced fraud detection
- Complete documentation and quick start guide
- Setup and verification scripts
Alphaeus Mote