Take me over?
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.
INHERITS FROM
Alzabo::Schema
METHODS
Constructors
new
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.
Returns
A new Alzabo::Create::Schema
object.
Throws
Alzabo::Exception::Params
Alzabo::Exception::System
load_from_file($name)
Returns a schema object previously saved to disk.
Returns
The Alzabo::Create::Schema
object specified by the name parameter.
Throws
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. This means that calling the make_sql
method on the object won't generate any SQL. To do this you'd have to first call $schema->set_instantiated(0)
and then $schema->make_sql
.
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.user => $user (optional)
User name to use when connecting to database.
password => $password (optional)
Password to use when connecting to database.
host => $host (optional)
The host with which to connect.
Returns
A new Alzabo::Create::Schema
object.
Other Methods
set_name ($name)
Change 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.
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.
Returns
The Alzabo::Create::Table
object created.
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
add_table
Add a table to the schema. 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.
Parameters
table =>
Alzabo::Create::Table
objectafter =>
Alzabo::Create::Table
object (optional)... or ...
before =>
Alzabo::Create::Table
object (optional)
Returns
The Alzabo::Create::Table
object created.
Throws
move_table
Allows you to change the order of the tables as they are stored in the schema.
Parameters
table =>
Alzabo::Create::Table
objectThe table to move.
and either ...
before =>
Alzabo::Create::Table
objectMove the table before this table
... or ...
after =>
Alzabo::Create::Table
objectMove the table after this table.
Throws
add_relation
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.
This is determined as follows: If the min_max_from value is 1..1 or 1..n, it assumes that the table specified as table_from
is dependent on the other table, and use the other table's primary key as the linking table. If the min_max_from
and min_max_to
are both 0..(1 or n) then it also assumes that the table_from
table is dependent. In all other cases, it uses the primary key from the table_from
.
If no columns with the same names exist in the other table, then columns with that name will be created. Otherwise, it changes the dependent columns so that their Alzabo::Create::ColumnDefinition
objects are the same as the columns in the table upon which it is dependent, meaning that changes to the type of one column affects both at the same time.
If you want to make multi-column relation, the assumption is that the order of the columns is significant. In other words, the first column in the columns_from
parameter is assumed to 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 both min_max_...
parameters have are (0 or 1)..n.
If both the min_max_from
and min_max_to
parameters are (0 or 1)..n 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.
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)min_max_from => (see below)
min_max_to => (see below)
The two min_max attributes both take the same kind of argument, an array reference two scalars long.
The first of these scalars can be the value '0' or '1' while the second can be '1' or 'n'.
Throws
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.
Parameters
host => $host
user => $user
password => $user
These three parameters are all passed the schema's Alzabo::Driver object to connect to the database.
instantiated
Returns
The value of the schema's instantiated attribute. It is true if 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.
rules
Returns
The schema's Alzabo::RDBMSRules
object.
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.
Parameters
host => $host
user => $user
password => $user
These three parameters are all passed the schema's Alzabo::Driver object to connect to the database.
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.
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 is also worth noting that if you set the instantiation attribute to true immediately, then the new schema be able to generate 'diffs' against the last version of the schema instantiated in an RDBMS backend. This is useful in the case where you have already copied the data from the old database to the new database in the RDBMS backend.
Parameters
name => $name
Returns
A new Alzabo::Create::Schema object.
save_to_file
Saves the schema to a file on disk.
AUTHOR
Dave Rolsky, <autarch@urth.org>