Alzabo::RDBMSRules - Base class for Alzabo RDBMS rulesets

       Dave Rolsky, <dave@urth.org>

perl v5.34.0                                       2022-06-14                            Alzabo::RDBMSRules(3pm)

       This class is the base class for all "Alzabo::RDBMSRules" modules.  To instantiate a subclass call this
       class's "new()" method.  See the "SUBCLASSING Alzabo::RDBMSRules" section for information on how to make
       a ruleset for the RDBMS of your choice.

available
       A list of names representing the available "Alzabo::RDBMSRules" subclasses.  Any one of these names would
       be appropriate as the "rdbms" parameter for the "Alzabo::RDBMSRules->new()" method.

   new
       The constructor always accepts one parameter, "rdbms", which is the name of the RDBMS to be used.

       Some subclasses may accept additional values.

       The constructor returns a new "Alzabo::RDBMSRules" object of the appropriate subclass.

       Throws: "Alzabo::Exception::Eval"

   schema_sql("Alzabo::Create::Schema"object)
       Returns a list of SQL statements which would create the given schema.

   index_sql("Alzabo::Create::Index"object)
       Returns a list of SQL statements to create the specified index.

   drop_table_sql("Alzabo::Create::Table"object)
       Returns a list of SQL statements to drop the specified table.

   drop_index_sql("Alzabo::Create::Index"object)
       Returns a list of SQL statements to drop the specified index.

   schema_sql_diff
       This method takes two parameters:

       •   new => "Alzabo::Create::Schema" object

       •   old => "Alzabo::Create::Schema" object

       This  method  compares the two schema objects and returns an array of SQL statements which turn the "old"
       schema into the "new" one.

   table_sql_diff
       This method takes two parameters:

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

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

       This method compares the two table objects and returns an array of SQL statements which  turn  the  "old"
       table into the "new" one.

   type_is_numeric("Alzabo::Column"object)
       Returns a boolean indicating whether or not the column is numeric (integer or floating point).

   quote_identifiers
       Returns  true  or  false  to  indicate  whether or not the generated DDL SQL statements should have their
       identifiers quoted or not.  This may be overridden by subclasses.  It defaults to false.

   can_alter_table_name
       If this is true, then when syncing a schema, the object will call "alter_table_name_sql()" to change  the
       table's name.  Otherwise it will call "recreate_table_sql()".

   can_alter_column_name
       If this is true, then when syncing a schema, the object will call "alter_column_name_sql()" to change the
       table's name.  Otherwise it will call "recreate_table_sql()".

   VirtualMethods
       The  following  methods  are  not  implemented  in  the  "Alzabo::RDBMSRules"  class  itself  and must be
       implemented in its subclasses.

   column_types
       Returns a list of valid column types.

   feature($feature)
       Given a string defining a feature, this method indicates whether or not the  given  RDBMS  supports  that
       feature.  By default, this method always returns false unless overridden in the subclass.

       Features that may be asked for:

       •   extended_column_types

           Column  types  that  must  be  input  directly  from  a user, as opposed to being chosen from a list.
           MySQL's ENUM and SET types are examples of such types.

       •   index_column_prefixes

           MySQL supports the notion of column prefixes in indexes, allowing you to index only a  portion  of  a
           large text column.

       •   fulltext_indexes

           This should be self-explanatory.

       •   functional_indexes

           Indexes on functions, as supported by PostgreSQL.

   validate_schema_name("Alzabo::Schema"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the schema's name is not valid.

   validate_table_name("Alzabo::Create::Table"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the table's name is not valid.

   validate_column_name("Alzabo::Create::Column"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the column's name is not valid.

   validate_column_type($type_as_string)
       Throws an "Alzabo::Exception::RDBMSRules" if the type is not valid.

       This method returns a canonized version of the type.

   validate_column_length("Alzabo::Create::Column"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the length or precision is not valid for the given column.

   validate_column_attribute
       This method takes two parameters:

       •   column => "Alzabo::Create::Column" object

       •   attribute => $attribute

       This method is a bit different from the others in that it takes an existing column object and a potential
       attribute.

       It throws an "Alzabo::Exception::RDBMSRules" if the attribute is is not valid for the column.

   validate_primary_key("Alzabo::Create::Column"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the column is not a valid primary key for its table.

   validate_sequenced_attribute("Alzabo::Create::Column"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the column cannot be sequenced.

   validate_index("Alzabo::Create::Index"object)
       Throws an "Alzabo::Exception::RDBMSRules" if the index is not valid.

   table_sql("Alzabo::Create::Table"object)
       Returns an array of SQL statements to create the specified table.

   column_sql("Alzabo::Create::Column"object)
       Returns an array of SQL statements to create the specified column.

   foreign_key_sql("Alzabo::Create::ForeignKey"object)
       Returns an array of SQL statements to create the specified foreign key.

   drop_column_sql("Alzabo::Create::Column"object)
       Returns an array of SQL statements to drop the specified column.

   drop_foreign_key_sql("Alzabo::Create::ForeignKey"object)
       Returns an array of SQL statements to drop the specified foreign key.

   column_sql_add("Alzabo::Create::Column"object)
       Returns an array of SQL statements to add the specified column.

   column_sql_diff
       This method takes two parameters:

       •   new => "Alzabo::Create::Column" object

       •   old => "Alzabo::Create::Column" object

       This  method  compares  the two table objects and returns an array of SQL statements which turn the "old"
       table into the "new" one.

   index_sql_diff
       This method takes two parameters:

       •   new => "Alzabo::Create::Index" object

       •   old => "Alzabo::Create::Index" object

       This method compares the two index objects and returns an array of SQL statements which  turn  the  "old"
       index into the "new" one.

   alter_primary_key_sql
       This method takes two parameters:

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

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

       This  method  compares the two table objects and returns an array of SQL statements which alter the "old"
       one's primary key to match the "new" one's.

   alter_table_name_sql("Alzabo::Create::Table"object)
       Given a table, this method  is  expected  to  change  the  table's  name  from  "$table->former_name"  to
       "$table->name".  This will only be called if the rules object returns true for "can_alter_table_name()".

   alter_column_name_sql("Alzabo::Create::Table"object)
       Given  a  column,  this  method  is  expected  to  change the table's name from "$column->former_name" to
       "$column->name".    This   will   only   be   called   if   the   rules   object   returns    true    for
       "can_alter_column_name()".

   recreate_table_sql
       This method takes two parameters:

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

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

       This method is expected to drop the old table and create the new one.

       However,  it must preserve all the data stored in the old table, excluding data in columns that are being
       dropped.  Additionally, if there are sequences associated with columns in the old table, they should  not
       be dropped.

       This  method  will  only be called if either "can_alter_table_name()" or "can_alter_column_name()" return
       false.

   reverse_engineer("Alzabo::Create::Schema"object)
       Given a schema object (which presumably has no tables), this method uses  the  schema's  "Alzabo::Driver"
       object to connect to an existing database and reverse engineer it into the appropriate Alzabo objects.

   type_is_integer("Alzabo::Column"object)
       Returns a boolean indicating whether or not the column is an integer type.

   type_is_floating_point("Alzabo::Column"object)
       Returns a boolean indicating whether or not the column is a floating point type.

   type_is_character("Alzabo::Column"object)
       Returns  a boolean indicating whether or not the column is a character type.  This is defined as any type
       which is defined to store text, regardless of length.

   type_is_date("Alzabo::Column"object)
       Returns a boolean indicating whether or not the column is a date type.  This is  not  true  for  datetime
       types.

   type_is_datetime("Alzabo::Column"object)
       Returns  a  boolean  indicating  whether or not the column is a datetime type.  This is not true for date
       types.

   type_is_time("Alzabo::Column"object)
       Returns a boolean indicating whether or not the column is a time type.  This is  not  true  for  datetime
       types.

   type_is_time_interval("Alzabo::Column"object)
       Returns a boolean indicating whether or not the column is a time interval type.

       Alzabo::RDBMSRules - Base class for Alzabo RDBMS rulesets

       To create a subclass of "Alzabo::RDBMSRules" for your particular RDBMS is fairly simple.

       Here's a sample header to the module using a fictional RDBMS called FooDB:

        package Alzabo::RDBMSRules::FooDB;

        use strict;
        use vars qw($VERSION);

        use Alzabo::RDBMSRules;

        use base qw(Alzabo::RDBMSRules);

       The  next  step  is  to  implement  a  "new()"  method  and the methods listed under the section "Virtual
       Methods".  The new method should look a bit like this:

        1:  sub new
        2:  {
        3:      my $proto = shift;
        4:      my $class = ref $proto || $proto;
        5:      my %p = @_;
        6:
        7:      my $self = bless {}, $self;
        8:
        9:      return $self;
        10:  }

       The hash %p contains any values passed to the "Alzabo::RDBMSRules->new" method by its caller.

       Lines 1-7 should probably be copied verbatim into your own "new" method.  Line 5 can be  deleted  if  you
       don't need to look at the parameters.

       The rest of your module should simply implement the methods listed under the "Virtual Methods" section of
       this documentation.

       Look  at  the included "Alzabo::RDBMSRules" subclasses for examples.  Feel free to contact me for further
       help if you get stuck.  Please tell me what database you're attempting to implement, and include the code
       you've written so far.

         use Alzabo::RDBMSRules;

         my $rules = Alzabo::RDBMSRules( rules => 'MySQL' );