view release on metacpan or  search on metacpan

lib/Alzabo/Create/Schema.pm  view on Meta::CPAN

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

=item * rdbms => $rdbms

This is a string identifying the RDBMS.  The allowed values are
returned from the
L<C<Alzabo::RDBMSRules-E<gt>available>|Alzabo::RDBMSRules/available>
method.  These are values such as 'MySQL', 'PostgreSQL', etc.

=back

It returns a new C<Alzabo::Create::Schema> object.

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>,
L<C<Alzabo::Exception::System>|Alzabo::Exceptions>

=head2 load_from_file

This constructor takes the following parameters:

=over 4

=item * name => $schema_name

=back

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

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>,
L<C<Alzabo::Exception::System>|Alzabo::Exceptions>

=head2 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:

=over 4

=item * name => $name

The name of the database with which to connect.

=item * rdbms => $rdbms

See the L<C<new>|new> method documentation for an explanation of this
parameter.

=back

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 C<Alzabo::Create::Schema> object.

=head2 Other Methods

=for pod_merge name

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

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>,
L<C<Alzabo::Exception::RDBMSRules>|Alzabo::Exceptions>,
L<C<Alzabo::Exception::System>|Alzabo::Exceptions>

=for pod_merge table

=for pod_merge tables

=for pod_merge has_table

=head2 make_table

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

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

Returns a new L<C<Alzabo::Create::Table>|Alzabo::Create::Table>
object.

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>,
L<C<Alzabo::Exception::RDBMSRules>|Alzabo::Exceptions>

=head2 delete_table (C<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: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>

=head2 add_table

Add a table to the schema.

This methods takes the following parameters:

=over 4

=item * table => C<Alzabo::Create::Table> object

=item * after => C<Alzabo::Create::Table> object (optional)

lib/Alzabo/Create/Schema.pm  view on Meta::CPAN

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:

=over 4

=item * table_from => C<Alzabo::Create::Table> object (optional if columns_from is provided)

=item * table_to => C<Alzabo::Create::Table> object (optional if columns_to is provided)

=item * columns_from => C<Alzabo::Create::Column> object (optional if table_from is provided)

=item * columns_to => C<Alzabo::Create::Column> object (optional if table_to is provided)

=item * cardinality => [1, 1], [1, 'n'], ['n', 1], or ['n', 'n']

=item * 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.

=item * from_is_dependent => $boolean

=item * to_is_dependent => $boolean

=item * comment => $comment

=back

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>

=head2 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.

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

=head2 instantiated

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

=head2 set_instantiated ($bool)

Set the schema's instantiated attribute as true or false.

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>

=head2 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 L<C<create()>|Alzabo::Create::Schema/create>
method for more details.

=head2 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 C<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: L<C<Alzabo::Exception::Driver>|Alzabo::Exceptions>

=head2 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
L<C<create()>|Alzabo::Create::Schema/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: L<C<Alzabo::Exception::Driver>|Alzabo::Exceptions>

=head2 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: L<C<Alzabo::Exception::Driver>|Alzabo::Exceptions>

=head2 delete

Removes the schema object from disk.  It does not delete the database
from the RDBMS.  To do this you must call the L<C<drop>|drop> method
first.

Throws: L<C<Alzabo::Exception::System>|Alzabo::Exceptions>

=head2 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:

=over 4

=item * name => $name

=back

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

Throws: L<C<Alzabo::Exception::Params>|Alzabo::Exceptions>,
L<C<Alzabo::Exception::RDBMSRules>|Alzabo::Exceptions>

=head2 save_to_file

Saves the schema to a file on disk.

Throws: L<C<Alzabo::Exception::System>|Alzabo::Exceptions>

=head2 runtime_clone

Returns a new C<Alzabo::Runtime::Schema> object based on the current
schema.

=head2 is_saved

Returns true if the schema has been saved to disk.

=for pod_merge begin_work

=for pod_merge rollback

=for pod_merge commit

=for pod_merge run_in_transaction ( sub { code... } )

=for pod_merge driver

=for pod_merge rules

=for pod_merge sqlmaker