perf(database): add configurable pool, query timeouts, and transactions (#93)

* perf(database): add configurable pool, query timeouts, and transactions

- Use TIMEOUTS config for connection timeout (was hardcoded)
- Make connectionLimit configurable via DB_CONNECTION_LIMIT env var
- Add query() wrapper with per-query timeout and slow query logging
- Add withTransaction() for atomic multi-step operations
- Wrap registerUser in transaction to prevent partial writes
- Log slow queries (>1s threshold, configurable via DB_SLOW_QUERY_THRESHOLD)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: address PR review feedback

- Soften first-user admin comment (not strictly race-safe without FOR UPDATE)
- Handle ER_DUP_ENTRY race condition for email uniqueness
- Fix misleading comment about mysql2 timeout option
- Document DB_CONNECTION_LIMIT, DB_QUEUE_LIMIT, DB_SLOW_QUERY_THRESHOLD in .env.example

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: mbuckingham74

.env.example

@@ -90,6 +90,11 @@ DB_PASSWORD=secure_password_123  # CHANGE THIS IN PRODUCTION!
 DB_NAME=meteo_app               # Database name
 DB_ROOT_PASSWORD=root_password_456  # MySQL root password - CHANGE THIS!
 
+# Database Pool Settings (optional - defaults are usually fine)
+# DB_CONNECTION_LIMIT=10         # Max connections in pool (default: 10)
+# DB_QUEUE_LIMIT=0               # Max queued requests when pool exhausted (0 = unlimited)
+# DB_SLOW_QUERY_THRESHOLD=1000   # Log queries slower than this (ms, default: 1000)
+
 # ====================================
 # SERVER CONFIGURATION
 # ====================================

backend/config/database.js

@@ -1,22 +1,116 @@
 const mysql = require('mysql2/promise');
 require('dotenv').config();
+const TIMEOUTS = require('./timeouts');
+
+/**
+ * Helper to get environment variable as number with fallback
+ */
+function getEnvNumber(key, defaultValue) {
+  const value = process.env[key];
+  if (value === undefined || value === null || value === '') {
+    return defaultValue;
+  }
+  const parsed = parseInt(value, 10);
+  return isNaN(parsed) ? defaultValue : parsed;
+}
 
-// Database configuration
+// Database configuration with configurable pool settings and timeouts
 const dbConfig = {
   host: process.env.DB_HOST || 'localhost',
   port: process.env.DB_PORT || 3306,
   user: process.env.DB_USER || 'root',
   password: process.env.DB_PASSWORD,
   database: process.env.DB_NAME || 'meteo_app',
   waitForConnections: true,
-  connectionLimit: 10,
-  queueLimit: 0,
-  timezone: 'Z' // Use UTC
+  connectionLimit: getEnvNumber('DB_CONNECTION_LIMIT', 10),
+  queueLimit: getEnvNumber('DB_QUEUE_LIMIT', 0),
+  timezone: 'Z', // Use UTC
+  // Connection timeout for establishing new connections
+  connectTimeout: TIMEOUTS.DATABASE.CONNECTION_TIMEOUT,
 };
 
 // Create connection pool
 const pool = mysql.createPool(dbConfig);
 
+// Slow query threshold (log queries slower than this)
+const SLOW_QUERY_THRESHOLD_MS = getEnvNumber('DB_SLOW_QUERY_THRESHOLD', 1000);
+
+/**
+ * Execute a query with timeout and slow query logging
+ * @param {string} sql - SQL query string
+ * @param {Array} params - Query parameters
+ * @param {object} options - Optional settings
+ * @param {number} options.timeout - Query timeout in ms (default: TIMEOUTS.DATABASE.QUERY_TIMEOUT)
+ * @param {boolean} options.isComplex - Use complex query timeout (default: false)
+ * @returns {Promise<Array>} Query results
+ */
+async function query(sql, params = [], options = {}) {
+  const timeout = options.timeout ||
+    (options.isComplex ? TIMEOUTS.DATABASE.COMPLEX_QUERY_TIMEOUT : TIMEOUTS.DATABASE.QUERY_TIMEOUT);
+
+  const startTime = Date.now();
+
+  try {
+    // mysql2 supports per-query timeout via the 'timeout' option in query config
+    const result = await pool.query({ sql, timeout }, params);
+
+    const duration = Date.now() - startTime;
+    if (duration > SLOW_QUERY_THRESHOLD_MS) {
+      console.warn(`⚠️ Slow query (${duration}ms): ${sql.substring(0, 100)}...`);
+    }
+
+    return result;
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    if (error.code === 'PROTOCOL_SEQUENCE_TIMEOUT' || error.message?.includes('timeout')) {
+      console.error(`❌ Query timeout after ${duration}ms: ${sql.substring(0, 100)}...`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Execute multiple queries in a transaction
+ * Automatically rolls back on error
+ * @param {Function} callback - Async function receiving connection object
+ * @returns {Promise<any>} Result from callback
+ *
+ * @example
+ * await withTransaction(async (conn) => {
+ *   await conn.query('INSERT INTO users ...', [data]);
+ *   await conn.query('INSERT INTO preferences ...', [prefs]);
+ * });
+ */
+async function withTransaction(callback) {
+  const connection = await pool.getConnection();
+
+  try {
+    await connection.beginTransaction();
+
+    // Create a query wrapper that respects timeouts
+    const wrappedConnection = {
+      query: async (sql, params = [], options = {}) => {
+        const timeout = options.timeout || TIMEOUTS.DATABASE.QUERY_TIMEOUT;
+        return connection.query({ sql, timeout }, params);
+      },
+      execute: async (sql, params = [], options = {}) => {
+        const timeout = options.timeout || TIMEOUTS.DATABASE.QUERY_TIMEOUT;
+        return connection.execute({ sql, timeout }, params);
+      }
+    };
+
+    const result = await callback(wrappedConnection);
+
+    await connection.commit();
+    return result;
+  } catch (error) {
+    await connection.rollback();
+    throw error;
+  } finally {
+    connection.release();
+  }
+}
+
 // Test database connection
 async function testConnection() {
   try {
@@ -97,6 +191,8 @@ async function seedDatabase() {
 
 module.exports = {
   pool,
+  query,
+  withTransaction,
   testConnection,
   initializeDatabase,
   seedDatabase

backend/services/authService.js

@@ -1,6 +1,6 @@
 const bcrypt = require('bcryptjs');
 const jwt = require('jsonwebtoken');
-const { pool } = require('../config/database');
+const { pool, withTransaction } = require('../config/database');
 const { createError, ERROR_CODES } = require('../utils/errorCodes');
 
 /**
@@ -15,57 +15,71 @@ const SALT_ROUNDS = 10;
 
 /**
  * Register a new user
+ * Uses a transaction to ensure user and preferences are created atomically.
+ * Handles race conditions via unique constraint on email (ER_DUP_ENTRY).
  */
 async function registerUser(email, password, name) {
-  try {
-    // Check if user already exists
-    const [existingUsers] = await pool.query(
-      'SELECT id FROM users WHERE email = ?',
-      [email]
-    );
-
-    if (existingUsers.length > 0) {
-      throw createError(ERROR_CODES.EMAIL_ALREADY_EXISTS, 'Email already registered');
-    }
-
-    // Check if this is the first user (will become admin)
-    const [userCount] = await pool.query('SELECT COUNT(*) as count FROM users');
-    const isFirstUser = userCount[0].count === 0;
+  // Check if user already exists (outside transaction for fast rejection)
+  const [existingUsers] = await pool.query(
+    'SELECT id FROM users WHERE email = ?',
+    [email]
+  );
 
-    // Hash password
-    const passwordHash = await bcrypt.hash(password, SALT_ROUNDS);
+  if (existingUsers.length > 0) {
+    throw createError(ERROR_CODES.EMAIL_ALREADY_EXISTS, 'Email already registered');
+  }
 
-    // Create user (first user is automatically admin)
-    const [result] = await pool.query(
-      'INSERT INTO users (email, password_hash, name, is_admin) VALUES (?, ?, ?, ?)',
-      [email, passwordHash, name, isFirstUser]
-    );
+  // Hash password before transaction (CPU-intensive, don't hold connection)
+  const passwordHash = await bcrypt.hash(password, SALT_ROUNDS);
 
-    const userId = result.insertId;
+  try {
+    // Use transaction to ensure atomicity of user + preferences creation
+    const result = await withTransaction(async (conn) => {
+      // Check if this is the first user (will become admin)
+      // Note: This is a best-effort check. In rare race conditions with concurrent
+      // first registrations, multiple users could become admin. For stricter control,
+      // use SELECT ... FOR UPDATE or a dedicated admin setup flow.
+      const [userCount] = await conn.query('SELECT COUNT(*) as count FROM users');
+      const isFirstUser = userCount[0].count === 0;
+
+      // Create user (first user is automatically admin)
+      const [insertResult] = await conn.query(
+        'INSERT INTO users (email, password_hash, name, is_admin) VALUES (?, ?, ?, ?)',
+        [email, passwordHash, name, isFirstUser]
+      );
+
+      const userId = insertResult.insertId;
+
+      if (isFirstUser) {
+        console.log(`🔧 First user registered as admin: ${email}`);
+      }
 
-    if (isFirstUser) {
-      console.log(`🔧 First user registered as admin: ${email}`);
-    }
+      // Create default preferences
+      await conn.query(
+        'INSERT INTO user_preferences (user_id) VALUES (?)',
+        [userId]
+      );
 
-    // Create default preferences
-    await pool.query(
-      'INSERT INTO user_preferences (user_id) VALUES (?)',
-      [userId]
-    );
+      return { userId, isFirstUser };
+    });
 
-    // Generate tokens (include admin status)
-    const tokens = generateTokens(userId, email, isFirstUser);
+    // Generate tokens (include admin status) - outside transaction
+    const tokens = generateTokens(result.userId, email, result.isFirstUser);
 
     return {
       user: {
-        id: userId,
+        id: result.userId,
         email,
         name,
-        isAdmin: isFirstUser
+        isAdmin: result.isFirstUser
       },
       ...tokens
     };
   } catch (error) {
+    // Handle race condition where email was taken between pre-check and insert
+    if (error.code === 'ER_DUP_ENTRY' && error.message?.includes('email')) {
+      throw createError(ERROR_CODES.EMAIL_ALREADY_EXISTS, 'Email already registered');
+    }
     console.error('Registration error:', error);
     throw error;
   }