SQL/docs/QUICKSTART.md

Quick Start Guide

🚀 Get Up and Running in 5 Minutes

Step 1: Start Docker Containers (1 minute)

# From the project root directory
docker-compose up -d

What this does:

• Starts PostgreSQL 16 database
• Starts DB-UI web interface
• Creates network and volumes

Verify it's running:

docker-compose ps

You should see both fraud_detection_db and fraud_detection_ui running.

---

Step 2: Initialize Database Schema (1 minute)

# Make script executable (first time only)
chmod +x scripts/setup-database.sh

# Run setup
./scripts/setup-database.sh

What this does:

• Creates all 20+ tables
• Sets up indexes and constraints
• Loads reference data (countries, merchant categories, etc.)

Expected output:

✓ PostgreSQL is ready
✓ Creating tables, indexes, and constraints
✓ Loading reference data
✓ Database setup completed successfully!

---

Step 3: Generate Test Data (15-30 minutes)

# Make script executable (first time only)
chmod +x data/generate_data.sh

# Run data generation
./data/generate_data.sh

What this does:

• Generates 100,000 customers
• Creates 150,000 accounts
• Generates 5,000,000 transactions
• Creates fraud patterns and alerts

⏱️ Time estimate:

• Fast machine (SSD, 16GB RAM): ~15 minutes
• Average machine: ~20-25 minutes
• Slower machine: ~30 minutes

You can monitor progress: The script shows progress for each step:

[1/9] Loading geographic reference data...
[2/9] Generating Customers...
[3/9] Generating Accounts...
...

---

Step 4: Access the Database

Option A: DB-UI Web Interface (Recommended for Beginners)

1. Open your browser to: http://localhost:3000
2. You'll see the database tables in the sidebar
3. Click any table to browse data
4. Use the "Custom SQL" tab to run queries

Features:

• Visual table browser
• SQL query editor with syntax highlighting
• Export results to CSV
• Schema introspection

Option B: Command Line (psql)

docker exec -it fraud_detection_db psql -U fraud_analyst -d fraud_detection

Quick commands:

-- List all tables
\dt

-- Describe a table
\d customers

-- Run a query
SELECT COUNT(*) FROM transactions;

-- Exit
\q

Option C: Your Favorite SQL Client

Connection Details:

Host:     localhost
Port:     5432
Database: fraud_detection
Username: fraud_analyst
Password: SecurePass123!

Popular clients:

• DBeaver (free, cross-platform)
• pgAdmin (free, PostgreSQL-specific)
• DataGrip (paid, JetBrains)
• TablePlus (paid, macOS/Windows)

---

🎓 Your First Queries

1. Check Data Counts

-- How many customers?
SELECT COUNT(*) FROM customers;

-- How many transactions?
SELECT COUNT(*) FROM transactions;

-- How many fraud alerts?
SELECT COUNT(*) FROM alerts WHERE status = 'OPEN';

2. Find High-Risk Customers

SELECT 
    customer_id,
    first_name,
    last_name,
    email,
    risk_score
FROM customers
WHERE risk_score > 80
ORDER BY risk_score DESC
LIMIT 10;

3. View Recent Transactions

SELECT 
    transaction_id,
    account_id,
    amount,
    transaction_date,
    is_flagged
FROM transactions
ORDER BY transaction_date DESC
LIMIT 20;

4. Find Flagged Transactions

SELECT 
    t.transaction_id,
    t.amount,
    t.fraud_score,
    t.flagged_reason,
    c.first_name,
    c.last_name
FROM transactions t
JOIN accounts a ON t.account_id = a.account_id
JOIN customers c ON a.customer_id = c.customer_id
WHERE t.is_flagged = TRUE
ORDER BY t.fraud_score DESC
LIMIT 10;

---

📚 Next Steps

Start Learning SQL

1. Begin with basics: exercises/01-basic-queries/README.md
2. Progress through levels: Work through exercises 01-06
3. Practice fraud detection: exercises/06-fraud-detection/README.md

Explore the Data

-- What countries are represented?
SELECT country_name, COUNT(*) as customer_count
FROM customers c
JOIN countries co ON c.country_id = co.country_id
GROUP BY country_name
ORDER BY customer_count DESC;

-- What are the top merchant categories?
SELECT mc.category_name, COUNT(*) as transaction_count
FROM transactions t
JOIN merchants m ON t.merchant_id = m.merchant_id
JOIN merchant_categories mc ON m.category_id = mc.category_id
GROUP BY mc.category_name
ORDER BY transaction_count DESC;

-- How many fraud cases by type?
SELECT ft.fraud_name, COUNT(*) as case_count
FROM fraud_cases fc
JOIN fraud_types ft ON fc.fraud_type_id = ft.fraud_type_id
GROUP BY ft.fraud_name
ORDER BY case_count DESC;

---

🔧 Troubleshooting

Database won't start

# Check logs
docker-compose logs postgres

# Restart containers
docker-compose restart

Can't connect to database

# Check if PostgreSQL is ready
docker exec fraud_detection_db pg_isready -U fraud_analyst

# Check port is not in use
netstat -an | grep 5432

Data generation fails

# Check disk space
df -h

# Check memory
free -h

# Try with smaller dataset
# Edit data/generate_data.sh and reduce:
NUM_CUSTOMERS=10000
NUM_TRANSACTIONS=500000

Reset everything

# Stop and remove everything
docker-compose down -v

# Start fresh
docker-compose up -d
./scripts/setup-database.sh
./data/generate_data.sh

---

💡 Tips

1. Use DB-UI for exploration - Great for browsing and understanding the schema
2. Use psql for practice - Best for learning SQL commands
3. Start simple - Begin with basic SELECT queries before complex joins
4. Check the exercises - They're designed to build your skills progressively
5. Experiment - The database is yours to explore and learn from!

---

🎯 Learning Goals

After completing this tutorial, you'll be able to:

• ✅ Write complex SQL queries
• ✅ Understand database relationships
• ✅ Detect fraud patterns in data
• ✅ Use window functions and CTEs
• ✅ Optimize queries with indexes
• ✅ Investigate financial crimes

---

Ready to start? Head to exercises/01-basic-queries/README.md! 🚀