MORIYA Masaki (守屋 雅樹) > DBICx-Modeler-Generator-0.02 > DBICx::Modeler::Generator

Download:
DBICx-Modeler-Generator-0.02.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.02   Source  

NAME ^

DBICx::Modeler::Generator - Dynamic definition of a DBIx::Class::Schema and a DBICx::Modeler

VERSION ^

This document describes DBICx::Modeler::Generator version 0.02.

SYNOPSIS ^

    use Orochi;

    my $container = Orochi->new;
    $container->inject_literal('/Class/application' => 'MyApp');
    $container->inject_literal('/Path/root' => 'examples');
    # ...
    $container->inject_class('DBICx::Modeler::Generator');
    $container->inject_class('DBICx::Modeler::Generator::Class');
    # ...
    my $generator = $container->get('/DBICx/Modeler/Generator');

    $generator->deploy_database;
    $generator->update_schemata;
    $generator->update_models;

    # note: let us use DBICx::Modeler::Generator::CLI instead of above codes.

DESCRIPTION ^

An enterprise application requires consideration of better architecture. Especially, a modeling greatly influences maintainability of the application.

So, I recommend that to separate schemata and models with DBICx::Modeler. This smart module provides a Moose-based model layer over DBIx::Class.

However, we must define a lot of model modules to receive the benefits of the separation. It is a too tiresome job.

Therefore, let us automate tedious common definition with this DBICx::Modeler::Generator module which provides features below:

As well, this DBICx::Modeler::Generator module can also be used as a simple automation wrapper only dynamic generation of schema modules with DBIx::Class::Schema::Loadler.

How to model in your application - typical workflow

  1. Design schemata with MySQL Workbench application (http://www.mysql.com/products/workbench/).

    This application can design tables, columns, indices, relationships, and much more.

    The sample of a schema file available for examples/doc/DBDSC_schemata.mwb in this distribution. It catches DBICx::Modeler's test modules which has artist, cd, and track tables (schemata).

  2. Optionally draw an ERD (Entity-Relationship Diagram) with MySQL Workbench for documentation.

    The sample of an exported graphic file available for examples/doc/DBDERII_Including_Information.png in this distribution.

  3. Dynamically deploy a database with the schemata by [Database] - [Forward Engineer...] function of MySQL Workbench.

    Or, by deploy_database() method of this module with a creation (DDL: Data Definition Language) script which generated by [File] - [Export] - [Forward Engineer SQL CREATE Script...] function of MySQL Workbench.

    The sample of an exported creation script file available for examples/src/myapp_mysql.sql (for MySQL) and examples/src/myappl.sql (for SQLite) in this distribution.

    Note: MySQL Workbench can export DDL script for SQLite with SQLite export plugin for MySQL Workbench plugin (http://www.henlich.de/software/sqlite-export-plugin-for-mysql-workbench/).

  4. Statically define (it means write it yourself) schema module files for additional definition. For example, inflations, deflations, relationships, and much more.

    The sample of schema module file which describes only part of an additional definition available for examples/src/lib/MyApp/Schema/Artist.pm in this distribution.

  5. Dynamically define schema module files by update_schemata() method of this module.

    For example, this will enable us to generate schema file which path is examples/lib/MyApp/Schema/Artist.pm, examples/lib/MyApp/Schema/Cd.pm, and much more in this distribution.

  6. Statically define (it means write it yourself) model module files for additional definition. For example, Moose's attributes, methods, method modifiers, and much more.

    The sample of model module file which describes only part of an additional definition available for examples/src/lib/MyApp/Model/Cd.pm in this distribution.

  7. Dynamically define model module files by update_models() method of this module.

    For example, this will enable us to generate model file which path is examples/lib/MyApp/Model/Artist.pm, examples/lib/MyApp/Model/Cd.pm, and much more in this distribution.

Tips about modeling

Using a batch script

I recommend to use a batch script which processes dynamic deployment of database, dynamic definition of schemata, and dynamic definition of models.

The sample of a batch script file available for examples/src/sbin/maintain_models.pl in this distribution. See EXAMPLES section for further detail.

How to make exported graphics the same size

In MySQL Workbench, 1mm of an ERD correspond 5px of an exported PNG graphic (This premise is correct as version 5.1.18 OSS of Windows binary).

On the basis of this observation, you can specify the size of a PNG graphic.

For example, to export as Quad-VGA resolution (width: 1280px, height: 960px), I whould suggest that you specify setting below:

[Paper] group

select [A4 (210 mm x 297 mm)] item from [Size] listbox

[Orientation] group

turn on [Landscape] radio button

[Margins] group

input [10]mm into [Top] text box

input [10]mm into [Left] text box

input [35]mm into [Bottom] text box

input [12]mm into [Right] text box

Just for reference, The sample of a size validator script file available for examples/src/confirm_image_size.pl in this distribution.

METHODS ^

Constructors

$di_container->get('/DBICx/Modeler/Generator')

Returns a dependency injected object.

To get an object, use the code as the synopsis above instead of DBICx::Modeler::Generator->new(...).

See DEPENDENCY INJECTION section for further detail.

You may use also the wrapped interface with DBICx::Modeler::Generator::CLI.

DBICx::Modeler::Generator::CLI->new_with_options(%init_args)

Returns an object of DBICx::Modeler::Generator::CLI.

I strongly recommend that you use this interface to get a generator object because the interface wraps dependency injection with MooseX::Getopt and MooseX::SimpleConfig.

See concrete codes below:

    my $generator = DBICx::Modeler::Generator::CLI->new_with_options(
        application => 'MyApp',
        root        => '/path/to/root',
        driver      => 'SQLite',
    )->generator;

Services

$self->deploy_database()

Deploys database with a creation script.

$self->update_models()

Updates model modules.

$self->update_schemata()

Updates schema modules.

DEPENDENCY INJECTION ^

This class and subclasses using MooseX::Orochi for DI (dependency injection).

See examples/src/sbin/maintain_models.pl in this distribution for further datail.

Mandatory dependencies

/DBICx/Modeler/Generator/Class

It is an instance of an implement class which complies with the DBICx::Modeler::Generator::ClassLike interface.

This distribution contains the implement class which named DBICx::Modeler::Generator::Class for common usage.

/DBICx/Modeler/Generator/Class/application

It is a class name of the application root.

Type

Str

Example

MyApp, My::App, etc.

/DBICx/Modeler/Generator/Driver

It is an instance of an implement class which complies with the DBICx::Modeler::Generator::DriverLike interface.

This distribution contains the implement classes which named DBICx::Modeler::Generator::Driver::MySQL and DBICx::Modeler::Generator::Driver::SQLite for common usage.

/DBICx/Modeler/Generator/Model

It is an instance of an implement class which complies with the DBICx::Modeler::Generator::ModelLike interface.

This distribution contains the implement class which named DBICx::Modeler::Generator::Model for common usage.

/DBICx/Modeler/Generator/Path

It is an instance of an implement class which complies with the DBICx::Modeler::Generator::PathLike interface.

This distribution contains the implement class which named DBICx::Modeler::Generator::Path for common usage.

/DBICx/Modeler/Generator/Path/root

It is a directory path of the application root.

Type

Path::Class::Dir (can be coerce with MooseX::Types::Path::Class)

Example

/path/to/root

/DBICx/Modeler/Generator/Schema

It is an instance of an implement class which complies with the DBICx::Modeler::Generator::SchemaLike interface.

This distribution contains the implement class which named DBICx::Modeler::Generator::Schema for common usage.

/DBICx/Modeler/Generator/Tree

It is an instance of an implement class which complies with the DBICx::Modeler::Generator::TreeLike interface.

This distribution contains the implement class which named DBICx::Modeler::Generator::Tree for common usage.

Optional dependencies

/DBICx/Modeler/Generator/Class/base_part

Type

Str

Default

Base

/DBICx/Modeler/Generator/Class/model_part

Type

Str

Default

Model

/DBICx/Modeler/Generator/Class/schema_part

Type

Str

Default

Schema

/DBICx/Modeler/Generator/Driver/bin

Type

Str

Default

mysql (in case of that the implement driver class is DBICx::Modeler::Generator::Driver::MySQL), sqlite3 (in case of that the implement driver class is DBICx::Modeler::Generator::Driver::SQLite), etc.

/DBICx/Modeler/Generator/Driver/database

Type

Str

Default

$application, /$root/$application.$database_extension, etc.

Example

myapp, my_app, /path/to/root/my_app.db, etc.

/DBICx/Modeler/Generator/Driver/dbd

Type

Str

Default

mysql (in case of that the implement driver class is DBICx::Modeler::Generator::Driver::MySQL), SQLite (in case of that the implement driver class is DBICx::Modeler::Generator::Driver::SQLite), etc.

/DBICx/Modeler/Generator/Driver/dsn

Type

Str

Default

dbi:$dbd:database=$database, dbi:$dbd:database=$database;host=$host, dbi:$dbd:database=$database;host=$host;port=$port, dbi:$dbd:dbname=$database, etc.

/DBICx/Modeler/Generator/Driver/extension

Type

Str

Default

.db (in case of that the implement driver class is DBICx::Modeler::Generator::Driver::SQLite), etc.

/DBICx/Modeler/Generator/Driver/host

Type

Str

Default

undef (it means localhost on general drivers)

/DBICx/Modeler/Generator/Driver/password

Type

Str

Default

undef

Example

foobar

/DBICx/Modeler/Generator/Driver/port

Type

Int

Example

3306, 3307, etc.

/DBICx/Modeler/Generator/Driver/username

Type

Str

Example

mysql_user

/DBICx/Modeler/Generator/Path/creation_script

Type

Path::Class::File (can be coerce with MooseX::Types::Path::Class)

Default

/$root/$source/$application.$script_extension

Example

/path/to/root/src/myapp.sql

/DBICx/Modeler/Generator/Path/module_extension

Type

Str

Default

.pm

/DBICx/Modeler/Generator/Path/script_extension

Type

Str

Default

.sql

/DBICx/Modeler/Generator/Schema/components

Type

ArrayRef[Str]

Default

[]

(cf. Don't use DBIx::Class::UTF8Columns, http://perl-users.jp/articles/advent-calendar/2009/hacker/04.html)

/DBICx/Modeler/Generator/Schema/is_debug

Type

Bool

Default

0 (false)

/DBICx/Modeler/Generator/Tree/application

Type

Str

Default

myapp (in calse of that the application class name is MyApp), my_app (in calse of that the application class name is My::App), etc.

/DBICx/Modeler/Generator/Tree/library

Type

ArrayRef[Str]

Default

[qw(lib)]

/DBICx/Modeler/Generator/Tree/source

Type

ArrayRef[Str]

Default

[qw(src)]

/DBICx/Modeler/Generator/Tree/target

Type

ArrayRef[Str]

Default

[]

EXAMPLES ^

This distribution includes whole file which related workflow above.

Run the following command at root directory of this distribution:

    perl -Ilib examples/src/sbin/maintain_models.pl \
         -a MyApp -r examples -d SQLite

or

    perl -Ilib examples/src/sbin/maintain_models.pl            \
         -a MyApp -r examples -d MySQL -u username -w password \
         -l /Path/script_extension=_mysql.sql

or

    perl -Ilib examples/src/sbin/maintain_models.pl \
         --configfile examples/src/myapp.yml

SEE ALSO ^

TO DO ^

INCOMPATIBILITIES ^

None reported.

BUGS AND LIMITATIONS ^

No bugs have been reported.

Making suggestions and reporting bugs

Please report any found bugs, feature requests, and ideas for improvements to bug-dbicx-modeler-generator at rt.cpan.org, or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=DBICx-Modeler-Generator. I will be notified, and then you'll automatically be notified of progress on your bugs/requests as I make changes.

When reporting bugs, if possible, please add as small a sample as you can make of the code that produces the bug. And of course, suggestions and patches are welcome.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc DBICx::Modeler::Generator

You can also find the Japanese edition of documentation for this module with the perldocjp command from Pod::PerldocJp.

    perldocjp DBICx::Modeler::Generator.ja

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/Public/Dist/Display.html?Name=DBICx-Modeler-Generator

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/DBICx-Modeler-Generator

Search CPAN

http://search.cpan.org/dist/DBICx-Modeler-Generator

CPAN Ratings

http://cpanratings.perl.org/dist/DBICx-Modeler-Generator

VERSION CONTROL ^

This module is maintained using git. You can get the latest version from git://github.com/gardejo/p5-dbicx-modeler-generator.git.

CODE COVERAGE ^

I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover summary report on this distribution's test suite.

 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 File                           stmt   bran   cond    sub    pod   time  total
 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 ...BICx/Modeler/Generator.pm  100.0    n/a    n/a  100.0  100.0    0.0  100.0
 .../Modeler/Generator/CLI.pm  100.0  100.0    n/a  100.0    0.0   22.2   98.0
 ...odeler/Generator/Class.pm  100.0    n/a    n/a  100.0  100.0    0.0  100.0
 ...er/Generator/ClassLike.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 .../Generator/Driver/Base.pm  100.0  100.0    n/a  100.0  100.0    0.0  100.0
 ...Generator/Driver/MySQL.pm  100.0  100.0    n/a  100.0    n/a    0.0  100.0
 ...enerator/Driver/SQLite.pm  100.0    n/a    n/a  100.0    n/a   11.1  100.0
 ...r/Generator/DriverLike.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 ...odeler/Generator/Model.pm  100.0  100.0    n/a  100.0  100.0   44.4  100.0
 ...er/Generator/ModelLike.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 ...Modeler/Generator/Path.pm  100.0  100.0    n/a  100.0  100.0    0.0  100.0
 ...ler/Generator/PathLike.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 ...deler/Generator/Schema.pm  100.0   50.0    n/a  100.0  100.0   22.2   97.6
 ...r/Generator/SchemaLike.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 ...Modeler/Generator/Tree.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 ...ler/Generator/TreeLike.pm  100.0    n/a    n/a  100.0    n/a    0.0  100.0
 Total                         100.0   94.4    n/a  100.0   91.7  100.0   99.7
 ---------------------------- ------ ------ ------ ------ ------ ------ ------

AUTHOR ^

MORIYA Masaki, alias Gardejo

<moriya at cpan dot org>, http://gardejo.org/

COPYRIGHT AND LICENSE ^

Copyright (c) 2009-2010 MORIYA Masaki, alias Gardejo

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlgpl and perlartistic.

The full text of the license can be found in the LICENSE file included with this distribution.

syntax highlighting: