ach_ui_dbtl_file_based/QUICK_INSTALL.md

# Quick Install Guide - Using oracledb (No Oracle Instant Client Needed!)

## Super Simple Setup (5 minutes)

### Step 1: Install Python Dependencies

```bash
cd /home/asif/projects/ach_ui_dbtl_file_based
source venv/bin/activate
pip install -r requirements.txt
```

That's it! oracledb Thin mode works without any Oracle Instant Client installation.

### Step 2: Create .env File

```bash
cp .env.example .env
```

### Step 3: Update .env with Your Database Credentials

```bash
# Edit .env
nano .env
```

Make sure these are set:
```
DB_USER=pacs_db
DB_PASSWORD=pacs_db
DB_HOST=testipksdb.c7q7defafeea.ap-south-1.rds.amazonaws.com
DB_PORT=1521
DB_SERVICE_NAME=IPKSDB
```

### Step 4: Create Database Tables

```bash
# Connect to your Oracle database and run:
sqlplus pacs_db/pacs_db@testipksdb.c7q7defafeea.ap-south-1.rds.amazonaws.com:1521/IPKSDB

-- Create ach_api_log table (if not already exists)
CREATE TABLE ach_api_log (
    id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    narration VARCHAR2(500),
    status VARCHAR2(100),
    bankcode VARCHAR2(20),
    jrnl_id VARCHAR2(50),
    tran_date DATE,
    cbs_acct VARCHAR2(50),
    tran_amt NUMBER(15, 2),
    TXNIND VARCHAR2(2),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_ach_jrnl_id ON ach_api_log(jrnl_id);
CREATE INDEX idx_ach_bankcode ON ach_api_log(bankcode);

EXIT;
```

### Step 5: Test the Connection

```bash
python -c "
import oracledb
conn = oracledb.connect(
    user='pacs_db',
    password='pacs_db',
    dsn='testipksdb.c7q7defafeea.ap-south-1.rds.amazonaws.com:1521/IPKSDB'
)
print('✓ Connected successfully!')
conn.close()
"
```

### Step 6: Test Local Logic (No Database Needed)

```bash
python test_local.py
```

Expected output:
```
✓ Date conversion: '19/01/26' → 2026-01-19
✓ TXNIND calculation: 100.50 → CR, -50.00 → DR
✓ Amount conversion: -100.50 → 100.50 (absolute)
✓ ACH Parser: Extracted 178 transactions
✓ Configuration loaded
✓ ALL TESTS PASSED
```

### Step 7: Run the Application

```bash
python main.py
```

---

## Installation Time Comparison

| Method | Time | Oracle Instant Client | Complexity |
|--------|------|-----|-----------|
| **oracledb Thin (New!)** | 2 min | Not needed | ✓ Easy |
| cx_Oracle (Old) | 15+ min | Required | Complex |

---

## What's New with oracledb

### No Oracle Instant Client Needed!

**Before (cx_Oracle):**
1. Download 200+ MB Oracle Instant Client
2. Install and configure
3. Set environment variables
4. Troubleshoot missing libraries
5. Finally, install Python package

**Now (oracledb):**
```bash
pip install oracledb
# Done! Works immediately.
```

### Thin Mode (Default)

oracledb uses **Thin mode** by default:
- ✓ No Oracle Instant Client needed
- ✓ Direct connection to database
- ✓ Works on Linux, macOS, Windows
- ✓ Perfect for cloud deployments

### Backward Compatible

All existing code continues to work:
```python
# Same API as cx_Oracle
cursor = conn.cursor()
cursor.execute("SELECT * FROM table")
rows = cursor.fetchall()
```

---

## Troubleshooting

### "ModuleNotFoundError: No module named 'oracledb'"

```bash
pip install -r requirements.txt
```

### "DPI-2015: connection refused"

Check your credentials:
```bash
# Verify .env settings
cat .env | grep DB_
```

Test with sqlplus:
```bash
sqlplus pacs_db/pacs_db@testipksdb.c7q7defafeea.ap-south-1.rds.amazonaws.com:1521/IPKSDB
```

### "ORA-12514: TNS:listener does not currently know of service"

Check DB_SERVICE_NAME in .env:
```
DB_SERVICE_NAME=IPKSDB  # Must match your database service name
```

---

## Next Steps

1. ✓ Installation complete
2. Run tests: `python test_local.py`
3. Start scheduler: `python main.py`
4. Monitor logs: `tail -f logs/app.log`

---

## Key Differences from cx_Oracle

| Feature | cx_Oracle | oracledb |
|---------|-----------|----------|
| Installation | 15+ minutes | 2 minutes |
| Oracle Instant Client | Required | Optional |
| Thin Mode | No | ✓ Yes (default) |
| Connection Pooling | ✓ | ✓ |
| API Compatibility | — | ✓ Same |

---

## System Requirements

**Minimum:**
- Python 3.8+
- pip (for installing packages)
- Network access to Oracle Database

**Optional:**
- Oracle Instant Client (for Thick mode - not needed for Thin mode)
- sqlplus (for manual database administration)

---

## Files Updated

This quick install uses the newly updated files:
- `requirements.txt` - Now has oracledb instead of cx_Oracle
- `db/oracle_connector.py` - Updated to use oracledb
- `ORACLEDB_MIGRATION.md` - Full migration details

See `ORACLEDB_MIGRATION.md` for more information about the migration from cx_Oracle to oracledb.

---

## That's It!

You now have a working ACH File Processing Pipeline with:
- ✓ oracledb (simpler, no Oracle Instant Client needed)
- ✓ SFTP support
- ✓ Batch processing
- ✓ Duplicate detection
- ✓ Complete logging

Ready to process ACH files!