# Oracle E-commerce and Accounting Workload

This project contains SQL*Plus/SQLcl scripts for creating and exercising an
Oracle e-commerce and accounting schema, including background workload jobs.

## Requirements

- Oracle Database 12c or later. The schema uses identity columns and daily
  interval partitioning.
- Run the scripts while connected as the schema owner.
- The Scheduler management procedures require the schema owner to have the
  `CREATE JOB` system privilege. A DBA can grant it directly:

  ```sql
  GRANT CREATE JOB TO your_schema;
  ```

- The activity procedure uses `DBMS_LOCK.SLEEP`. The schema owner may need a
  direct grant from a DBA:

  ```sql
  GRANT EXECUTE ON SYS.DBMS_LOCK TO your_schema;
  ```

  A role grant may not be sufficient when compiling a stored procedure.

## Scripts and execution order

Run these scripts in order from SQL*Plus or SQLcl:

```sql
@oracle_ecommerce_schema.sql
@oracle_ecommerce_seed_2gb.sql
@oracle_ecommerce_activity.sql
@oracle_ecommerce_job_management.sql
```

The schema script creates objects only. The seed script expects the schema to
be empty and should be run once. The activity and job-management scripts
create or replace their procedures and can be rerun to install procedure
changes.

## `oracle_ecommerce_schema.sql`

Creates 22 tables with primary keys, foreign keys, unique and check
constraints, and supporting indexes. Seven event/transaction tables use
one-day interval range partitioning; Oracle creates daily interval partitions
automatically for inserted dates after the initial partition boundary.

The model covers:

- **Reference and customer data:** `CURRENCIES`, `SALES_CHANNELS`,
  `CUSTOMERS`, `CUSTOMER_ADDRESSES`, `SUPPLIERS`, `PRODUCT_CATEGORIES`,
  `WAREHOUSES`, and `GL_ACCOUNTS`.
- **Catalog and inventory:** `PRODUCTS`, `INVENTORY_BALANCES`, and
  `INVENTORY_MOVEMENTS`.
- **Sales and fulfillment:** `SALES_ORDERS`, `SALES_ORDER_LINES`, `PAYMENTS`,
  `SHIPMENTS`, `SHIPMENT_ITEMS`, and `RETURNS`.
- **Purchasing and accounting:** `PURCHASE_ORDERS`, `PURCHASE_ORDER_LINES`,
  `JOURNAL_ENTRIES`, and `JOURNAL_LINES`.
- **Operational history:** `AUDIT_EVENTS`.

Daily interval-partitioned tables are `SALES_ORDERS`, `PAYMENTS`, `SHIPMENTS`,
`INVENTORY_MOVEMENTS`, `JOURNAL_ENTRIES`, `RETURNS`, and `AUDIT_EVENTS`.

## `oracle_ecommerce_seed_2gb.sql`

Loads reference and transactional sample data, followed by an audit-event
payload of 2 GiB (2,147,483,648 ASCII characters/bytes in the `DETAILS`
column). Oracle table, index, and segment overhead makes the allocated
database storage larger than 2 GiB. The script generates 1,073,742 audit
rows and commits them in batches; the final row contains the remaining
payload bytes.

This is a large load and can consume substantial database time, redo, and
storage. It is intended for a test database with enough available space, not
for a production data environment. To change its payload size, edit
`c_target_payload_bytes` in the script. The number of characters per audit
row is controlled by `c_payload_chars` and must remain within the
`AUDIT_EVENTS.DETAILS` column capacity.

## `oracle_ecommerce_activity.sql`

Creates `SIMULATE_COMMERCE_ACTIVITY`, which randomly performs single-row
INSERT, UPDATE, and DELETE operations across these 16 tables:

`RETURNS`, `PURCHASE_ORDERS`, `PURCHASE_ORDER_LINES`, `PRODUCTS`,
`CUSTOMER_ADDRESSES`, `SHIPMENTS`, `PAYMENTS`, `CUSTOMERS`,
`JOURNAL_ENTRIES`, `SALES_ORDERS`, `INVENTORY_MOVEMENTS`, `SHIPMENT_ITEMS`,
`SALES_ORDER_LINES`, `JOURNAL_LINES`, `INVENTORY_BALANCES`, and `AUDIT_EVENTS`.

The procedure selects parent keys from existing rows for inserts and limits
parent-row deletes to records with no dependent rows. Each successful DML
operation affects one row. Updates change representative values/statuses;
inserts use synthetic data. Operations commit after each iteration, making
changes visible to other sessions, but also committing any uncommitted work
already present in the caller's session.

### Parameters

| Parameter | Meaning |
| --- | --- |
| `p_iterations` | Number of workload iterations; must be non-negative. |
| `p_seconds_between_iterations` | Delay between iterations in seconds; must be non-negative. |
| `p_average_rows_per_iteration` | Target average successful DML rows per iteration; must be between 0 and 10,000. Fractional values are randomly rounded across iterations. |

An iteration may affect fewer rows than its target if it cannot find an eligible
row or exhausts its bounded number of attempts. The average is therefore a
best-effort target, not a guarantee.

Example: run 100 iterations, wait 2 seconds between them, and target an average
of 5.5 successful row operations per iteration:

```sql
SET SERVEROUTPUT ON
EXEC simulate_commerce_activity(100, 2, 5.5);
```

The procedure prints a one-line summary for each iteration and a final total
and realized average. `DBMS_OUTPUT` is buffered, so SQL*Plus/SQLcl may display
the output after the procedure completes.

## `oracle_ecommerce_job_management.sql`

Creates four procedures for managing one-time Oracle Scheduler jobs that run
`SIMULATE_COMMERCE_ACTIVITY` asynchronously. A created job is enabled
immediately, starts as soon as Scheduler can run it, executes the specified
number of iterations, and remains in the schema's Scheduler job list after
completion (`AUTO_DROP` is disabled).

```sql
SET SERVEROUTPUT ON

-- Create a background job: name, iterations, seconds between iterations,
-- average DML rows per iteration.
EXEC create_commerce_activity_job('COMMERCE_LOAD_01', 10000, 3, 5.5);

-- List Scheduler jobs for SIMULATE_COMMERCE_ACTIVITY.
EXEC list_commerce_activity_jobs;

-- Stop and disable a pending or running job; it remains listed.
EXEC stop_commerce_activity_job('COMMERCE_LOAD_01');

-- Remove the job. FORCE also stops it if it is still running.
EXEC remove_commerce_activity_job('COMMERCE_LOAD_01');
```

The list procedure reports the job state, enabled status, run/failure counts,
and last start time. `STOP` disables the job and force-stops it if running;
it does not resume automatically. `REMOVE` drops the job and force-stops it
if necessary. These operations apply to jobs owned by the connected schema.

For run history and Scheduler error messages, query the job run details view:

```sql
SELECT log_date, status, error#, additional_info
FROM user_scheduler_job_run_details
WHERE job_name = 'COMMERCE_LOAD_01'
ORDER BY log_date DESC;
```

The activity procedure's `DBMS_OUTPUT` is generated in the Scheduler worker
session and is not normally returned to the session that submitted the job.
Use Scheduler run details to inspect completion status and errors.