feat: Enhanced transaction handling with savepoints and isolation levels

[Mrunal112]

Enhanced Transaction Handling for PostgreSQL Wire Protocol Mock

Changes Proposed

This PR enhances the transaction handling capabilities of the PostgreSQL wire protocol mock server to better simulate real PostgreSQL transaction behavior. The implementation includes comprehensive support for transaction control, savepoints, isolation levels, and proper error handling.

Key Features Added

1. Advanced Transaction Control

• BEGIN / START TRANSACTION with full option support
• Transaction isolation levels: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE
• Transaction modes: READ ONLY, READ WRITE, DEFERRABLE
• Proper COMMIT and ROLLBACK handling
• SET TRANSACTION command support

2. Savepoint Management

• SAVEPOINT <name> - Create named savepoints within transactions
• ROLLBACK TO SAVEPOINT <name> - Rollback to a specific savepoint
• RELEASE SAVEPOINT <name> - Release a savepoint
• Proper savepoint stack management (LIFO)
• Savepoint name validation and duplicate handling

3. Enhanced Error Handling

• Automatic transaction failure state on query errors
• Proper SQLSTATE error codes:
  • 25001 - ACTIVE_SQL_TRANSACTION (already in transaction)
  • 25P01 - NO_ACTIVE_SQL_TRANSACTION (no transaction active)
  • 25P02 - IN_FAILED_SQL_TRANSACTION (transaction aborted)
  • 3B001 - UNDEFINED_SAVEPOINT (savepoint not found)
• Transaction recovery via savepoints
• Proper error context and hints

4. Transaction State Management

• Transaction depth tracking for nested BEGIN detection
• Transaction start time and duration calculation
• Transaction status indicators (IDLE, IN_TRANSACTION, IN_FAILED_TRANSACTION)
• Proper PostgreSQL prompt indicators (postgres=# vs postgres=*> vs postgres=!>)

5. Comprehensive Testing

• 69 test cases covering all transaction behaviors
• Basic transaction control tests (BEGIN, COMMIT, ROLLBACK)
• Transaction options and isolation level tests
• Savepoint management tests (create, rollback, release)
• Error handling and recovery tests
• Nested transaction detection tests
• All tests passing ✅

6. Documentation

• Complete transaction support documentation (docs/TRANSACTION_SUPPORT.md)
• CLI testing guide with 18 test scenarios (TRANSACTION_CLI_TESTING.md)
• Updated README with transaction features
• Updated CHANGELOG with detailed changes

Related Issues

Fixes #57

Files Changed

Core Implementation

• src/connection/connectionState.js - Enhanced connection state management

  • Added transaction isolation level, read-only, and deferrable flags
  • Implemented savepoint stack (LIFO operations)
  • Added transaction depth tracking
  • Transaction duration tracking
  • Methods: beginTransaction(), createSavepoint(), rollbackToSavepoint(), releaseSavepoint()

• src/handlers/queryHandlers.js - Transaction query handlers

  • handleTransactionQuery() - Main transaction command router
  • handleBeginTransaction() - BEGIN with options parser
  • handleCommitTransaction() - COMMIT handler
  • handleRollbackTransaction() - ROLLBACK and ROLLBACK TO SAVEPOINT handler
  • handleSavepoint() - SAVEPOINT creation
  • handleReleaseSavepoint() - SAVEPOINT release
  • parseTransactionOptions() - Transaction option parser
  • handleSetTransaction() - SET TRANSACTION handler

• src/protocol/constants.js - Added UNDEFINED_SAVEPOINT error code

Tests

• __tests__/handlers/transactionHandlers.test.js - Comprehensive test suite (69 tests)
  • Basic transaction control (9 tests)
  • Transaction options (6 tests)
  • Isolation levels (4 tests)
  • Savepoint management (12 tests)
  • Duration tracking (3 tests)
  • Connection state (6 tests)
  • Nested transactions (2 tests)
  • Query handlers (27 tests)

Documentation

• docs/TRANSACTION_SUPPORT.md - Complete feature documentation
• TRANSACTION_CLI_TESTING.md - CLI testing guide
• README.md - Updated with transaction features
• CHANGELOG.md - Added detailed change log entry

Testing Results

✅ All 69 tests passing

npm test -- transactionHandlers.test.js

✅ CLI Testing Verified (via psql client)

• Basic transactions work correctly
• Isolation levels accepted and tracked
• Savepoints created, rolled back, and released properly
• Transaction state indicators working (postgres=*> prompt)
• Error recovery via savepoints is functional
• Nested BEGIN properly rejected with error code 25001

Example Usage

Basic Transaction

BEGIN;
SELECT 'Hello from transaction!';
COMMIT;

Transaction with Isolation Level

BEGIN ISOLATION LEVEL SERIALIZABLE;
SELECT * FROM users;
COMMIT;

Savepoint Recovery

BEGIN;
SELECT 1 AS "working";
SAVEPOINT safe_point;
-- Some operation that might fail
ROLLBACK TO SAVEPOINT safe_point;
SELECT 2 AS "recovered";
COMMIT;

Multiple Savepoints

BEGIN;
SAVEPOINT sp1;
-- work
SAVEPOINT sp2;
-- more work
ROLLBACK TO SAVEPOINT sp1;  -- sp2 is automatically discarded
COMMIT;

Checklist

• I've read the contributing guidelines
• Tests for the changes have been added/updated (69 tests)
• All tests pass locally ✅
• Documentation has been updated (TRANSACTION_SUPPORT.md, CLI guide, README, CHANGELOG)
• The code follows project style guidelines (lint-staged passed)
• No new warnings are generated

Screenshots

• Initiating a Transaction

• Error when Nested Transaction is Attempted (Error Code 25001)

• Test Cases Results