product
This commit is contained in:
232
QUICK_INSTALL.md
Normal file
232
QUICK_INSTALL.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user