Read Me

DBFeeder 
======= 
For the most up to date information, please visit http://dbfeeder.sf.net/ 
DBFeeder is written and maintained by Davide Conti <daconti.mail@gmail.com>
Please avoid using this software in production databases.
Please read carefully the disclaimer before start using it. 

Description 
=========== 
This is DBFeeder, a perl script based database engine to fill databases with 
highly customizable synthetic data. This is especially useful if you are doing 
first time db-process developments but you don't have data on which they can 
work on.
DBFeeder is very easy to use, in few clicks you get lots of tables filled and 
you can immediately start testing your processes.

Requirements 
============
* Database: 
	* Oracle 12 or later.
	* At least one db-account with create table grant and select_catalog_role. 

* Perl: 
	* One of the latest Perl installations (5.8  and above) 
	* DBI package with either DBI::ODBC or DBI::Oracle.
	* Data-Generate package 0.01 and above.
	* Parse::RecDescent 1.94 and above.
	* Other perl libaries (easy to get and install), 
      for a complete list of libraries see http://dbfeeder.sf.net/requirements/ 

Installation
============ 
* Download the latest version of DBFeeder.zip (http://dbfeeder.sf.net/download/)
* Copy the zip file in a directory of your choice and unpack there the zip file.
* Open a command line terminal and change to the DBFeeder directory.
* To start DBFeeder type now: 

		perl  -ws -Ilib lib/Data/DBFeeder.pm

* If everything is OK you should see a text based menu with different options.
* Type now E for exit and follow next section's instructions.

Configuration
============= 
Before using DBFeeder you need to choose the proper DBI Driver:
* Start again DBFeeder as described above.
* Choose now 'GLOBAL SETUP MENU' from the text based menu options. 
* Choose now the option 'set dbi driver' and change the default (dbi::Oracle) 
  to your own dbi driver module. 

In addition, if the sqlplus command is not in your standard path, you have to 
enter the sqlplus path location. Proceed as follows:
* In the 'GLOBAL SETUP MENU' choose now the option 'set sqlplus' (most probably 
  you have to type N to go to the next page).
* Change now the default (sqlplus) to your sqlplus path (ex C:/oracle/sqlplus).
   

First Project
============= 
To let you familiarize with DBFeeder we prepared two demos that you can install 
from scratch in an empty database schema. We will go now through one of them 
(HR_DEMO).

At first we need to create the project 'HR_DEMO'. Proceed as follows:
* Start DBFeeder. Choose 'PROJECT MENU' -> 'CREATE DEMO PROJECTS' 
   -> 'CREATE PROJECT HR_DEMO'.
* Change now DB connection parameters according to your database account 
  (pls caution! all existing tables of this accounts will be deleted).
  At the end choose 'TEST DB CONNECTION' to check that db connection is working.
  
* Choose a directory for the 'HR_DEMO' project. DBFeeder will use this directory
   to store and retrieve project data.
* Choose 'MAKE PROJECT' and follow interactive instructions.If creation is 
  successful you should see the message: 
   
       'DBFEEDER PROJECT HR_DEMO CREATION COMPLETED'

After creation of HR_DEMO you need to load the project into memory in order 
to create data. Proceed now as follows:
* From the 'CREATE PROJECT HR_DEMO' choose now 'back to previous' until you get 
   to the 'PROJECT' menu.
* Choose now 'LOAD PROJECT' -> 'HR DEMO'.If loading is successful you should see  
    
    '- PROJECT HR_DEMO ACTIVE-' 
   
   in the top of the menu.

Finally we will now create a first data-set and insert it into the database.
Proceed as follows:
* From 'LOAD PROJECT' go back until you get into the 'MAIN MENU'. 
    Choose now 'DATA MENU' -> 'generate sql scripts'. 
* Type 'A' for automatic cardinality setup. 
* Give now 200 as the maximal cardinality to be chosen. 
* Wait until you get the message 'Data generation completed press a key to continue' 
* Choose now 'run sql insert script'. You should get now 
   a kind of message like this:
 
		run sql script: ...INS_TABS_HR_DEMO.SQL for user XXXX

		SQL*Plus: Release ....

		Connected to:
		Oracle Database....

		INSERT DATA INTO JOBS
		INSERT DATA INTO REGIONS
		INSERT DATA INTO COUNTRIES
		INSERT DATA INTO LOCATIONS
		INSERT DATA INTO DEPARTMENTS
		INSERT DATA INTO EMPLOYEES
		INSERT DATA INTO JOB_HISTORY
		Disconnected from Oracle Database...

		sql done
		press a key to continue

* Check now in the database: the tables JOBS, REGIONS, COUNTRIES, LOCATIONS,
  DEPARTMENTS, EMPLOYEES and JOB_HISTORY should be filled with some data!  

Customize your data
=================== 
* Go in the 'HR_DEMO' project directory. Look for the file COUNTRY_NAME.cfg in 
   the project input directory. It should have a path like  

      ./Input/*/HR_DEMO/COUNTRIES/COUNTRY_NAME/COUNTRY_NAME.cfg  

* Edit the file and replace contents with the string below: 
   
   STRING  'ITALY' (25%) | 'GERMANY' (25%) | 'USA' (25%) | 'SWITZERLAND' (25%);

* Restart now DBFeeder and reload project 'HR_DEMO' so that changes in
   configuration files are detected. 
* Go in the 'DATA MENU', choose 'run sql cleanup script', 
* Choose now 'DATA MENU' -> 'generate sql scripts'. 
* Type 'A' for automatic cardinality setup. 
* Give 200 as the maximal cardinality to be chosen. 
* Choose 'run sql insert script' and check that you dont get error messages. 
 
* Check now the column COUNTRY_NAME  in the table COUNTRIES. You should now see 
  only the countries 'ITALY', 'GERMANY', 'USA' and 'SWITZERLAND' with more or 
  less equal distributions.

DONE! Read now the online manual (http://dbfeeder.sf.net/manual/) for more 
extensive instructions about customizing your data.


Disclaimer
==========
THERE IS NO WARRANTY OR GUARANTEE OF ANY KIND (PARTICULAR THAT IT WORKS AS 
ADVERTISED). THE SOFTWARE IS SUPPLIED "AS IS, WHERE IS", AND IT IS PROVIDED IN 
GOOD FAITH. WHILE WELCOMING SUGGESTIONS FOR IMPROVEMENT (SEE BELOW), THE 
AUTHOR(S) OF THIS PACKAGE ACCEPTS NO RESPONSIBILITY FOR LOSSES INCURRED, AND 
OFFERS NO GUARANTEES ABOUT SUITABILITY OF THE SOFTWARE FOR ANY SPECIFIC PURPOSE. 
IN PARTICULAR PLEASE AVOID USING THIS SOFTWARE IN PRODUCTION DATABASES!

Contact information
===================
For suggestions, error & bug traces, improvements, or if you have written some 
tutorial/manual (in the language of your choice) which you like to be included 
in the installation package, etc. you can contact us at daconti.mail@gmail.com.