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

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

cp .env.example .env

Step 3: Update .env with Your Database Credentials

# 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

# 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

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)

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

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):

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:

# Same API as cx_Oracle
cursor = conn.cursor()
cursor.execute("SELECT * FROM table")
rows = cursor.fetchall()

---

Troubleshooting

"ModuleNotFoundError: No module named 'oracledb'"

pip install -r requirements.txt

"DPI-2015: connection refused"

Check your credentials:

# Verify .env settings
cat .env | grep DB_

Test with sqlplus:

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!