.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bigtop::Backend::SQL 3"
.TH Bigtop::Backend::SQL 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Bigtop::Backend::SQL \- defines legal keywords in table and field blocks
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
If you are making an \s-1SQL\s0 generating backend:
.PP
.Vb 1
\&    use Bigtop::Backend::SQL;
.Ve
.PP
This specifies the valid keywords for the \s-1SQL\s0 generating backend.
.PP
If you need additional keywords which are generally useful, add them
here (and send in a patch).  If you need backend specific keywords, register
them within your backend module.  Note that only keywords affecting
the \s-1SQL\s0 should be put here.  But, fields have other keywords which
affect things like how they look in html forms and whether they are fetched
by default.  Register those keywords in Bigtop::Control:: or
Bigtop::Model:: modules.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you are using a Bigtop backend which generates \s-1SQL\s0, you should
read this document to find out what the valid keywords inside table
and field blocks are.
.PP
If you are writing a Bigtop backend to generate \s-1SQL\s0, you should use
this module.  That will register the standard table and field keywords
with the Bigtop parser.
.SH "BASIC STRUCTURE"
.IX Header "BASIC STRUCTURE"
A bigtop app block could look like this:
.PP
.Vb 6
\&    app name {
\&        table name {
\&            field name {
\&            }
\&        }
\&    }
.Ve
.SH "KEYWORDS"
.IX Header "KEYWORDS"
Inside the table, you can include the following keywords:
.IP "sequence" 4
.IX Item "sequence"
This must be the name of a valid sequence defined with an app level
sequence block.  Any field whose 'is' list includes auto (which is an
alias for assign_by_sequence) will use this sequence.
.IP "data" 4
.IX Item "data"
Allows you to include data for table population.  Include
as many column name => value pairs as you need.  Repeat for each
row you want to insert.  They will become \s-1INSERT\s0 \s-1INTO\s0 statements.
.Sp
Example:
.Sp
.Vb 10
\&    table payeepayor {
\&        field id    { is int, primary_key, assign_by_sequence; }
\&        field name  { is varchar; }
\&        sequence payeepayor_seq;
\&        data
\&            name => `Gas Company`;
\&        data
\&            id   => 2,
\&            name => `Electric Company`;
\&    }
.Ve
.Sp
Note that it is not wise to manually assign ids for tables with sequence
defaults.  I show it here as a simple syntactic example.
.Sp
Be somewhat careful with quoting.  Numbers won't be quoted, but
strings will be.  If you need internal quotes, escape them as in:
.Sp
.Vb 1
\&    data name => `Phil\e's Business Center`;
.Ve
.Sp
Double quotes don't need escaping, since the value will be single quoted.
.PP
Inside the field you may include
.IP "is (required)" 4
.IX Item "is (required)"
This defines the basic \s-1SQL\s0 declaration for the column.  Provide a
comma separated list of \s-1SQL\s0 column definition phrases or put them
all in a back quoted string or use some combination of those.
There are some keywords you can use, these are translated by the
backend to their proper equivalents:
.RS 4
.IP "int" 4
.IX Item "int"
Short for int4.
.IP "primary_key" 4
.IX Item "primary_key"
Not very short for \s-1PRIMARY\s0 \s-1KEY\s0.
.IP "assign_by_sequence" 4
.IX Item "assign_by_sequence"
Short for defaults to the next value from the sequence for this table.
To use this, you must have a defined sequence for the table and that
sequence must be defined at the app level.  (Defining it twice seems odd
to me, but some tables must share an index.  The app level definition
creates the sequence, as in it generates '\s-1CREATE\s0 \s-1SEQUENCE\s0...'.  The table
level definition ties this table to a sequence, as in it generates
a default clause with the sequence in it.)
.IP "auto" 4
.IX Item "auto"
A pure synonymn for assign_by_sequence, for those who refuse to type
so long a keyword.
.RE
.RS 4
.RE
.IP "update_with" 4
.IX Item "update_with"
Not currently supported.
.IP "refers_to" 4
.IX Item "refers_to"
This marks the column as a foreign key (whether a genuine \s-1SQL\s0 foreign
key is used is up to the backend).  Currently, you can only specify the
table this column points to.  The assumption about which column varies
depending on who's doing the assuming.  For example, Class::DBI assumes
the column refers to the primary key of the other table.  Gantry makes
the tacit assumption that the primary key is the single column called id.
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow <crow.phil@gmail.com>
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (C) 2005 by Phil Crow
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.