NAME

       Alzabo::Create::Schema - Schema objects for schema creation

SYNOPSIS

         use Alzabo::Create::Schema;

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 RDBMS, create relationships between
       tables, etc.

   Instantiation
       Every schema keeps track of whether it has been instantiated or not.  A schema that is
       instantiated is one that exists in an RDBMS backend.  This can be done explicitly by
       calling the schema's "create()" method.  It is also implicitly set when a schema is
       created as the result of reverse engineering.

       The most important effect of instantiation is that once a schema is instantiated, the way
       it generates SQL for itself changes.  Before it is instantiated, if you ask it to generate
       SQL via the "make_sql()" the method, it will generate the set of SQL statements that are
       needed to create the schema from scratch.

       After it is instantiated, the schema will instead generate the SQL necessary to convert
       the version in the RDBMS backend to match the object's current state.  This can be thought
       of as a SQL 'diff'.

       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
       "make_sql()" method, you will not get any SQL.  This is because the schema knows that it
       is instantiated and it also knows that it is the same as the version in the RDBMS, so no
       SQL is necessary.

       You can use the "set_instantiated()" method method to change whether or not the schem
       thinks it is instantiated.

INHERITS FROM

       "Alzabo::Schema"

       Note: all relevant documentation from the superclass has been merged into this document.

METHODS

   Constructors
   new
       This constructor takes the following parameters:

       •   name => $name

           This is the name of the schema, and will be the name of the database in the RDBMS.

       •   rdbms => $rdbms

           This is a string identifying the RDBMS.  The allowed values are returned from the
           "Alzabo::RDBMSRules->available" method.  These are values such as 'MySQL',
           'PostgreSQL', etc.

       It returns a new "Alzabo::Create::Schema" object.

       Throws: "Alzabo::Exception::Params", "Alzabo::Exception::System"

   load_from_file
       This constructor takes the following parameters:

       •   name => $schema_name

       Returns a schema object previously saved to disk, as specified by the "name" parameters.

       Throws: "Alzabo::Exception::Params", "Alzabo::Exception::System"

   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 SQL diffs, as opposed to SQL to create the
       database from scratch.

       The schema object returned by this method will have its instantiated attribute set as
       true.

       It takes the following parameters:

       •   name => $name

           The name of the database with which to connect.

       •   rdbms => $rdbms

           See the "new" method documentation for an explanation of this parameter.

       In addition, this method takes any parameters that can be used when connecting to the
       RDBMS, including "user", "password", "host", and "port".

       Returns a new "Alzabo::Create::Schema" object.

   Other Methods
   name
       Returns a string containing the name of the schema.

   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 "save_to_file()" immediately
       afterwards if you want to make sure you have a copy of the schema saved.

       Throws: "Alzabo::Exception::Params", "Alzabo::Exception::RDBMSRules",
       "Alzabo::Exception::System"

   table ($name)
       Returns an "Alzabo::Create::Table" object representing the specified table.

       An "Alzabo::Exception::Params" exception is throws if the schema does not contain the
       table.

   tables (@optional_list)
       If no arguments are given, this method returns a list of all "Alzabo::Create::Table"
       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).

       An "Alzabo::Exception::Params" exception is throws if the schema does not contain one or
       more of the specified tables.

   has_table ($name)
       Returns a boolean value indicating whether the table exists in the schema.

   make_table
       This method makes a new table and adds it to the schema, the parameters given are passed
       directly to the "Alzabo::Create::Table->new()" method.  The "schema" parameter is filled
       in automatically.

       If a "before" or "after" parameter is given then the "move_table()" method will be called
       to move the new table to the appropriate position.

       Returns a new "Alzabo::Create::Table" object.

       Throws: "Alzabo::Exception::Params", "Alzabo::Exception::RDBMSRules"

   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.

       Throws: "Alzabo::Exception::Params"

   add_table
       Add a table to the schema.

       This methods takes the following parameters:

       •   table => "Alzabo::Create::Table" object

       •   after => "Alzabo::Create::Table" object (optional)

           ... or ...

       •   before => "Alzabo::Create::Table" object (optional)

       Returns a new "Alzabo::Create::Table" object.

       Throws: "Alzabo::Exception::Params"

   move_table
       Allows you to change the order of the tables as they are stored in the schema.

       This method takes the following parameters:

       •   table => "Alzabo::Create::Table" object

           The table to move.

           and either ...

       •   before => "Alzabo::Create::Table" object

           Move the table before this table

           ... or ...

       •   after => "Alzabo::Create::Table" object

           Move the table after this table.

       Throws: "Alzabo::Exception::Params"

   add_relationship
       Creates a relationship between two tables.  This involves creating
       "Alzabo::Create::ForeignKey" objects in both tables.  If the "columns_from" and
       "columns_to" parameters are not specified then the schema object attempts to calculate the
       proper values for these attributes.

       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 "table_from" is treated as being the dependent
       table for the purposes of determining

       If no columns with the same names exist in the other table, then columns with those names
       will be created.  Otherwise, "add_relationship()" changes the dependent columns so that
       their "Alzabo::Create::ColumnDefinition" 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.

       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 "columns_from" parameter
       should correspond to the first column in hte "columns_to" parameter and so on.

       The number of columns given in "columns_from" and "columns_to" must be the same except
       when creating a many to many relationship.

       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.

       This method takes the following parameters:

       •   table_from => "Alzabo::Create::Table" object (optional if columns_from is provided)

       •   table_to => "Alzabo::Create::Table" object (optional if columns_to is provided)

       •   columns_from => "Alzabo::Create::Column" object (optional if table_from is provided)

       •   columns_to => "Alzabo::Create::Column" object (optional if table_to is provided)

       •   cardinality => [1, 1], [1, 'n'], ['n', 1], or ['n', 'n']

       •   name => $name

           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.

       •   from_is_dependent => $boolean

       •   to_is_dependent => $boolean

       •   comment => $comment

       Throws: "Alzabo::Exception::Params"

   create
       This method causes the schema to connect to the RDBMS, create a new database if necessary,
       and then execute whatever SQL 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 SQL 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.

       Wherever possible, existing data will be preserved.

       This method takes any parameters that can be used when connecting to the RDBMS, including
       "schema_name", "user", "password", "host", and "port".

       If a "schema_name" parameter is given, then this will be the name given to the schema in
       the RDBMS.

       Warning: Every time you call "create()" or "sync_backend()", 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 "sync_backend()" to sync the RDBMS schema,
       since the schema's internal notion of it's state may be incorrect.

   instantiated
       Returns a boolean value indicating whether the schema has been created in an RDBMS
       backend, otherwise it is false.

   set_instantiated ($bool)
       Set the schema's instantiated attribute as true or false.

       Throws: "Alzabo::Exception::Params"

   make_sql
       Returns an array containing the SQL statements necessary to either create the database
       from scratch or update the database to match the schema object.  See the "create()" method
       for more details.

   drop
       Drops the database/schema from the RDBMS.  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 "delete()" method.

       This method takes any parameters that can be used when connecting to the RDBMS, including
       "schema_name", "user", "password", "host", and "port".

       Throws: "Alzabo::Exception::Driver"

   sync_backend
       This method will look at the schema as it exists in the RDBMS 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 RDBMS backend, then this method is
       equivalent to the "create()" method.

       After this method is called, the schema will be considered to be instantiated.

       This method will never be perfect because some RDBMS backends alter table definitions as
       they are created.  For example, MySQL has default column "lengths" for all of its integer
       columns.  Alzabo tries to account for these.

       In the end, this means that Alzabo may never think that a schema in the RDBMS exactly
       matches the state of the Alzabo schema object.  Even immediately after running this
       method, running it again may still cause it to execute SQL commands.  Fortunately, the SQL
       it generates will not cause anything to break.

       This method takes any parameters that can be used when connecting to the RDBMS, including
       "schema_name", "user", "password", "host", and "port".

       Throws: "Alzabo::Exception::Driver"

   sync_backend_sql
       If there is no corresponding schema in the RDBMS backend, then this method returns the SQL
       necessary to create the schema from scratch.

       This method takes any parameters that can be used when connecting to the RDBMS, including
       "schema_name", "user", "password", "host", and "port".

       Throws: "Alzabo::Exception::Driver"

   delete
       Removes the schema object from disk.  It does not delete the database from the RDBMS.  To
       do this you must call the "drop" method first.

       Throws: "Alzabo::Exception::System"

   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.

       It takes the following parameters:

       •   name => $name

       This method returns a new Alzabo::Create::Schema object.

       Throws: "Alzabo::Exception::Params", "Alzabo::Exception::RDBMSRules"

   save_to_file
       Saves the schema to a file on disk.

       Throws: "Alzabo::Exception::System"

   runtime_clone
       Returns a new "Alzabo::Runtime::Schema" object based on the current schema.

   is_saved
       Returns true if the schema has been saved to disk.

   begin_work
       Starts a transaction.  Calls to this function may be nested and it will be handled
       properly.

   rollback
       Rollback a transaction.

   commit
       Finishes a transaction with a commit.  If you make multiple calls to "begin_work()", make
       sure to call this method the same number of times.

   run_in_transaction ( sub { code... } )
       This method takes a subroutine reference and wraps it in a transaction.

       It will preserve the context of the caller and returns whatever the wrapped code would
       have returned.

   driver
       Returns the "Alzabo::Driver" object for the schema.

   rules
       Returns the "Alzabo::RDBMSRules" object for the schema.

   sqlmaker
       Returns the "Alzabo::SQLMaker" object for the schema.

AUTHOR

       Dave Rolsky, <autarch@urth.org>