\name{createDBTable}
\alias{createDBTable}
\title{Creating a PgSQL database table}
\description{
  \code{createDBTable} creates a PostgreSQL data base table with primary key and possible foreign keys if needed (to guarantee the referencial integrity).
}
\usage{
createDBTable(conn, name=NULL, attributes=NULL, data.types=NULL, options=NULL, references=NULL, references.options=NULL, no.clobber=TRUE, auto.pk=TRUE, no.transaction=FALSE,silent=FALSE)
}
\arguments{
  \item{conn}{A connection object (create it with the dbConnect.PgSQL.conn function from the package RdbiPgSQL)}
  \item{name}{The table name}
  \item{attributes}{a vector containing the attribute names for the table}
  \item{data.types}{a vector specifying the data type for each attribute. If not submitted every column attribute is set to the TEXT data type. The data types can be defined by submitting a vector with the SQL data types for the attributes. Valid data types are: TEXT for character, BOOL for logical, REAL for numeric (real, for integer also INTEGER can be submitted). If the data types are all the same for all attributes, only one data type can be submitted (with the SQL data types above or, in the case it is not(!) a character an exemplary value can be submitted (e.g. \code{data.types=2}, so the data types for all attributes in the database table are set to REAL)).}
  \item{options}{optional, some advanced options for the attributes. If submitted it must have the same length as the attributes argument.}
  \item{references}{the table name(s) where the foreign key(s) should point to.}
  \item{references.options}{a vector with the same length of references, that allows to specify some options for the refernces (for example if one wants to allow foreign keys to get a NULL value, for example if no row in the references table exists where this row can reference to as references.options a "" can be submitted. If nothing is submitted (the default case), for every reference (foreign key) the constraint NOT NULL will be inserted, so no NULL references are allowed.)}
  \item{no.clobber}{if already existant tables with the same name should be deleted, default is FALSE}
  \item{auto.pk}{if a primary key for this table should be create automatically (default is TRUE, so a autoincrementing primary key will be created for that table. Everytime a new row is inserted into the table, the primary key will be created automatically).}
  \item{no.transaction}{if the whole call should be performed into a TRANSACTION, so if any error occurrs during the processing of the function, the database will not be touched. The default value is TRUE, so the function is quite robust.}
  \item{silent}{if the function should not check wether or not the table does already exist.}
}
\details{
creates a PostgreSQL database table, with the possibility to generate a primary key column that is incremented automatically with each insertion of data. Also foreign keys, that are references to other tables will be generated. So the referential integrity of the data in the tables is warranted. Advanced options can be specified for the tables attributes too (such as the keyword UNIQUE for a column).
}
\references{}
\author{Johannes Rainer}

\seealso{
%    \code{\link{dbWriteTable}},
    \code{\link{insertIntoTable}},
    \code{\link{updateDBTable}}
}

\examples{
  ## create a simple table called "individual", that references to a already existant table "species".
  \dontrun{Con <- dbConnect(PgSQL(),user="postgres",dbname="template1",host="localhost")}
  \dontrun{createDBTable(Con,name="individual",attributes=c("name","age"),data.types=c("TEXT","REAL"),references="species")}
  
  ## this call creates the database table "individual", with the primary key "individual_pk", the attributes 
  ## "name" and "age" and the foreign key "species_fk", that will, upon inserting of any data point to the 
  ## primary key of the table "species".
}

\keyword{data}