SachetCognition · devin-ai-integration · Jan 8, 2026 · Jan 8, 2026
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,28 @@
+version: '3.8'
+
+services:
+  oracle-xe:
+    image: gvenzl/oracle-xe:21-slim
+    container_name: oracle-xe-persistent
+    environment:
+      - ORACLE_PASSWORD=oracle
+    ports:
+      - "1521:1521"
+    volumes:
+      - oracle-data:/opt/oracle/oradata
+    shm_size: 1g
+    healthcheck:
+      test: ["CMD", "healthcheck.sh"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    networks:
+      - utplsql_network
+
+networks:
+  utplsql_network:
+    driver: bridge
+
+volumes:
+  oracle-data:
+    driver: local
diff --git a/docs/PERSISTENT_DATABASE_SETUP.md b/docs/PERSISTENT_DATABASE_SETUP.md
@@ -0,0 +1,296 @@
+# Persistent Oracle Database Setup Guide
+
+This guide explains how to set up and run the utPLSQL demo project with a persistent Oracle database that preserves data across container restarts.
+
+## Overview
+
+The default CI/CD setup uses ephemeral Docker containers that are destroyed after each pipeline run. This persistent setup uses Docker volumes to ensure data survives container restarts and recreations.
+
+## Prerequisites
+
+Before starting, ensure you have installed:
+
+- **Docker**: Version 20.10 or later
+- **Docker Compose**: Version 2.0 or later (or docker-compose v1.29+)
+- **Git**: For cloning the utPLSQL framework
+
+## Quick Start
+
+### 1. Start the Persistent Database
+
+```bash
+# Make the setup script executable
+chmod +x scripts/setup_persistent_db.sh
+
+# Start the database
+./scripts/setup_persistent_db.sh
+```
+
+This will:
+- Create a Docker network for the database
+- Start an Oracle XE 21c container with persistent storage
+- Wait for the database to be ready
+
+### 2. Install utPLSQL and Demo Project
+
+```bash
+# Make the installation script executable
+chmod +x scripts/install_all.sh
+
+# Install everything
+./scripts/install_all.sh
+```
+
+This will:
+- Clone and install the utPLSQL v3 testing framework
+- Create the `ut3_demo` user
+- Install the demo PL/SQL packages
+- Install the persistent tables with varying complexity
+- Install the unit tests
+
+### 3. Verify Data Persistence
+
+```bash
+# Make the verification script executable
+chmod +x scripts/verify_persistence.sh
+
+# Run the verification
+./scripts/verify_persistence.sh
+```
+
+This script will:
+- Display current data in all tables
+- Insert test data
+- Stop and restart the container
+- Verify the test data persisted
+
+## Connection Details
+
+| Property | Value |
+|----------|-------|
+| Host | localhost |
+| Port | 1521 |
+| Service Name | XE |
+| SYS Password | oracle |
+| Demo User | ut3_demo |
+| Demo Password | ut3_demo |
+
+### Connection Strings
+
+```bash
+# SYS (admin) connection
+sqlplus sys/oracle@//127.0.0.1:1521/XE as sysdba
+
+# Demo user connection
+sqlplus ut3_demo/ut3_demo@//127.0.0.1:1521/XE
+```
+
+## Docker Commands
+
+### Start the Database
+```bash
+docker compose up -d
+```
+
+### Stop the Database (preserves data)
+```bash
+docker compose stop
+```
+
+### Restart the Database
+```bash
+docker compose start
+```
+
+### Stop and Remove Container (preserves data in volume)
+```bash
+docker compose down
+```
+
+### Stop and Remove Everything (including data)
+```bash
+docker compose down -v
+```
+
+### View Database Logs
+```bash
+docker logs oracle-xe-persistent
+```
+
+### Follow Database Logs
+```bash
+docker logs -f oracle-xe-persistent
+```
+
+## Table Structure
+
+The persistent tables are organized into three complexity levels:
+
+### Simple Tables (V2.01)
+
+**categories** - Basic lookup table for product categories
+- `category_id` (NUMBER, PK)
+- `category_name` (VARCHAR2)
+- `description` (VARCHAR2)
+- `created_date` (DATE)
+
+**status_lookup** - Status codes for various entities
+- `status_code` (VARCHAR2, PK)
+- `status_description` (VARCHAR2)
+- `is_active` (CHAR)
+
+### Medium Complexity Tables (V2.02)
+
+**customers** - Customer information with constraints
+- Primary key with sequence
+- Foreign key to status_lookup
+- Email uniqueness constraint
+- Email format check constraint
+- Multiple indexes
+
+**products** - Product catalog with category relationships
+- Primary key with sequence
+- Foreign keys to categories and status_lookup
+- Price and stock check constraints
+- Multiple indexes
+
+**orders** - Order header information
+- Primary key with sequence
+- Foreign keys to customers and status_lookup
+- Date validation constraint
+- Multiple indexes
+
+### Complex Tables (V2.03)
+
+**order_items** - Order line items with computed columns
+- Primary key with sequence
+- Foreign keys to orders and products
+- Virtual column for line_total calculation
+- Unique constraint on order/product combination
+- Triggers for order total and inventory updates
+
+**audit_log** - Automatic change tracking
+- Captures INSERT, UPDATE, DELETE operations
+- Records old and new values
+- Tracks user and session information
+
+**inventory_transactions** - Stock movement history
+- Tracks all inventory changes
+- Links to source transactions
+- Maintains quantity history
+
+### Triggers
+
+1. **trg_update_order_total** - Automatically calculates order totals when items change
+2. **trg_update_inventory** - Updates product stock and creates inventory transactions
+3. **trg_audit_customers** - Logs all changes to the customers table
+4. **trg_customers_updated** - Sets updated_date on customer changes
+5. **trg_products_updated** - Sets updated_date on product changes
+
+## Running Tests
+
+After installation, run the utPLSQL unit tests:
+
+```bash
+./scripts/4_run_tests.sh
+```
+
+Or using utPLSQL-cli directly:
+
+```bash
+# Download utPLSQL-cli if not already present
+curl -Lk -o utPLSQL-cli.zip "https://github.com/utPLSQL/utPLSQL-cli/releases/download/3.1.9/utPLSQL-cli.zip"
+unzip utPLSQL-cli.zip
+chmod -R u+x utPLSQL-cli
+
+# Run tests
+utPLSQL-cli/bin/utplsql run ut3_demo/ut3_demo@//127.0.0.1:1521/XE -f=ut_documentation_reporter
+```
+
+## Troubleshooting
+
+### Database Won't Start
+
+1. Check if Docker is running:
+   ```bash
+   docker info
+   ```
+
+2. Check container logs:
+   ```bash
+   docker logs oracle-xe-persistent
+   ```
+
+3. Ensure port 1521 is not in use:
+   ```bash
+   lsof -i :1521
+   ```
+
+### Connection Refused
+
+1. Wait for the database to fully start (can take 2-3 minutes)
+2. Check if the container is running:
+   ```bash
+   docker ps | grep oracle-xe-persistent
+   ```
+
+### Data Not Persisting
+
+1. Ensure you're using `docker compose stop` instead of `docker compose down -v`
+2. Check if the volume exists:
+   ```bash
+   docker volume ls | grep oracle-data
+   ```
+
+### Permission Issues
+
+If you encounter permission issues with the scripts:
+```bash
+chmod +x scripts/*.sh
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Docker Host                               │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │              oracle-xe-persistent                      │  │
+│  │  ┌─────────────────────────────────────────────────┐  │  │
+│  │  │           Oracle XE 21c Database                │  │  │
+│  │  │  ┌─────────────┐  ┌─────────────────────────┐  │  │  │
+│  │  │  │ UT3 Schema  │  │    UT3_DEMO Schema      │  │  │  │
+│  │  │  │ (utPLSQL)   │  │ (Demo + Persistent)     │  │  │  │
+│  │  │  └─────────────┘  └─────────────────────────┘  │  │  │
+│  │  └─────────────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                           │                                  │
+│                           ▼                                  │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │              oracle-data (Docker Volume)               │  │
+│  │              /opt/oracle/oradata                       │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼ Port 1521
+                    ┌─────────────┐
+                    │   Client    │
+                    │ (SQLPlus,   │
+                    │  SQL Dev,   │
+                    │  utPLSQL)   │
+                    └─────────────┘
+```
+
+## Files Created
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Docker Compose configuration for persistent database |
+| `scripts/setup_persistent_db.sh` | Script to start the persistent database |
+| `scripts/install_all.sh` | Script to install utPLSQL, demo project, and tables |
+| `scripts/verify_persistence.sh` | Script to verify data persistence |
+| `source/persistent_tables/V2.01__simple_tables.sql` | Simple table definitions |
+| `source/persistent_tables/V2.02__medium_tables.sql` | Medium complexity tables |
+| `source/persistent_tables/V2.03__complex_tables.sql` | Complex tables with triggers |
+| `source/persistent_tables/install_persistent_tables.sql` | Installation script for tables |
+| `docs/PERSISTENT_DATABASE_SETUP.md` | This documentation |