= TUTORIAL
---

This tutorial will walk you through a very simple sample program using
BtPgsql.

<b>1)</b> First we will need to set a database containing some bi-temporal
tables.  We will call this database 'sample'.  We could create this database
using :

  ruby -r postgres -e 'PGconn.new.exec "create database sample"'

or

  psql -c 'create database sample'

or

  createdb sample

<b>2)</b> Next we'll need to set up the <i>bi-temporal system relations</i>
required by BtPgsql using :

  psql -d sample -f ./sql/btschema.sql

or

  unix prompt > psql -d sample

  sample=# \i ./sql/btschema.sql

Do not be alarmed at errors complaining about not being able to drop certain
tables, the btschema.sql file attempts to drop the relevant tables before
creating them.

<b>3)</b> We next will need to create some bi-temporal relations and describe
their relationships.  The relations and relationships required to run the
sample program are defined in link:../sql/sample_simple.sql.  You will need to
install these definitions into the sample database using :

  psql -d sample -f ./sql/sample_simple.sql

or

  unix prompt > psql -d sample

  sample=# \i ./sql/sample_simple.sql


<b>4)</b> At this point you are ready to run link:../sample/simple.rb using :

  ./sample/simple.rb

or

  ruby ./sample/simple.rb

Note that you may chose to use a different database name than _sample_ for
this tutorial, in which case you would simply use :

  ./sample/simple.rb your_database_name

or

  ruby ./sample/simple.rb your_database_name


To run the link:../sample/simple.rb example program.


---
==== The details of the example program are doccumented in the program itself - link:../sample/simple.rb


---
If you repeat the above procedures to set up a database and it's BtPgsql
system tables, and have the <i>rubyunit</i> testing framework from the RAA
(http://raa.ruby-lang.org/list.rhtml?name=rubyunit) installed, you may run the
unit test included with the distribution - link:../test/btpgsql.rb.  

For example, one could :

  createdb btpgsql_unit_test

  psql -d btpgsql_unit_test -f ./sql/btschema.sql

  psql -d btpgsql_unit_test -f ./sql/btpgsql_unit_test.sql

  ruby ./test/btpgsql.rb btpgsql_unit_test


Note that simply running

  ./test/btpgsql.rb

or

  ruby ./test/btpgsql.rb

with *no* arguments will _attempt_ to create, populate, and describe the
database for you.

---
<b>If any of these should fail, please contact me immeadiately @
mailto:ahoward@fsl.noaa.gov</b>
---