.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .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. \*(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- .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" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "Alzabo::Create::Schema 3pm" .TH Alzabo::Create::Schema 3pm "2015-05-24" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Alzabo::Create::Schema \- Schema objects for schema creation .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Alzabo::Create::Schema; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class represents the whole schema. It contains table objects, which in turn contain columns, indexes, etc. It contains methods that act globally on the schema, including methods to save it to disk, create itself in an \s-1RDBMS,\s0 create relationships between tables, etc. .SS "Instantiation" .IX Subsection "Instantiation" Every schema keeps track of whether it has been instantiated or not. A schema that is instantiated is one that exists in an \s-1RDBMS\s0 backend. This can be done explicitly by calling the schema's \&\f(CW\*(C`create()\*(C'\fR method. It is also implicitly set when a schema is created as the result of reverse engineering. .PP The most important effect of instantiation is that once a schema is instantiated, the way it generates \s-1SQL\s0 for itself changes. Before it is instantiated, if you ask it to generate \s-1SQL\s0 via the \f(CW\*(C`make_sql()\*(C'\fR the method, it will generate the set of \s-1SQL\s0 statements that are needed to create the schema from scratch. .PP After it is instantiated, the schema will instead generate the \s-1SQL\s0 necessary to convert the version in the \s-1RDBMS\s0 backend to match the object's current state. This can be thought of as a \s-1SQL \s0'diff'. .PP While this feature is quite useful, it can be confusing too. The most surprising aspect of this is that if you create a schema via reverse engineering and then call the \f(CW\*(C`make_sql()\*(C'\fR method, you will not get any \s-1SQL. \s0 This is because the schema knows that it is instantiated and it also knows that it is the same as the version in the \s-1RDBMS,\s0 so no \s-1SQL\s0 is necessary. .PP You can use the \f(CW\*(C`set_instantiated()\*(C'\fR method method to change whether or not the schem thinks it is instantiated. .SH "INHERITS FROM" .IX Header "INHERITS FROM" \&\f(CW\*(C`Alzabo::Schema\*(C'\fR .PP Note: all relevant documentation from the superclass has been merged into this document. .SH "METHODS" .IX Header "METHODS" .SS "Constructors" .IX Subsection "Constructors" .SS "new" .IX Subsection "new" This constructor takes the following parameters: .IP "\(bu" 4 name => \f(CW$name\fR .Sp This is the name of the schema, and will be the name of the database in the \s-1RDBMS.\s0 .IP "\(bu" 4 rdbms => \f(CW$rdbms\fR .Sp This is a string identifying the \s-1RDBMS. \s0 The allowed values are returned from the \&\f(CW\*(C`Alzabo::RDBMSRules\->available\*(C'\fR method. These are values such as 'MySQL', 'PostgreSQL', etc. .PP It returns a new \f(CW\*(C`Alzabo::Create::Schema\*(C'\fR object. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR, \&\f(CW\*(C`Alzabo::Exception::System\*(C'\fR .SS "load_from_file" .IX Subsection "load_from_file" This constructor takes the following parameters: .IP "\(bu" 4 name => \f(CW$schema_name\fR .PP Returns a schema object previously saved to disk, as specified by the \&\*(L"name\*(R" parameters. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR, \&\f(CW\*(C`Alzabo::Exception::System\*(C'\fR .SS "reverse_engineer" .IX Subsection "reverse_engineer" Attempts to connect to a database and instantiate a new schema object based on information in the specified database. The returned object will have its instantiated value set to true so that subsequent changes will lead to \s-1SQL\s0 diffs, as opposed to \s-1SQL\s0 to create the database from scratch. .PP The schema object returned by this method will have its instantiated attribute set as true. .PP It takes the following parameters: .IP "\(bu" 4 name => \f(CW$name\fR .Sp The name of the database with which to connect. .IP "\(bu" 4 rdbms => \f(CW$rdbms\fR .Sp See the \f(CW\*(C`new\*(C'\fR method documentation for an explanation of this parameter. .PP In addition, this method takes any parameters that can be used when connecting to the \s-1RDBMS,\s0 including \*(L"user\*(R", \*(L"password\*(R", \*(L"host\*(R", and \&\*(L"port\*(R". .PP Returns a new \f(CW\*(C`Alzabo::Create::Schema\*(C'\fR object. .SS "Other Methods" .IX Subsection "Other Methods" .SS "name" .IX Subsection "name" Returns a string containing the name of the schema. .SS "set_name ($name)" .IX Subsection "set_name ($name)" Changes the schema name. Since schemas are saved on disk with filenames based on the schema name, this deletes the files for the old name. Call \f(CW\*(C`save_to_file()\*(C'\fR immediately afterwards if you want to make sure you have a copy of the schema saved. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR, \&\f(CW\*(C`Alzabo::Exception::RDBMSRules\*(C'\fR, \&\f(CW\*(C`Alzabo::Exception::System\*(C'\fR .SS "table ($name)" .IX Subsection "table ($name)" Returns an \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object representing the specified table. .PP An \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR exception is throws if the schema does not contain the table. .SS "tables (@optional_list)" .IX Subsection "tables (@optional_list)" If no arguments are given, this method returns a list of all \&\f(CW\*(C`Alzabo::Create::Table\*(C'\fR objects in the schema, or in a scalar context the number of such tables. If one or more arguments are given, returns a list of table objects with those names, in the same order given (or the number of such tables in a scalar context, but this isn't terribly useful). .PP An \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR exception is throws if the schema does not contain one or more of the specified tables. .SS "has_table ($name)" .IX Subsection "has_table ($name)" Returns a boolean value indicating whether the table exists in the schema. .SS "make_table" .IX Subsection "make_table" This method makes a new table and adds it to the schema, the parameters given are passed directly to the \f(CW\*(C`Alzabo::Create::Table\->new()\*(C'\fR method. The \*(L"schema\*(R" parameter is filled in automatically. .PP If a \*(L"before\*(R" or \*(L"after\*(R" parameter is given then the \&\f(CW\*(C`move_table()\*(C'\fR method will be called to move the new table to the appropriate position. .PP Returns a new \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR, \&\f(CW\*(C`Alzabo::Exception::RDBMSRules\*(C'\fR .ie n .SS "delete_table (""Alzabo::Create::Table"" object)" .el .SS "delete_table (\f(CWAlzabo::Create::Table\fP object)" .IX Subsection "delete_table (Alzabo::Create::Table object)" Removes the given table from the schema. This method will also delete all foreign keys in other tables that point at the given table. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR .SS "add_table" .IX Subsection "add_table" Add a table to the schema. .PP This methods takes the following parameters: .IP "\(bu" 4 table => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object .IP "\(bu" 4 after => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object (optional) .Sp \&... or ... .IP "\(bu" 4 before => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object (optional) .PP Returns a new \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR .SS "move_table" .IX Subsection "move_table" Allows you to change the order of the tables as they are stored in the schema. .PP This method takes the following parameters: .IP "\(bu" 4 table => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object .Sp The table to move. .Sp and either ... .IP "\(bu" 4 before => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object .Sp Move the table before this table .Sp \&... or ... .IP "\(bu" 4 after => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object .Sp Move the table after this table. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR .SS "add_relationship" .IX Subsection "add_relationship" Creates a relationship between two tables. This involves creating \&\f(CW\*(C`Alzabo::Create::ForeignKey\*(C'\fR objects in both tables. If the \*(L"columns_from\*(R" and \*(L"columns_to\*(R" parameters are not specified then the schema object attempts to calculate the proper values for these attributes. .PP To do this, Alzabo attempts to determine the dependencies of the tables. If you have specified a cardinality of 1..1, or n..1, in cases where both tables are independent, or where they are both dependent then the \*(L"table_from\*(R" is treated as being the dependent table for the purposes of determining .PP If no columns with the same names exist in the other table, then columns with those names will be created. Otherwise, \&\f(CW\*(C`add_relationship()\*(C'\fR changes the dependent columns so that their \&\f(CW\*(C`Alzabo::Create::ColumnDefinition\*(C'\fR objects are the same as the columns in the table upon which they are dependent, meaning that changes to the type of one column affects both at the same time. .PP If you want to make a multi-column relationship, the assumption is that the order of the columns is significant. In other words, the first column in the \*(L"columns_from\*(R" parameter should correspond to the first column in hte \*(L"columns_to\*(R" parameter and so on. .PP The number of columns given in \*(L"columns_from\*(R" and \*(L"columns_to\*(R" must be the same except when creating a many to many relationship. .PP If the cardinality is many to many then a new table will be created to link the two tables together. This table will contain the primary keys of both the tables passed into this function. It will contain foreign keys to both of these tables as well, and these tables will be linked to this new table. .PP This method takes the following parameters: .IP "\(bu" 4 table_from => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object (optional if columns_from is provided) .IP "\(bu" 4 table_to => \f(CW\*(C`Alzabo::Create::Table\*(C'\fR object (optional if columns_to is provided) .IP "\(bu" 4 columns_from => \f(CW\*(C`Alzabo::Create::Column\*(C'\fR object (optional if table_from is provided) .IP "\(bu" 4 columns_to => \f(CW\*(C`Alzabo::Create::Column\*(C'\fR object (optional if table_to is provided) .IP "\(bu" 4 cardinality => [1, 1], [1, 'n'], ['n', 1], or ['n', 'n'] .IP "\(bu" 4 name => \f(CW$name\fR .Sp If provided, and if the specified cardinality requires the creation of a linking table, this string will be used to name that linking table. Otherwise, the new table's name will be synthesized from the names of those it's linking. .IP "\(bu" 4 from_is_dependent => \f(CW$boolean\fR .IP "\(bu" 4 to_is_dependent => \f(CW$boolean\fR .IP "\(bu" 4 comment => \f(CW$comment\fR .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR .SS "create" .IX Subsection "create" This method causes the schema to connect to the \s-1RDBMS,\s0 create a new database if necessary, and then execute whatever \s-1SQL\s0 is necessary to make that database match the current state of the schema object. If the schema has been instantiated previously, then it will generate the \&\s-1SQL\s0 necessary to change the database. This may be destructive (dropping tables, columns, etc) so be careful. This will cause the schema to be marked as instantiated. .PP Wherever possible, existing data will be preserved. .PP This method takes any parameters that can be used when connecting to the \s-1RDBMS,\s0 including \*(L"schema_name\*(R", \*(L"user\*(R", \*(L"password\*(R", \*(L"host\*(R", and \&\*(L"port\*(R". .PP If a \*(L"schema_name\*(R" parameter is given, then this will be the name given to the schema in the \s-1RDBMS.\s0 .PP \&\fBWarning\fR: Every time you call \f(CW\*(C`create()\*(C'\fR or \f(CW\*(C`sync_backend()\*(C'\fR, the schema will consider itself to have been instantiated. This will affect how schema diffs are generated. After this, you will almost certainly need to use \f(CW\*(C`sync_backend()\*(C'\fR to sync the \s-1RDBMS\s0 schema, since the schema's internal notion of it's state may be incorrect. .SS "instantiated" .IX Subsection "instantiated" Returns a boolean value indicating whether the schema has been created in an \s-1RDBMS\s0 backend, otherwise it is false. .SS "set_instantiated ($bool)" .IX Subsection "set_instantiated ($bool)" Set the schema's instantiated attribute as true or false. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR .SS "make_sql" .IX Subsection "make_sql" Returns an array containing the \s-1SQL\s0 statements necessary to either create the database from scratch or update the database to match the schema object. See the \f(CW\*(C`create()\*(C'\fR method for more details. .SS "drop" .IX Subsection "drop" Drops the database/schema from the \s-1RDBMS. \s0 This will cause the schema to be marked as not instantiated. This method does not delete the Alzabo files from disk. To do this, call the \f(CW\*(C`delete()\*(C'\fR method. .PP This method takes any parameters that can be used when connecting to the \s-1RDBMS,\s0 including \*(L"schema_name\*(R", \*(L"user\*(R", \*(L"password\*(R", \*(L"host\*(R", and \&\*(L"port\*(R". .PP Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR .SS "sync_backend" .IX Subsection "sync_backend" This method will look at the schema as it exists in the \s-1RDBMS\s0 backend, and make any changes that are necessary in order to make this backend schema match the Alzabo schema object. If there is no corresponding schema in the \s-1RDBMS\s0 backend, then this method is equivalent to the \&\f(CW\*(C`create()\*(C'\fR method. .PP After this method is called, the schema will be considered to be instantiated. .PP This method will never be perfect because some \s-1RDBMS\s0 backends alter table definitions as they are created. For example, MySQL has default column \*(L"lengths\*(R" for all of its integer columns. Alzabo tries to account for these. .PP In the end, this means that Alzabo may never think that a schema in the \s-1RDBMS\s0 exactly matches the state of the Alzabo schema object. Even immediately after running this method, running it again may still cause it to execute \s-1SQL\s0 commands. Fortunately, the \s-1SQL\s0 it generates will not cause anything to break. .PP This method takes any parameters that can be used when connecting to the \s-1RDBMS,\s0 including \*(L"schema_name\*(R", \*(L"user\*(R", \*(L"password\*(R", \*(L"host\*(R", and \&\*(L"port\*(R". .PP Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR .SS "sync_backend_sql" .IX Subsection "sync_backend_sql" If there is no corresponding schema in the \s-1RDBMS\s0 backend, then this method returns the \s-1SQL\s0 necessary to create the schema from scratch. .PP This method takes any parameters that can be used when connecting to the \s-1RDBMS,\s0 including \*(L"schema_name\*(R", \*(L"user\*(R", \*(L"password\*(R", \*(L"host\*(R", and \&\*(L"port\*(R". .PP Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR .SS "delete" .IX Subsection "delete" Removes the schema object from disk. It does not delete the database from the \s-1RDBMS. \s0 To do this you must call the \f(CW\*(C`drop\*(C'\fR method first. .PP Throws: \f(CW\*(C`Alzabo::Exception::System\*(C'\fR .SS "clone" .IX Subsection "clone" This method creates a new object identical to the one that the method was called on, except that this new schema has a different name, it does not yet exist on disk, its instantiation attribute is set to false. .PP It takes the following parameters: .IP "\(bu" 4 name => \f(CW$name\fR .PP This method returns a new Alzabo::Create::Schema object. .PP Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR, \&\f(CW\*(C`Alzabo::Exception::RDBMSRules\*(C'\fR .SS "save_to_file" .IX Subsection "save_to_file" Saves the schema to a file on disk. .PP Throws: \f(CW\*(C`Alzabo::Exception::System\*(C'\fR .SS "runtime_clone" .IX Subsection "runtime_clone" Returns a new \f(CW\*(C`Alzabo::Runtime::Schema\*(C'\fR object based on the current schema. .SS "is_saved" .IX Subsection "is_saved" Returns true if the schema has been saved to disk. .SS "begin_work" .IX Subsection "begin_work" Starts a transaction. Calls to this function may be nested and it will be handled properly. .SS "rollback" .IX Subsection "rollback" Rollback a transaction. .SS "commit" .IX Subsection "commit" Finishes a transaction with a commit. If you make multiple calls to \&\f(CW\*(C`begin_work()\*(C'\fR, make sure to call this method the same number of times. .SS "run_in_transaction ( sub { code... } )" .IX Subsection "run_in_transaction ( sub { code... } )" This method takes a subroutine reference and wraps it in a transaction. .PP It will preserve the context of the caller and returns whatever the wrapped code would have returned. .SS "driver" .IX Subsection "driver" Returns the \f(CW\*(C`Alzabo::Driver\*(C'\fR object for the schema. .SS "rules" .IX Subsection "rules" Returns the \f(CW\*(C`Alzabo::RDBMSRules\*(C'\fR object for the schema. .SS "sqlmaker" .IX Subsection "sqlmaker" Returns the \f(CW\*(C`Alzabo::SQLMaker\*(C'\fR object for the schema. .SH "AUTHOR" .IX Header "AUTHOR" Dave Rolsky,