Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Alzabo::Create::SchemaUser Contributed Perl DocumentaAlzabo::Create::Schema(3)

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:

       o   name	=> $name

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

       o   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:

       o   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:

       o   name	=> $name

	   The name of the database with which to connect.

       o   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:

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

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

	   ... or ...

       o   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:

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

	   The table to	move.

	   and either ...

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

	   Move	the table before this table

	   ... or ...

       o   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:

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

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

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

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

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

       o   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.

       o   from_is_dependent =>	$boolean

       o   to_is_dependent => $boolean

       o   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:

       o   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>

perl v5.24.1			  2017-07-02	     Alzabo::Create::Schema(3)

NAME | SYNOPSIS | DESCRIPTION | INHERITS FROM | METHODS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Alzabo::Create::Schema&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help