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:

Dynamic deployment of database
Dynamic generation of DBIx::Class schema modules
Dynamic generation of DBICx::Modeler model modules

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

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).
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.
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/).
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.
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.
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.
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

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

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

TO DO

More tests
Using Test::mysqld for tests (cf. http://mt.endeworks.jp/d-6/2009/10/things-ive-done-while-using-test-mysqld.html by Daisuke Maki, alias lestrrat

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

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.

To install DBICx::Modeler::Generator, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DBICx::Modeler::Generator

CPAN shell

perl -MCPAN -e shell
install DBICx::Modeler::Generator

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

How to model in your application - typical workflow

Tips about modeling

Using a batch script

How to make exported graphics the same size

METHODS

Constructors

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

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

Services

$self->deploy_database()

$self->update_models()

$self->update_schemata()

DEPENDENCY INJECTION

Mandatory dependencies

/DBICx/Modeler/Generator/Class

/DBICx/Modeler/Generator/Class/application

/DBICx/Modeler/Generator/Driver

/DBICx/Modeler/Generator/Model

/DBICx/Modeler/Generator/Path

/DBICx/Modeler/Generator/Path/root

/DBICx/Modeler/Generator/Schema

/DBICx/Modeler/Generator/Tree

Optional dependencies

/DBICx/Modeler/Generator/Class/base_part

/DBICx/Modeler/Generator/Class/model_part

/DBICx/Modeler/Generator/Class/schema_part

/DBICx/Modeler/Generator/Driver/bin

/DBICx/Modeler/Generator/Driver/database

/DBICx/Modeler/Generator/Driver/dbd

/DBICx/Modeler/Generator/Driver/dsn

/DBICx/Modeler/Generator/Driver/extension

/DBICx/Modeler/Generator/Driver/host

/DBICx/Modeler/Generator/Driver/password

/DBICx/Modeler/Generator/Driver/port

/DBICx/Modeler/Generator/Driver/username

/DBICx/Modeler/Generator/Path/creation_script

/DBICx/Modeler/Generator/Path/module_extension

/DBICx/Modeler/Generator/Path/script_extension

/DBICx/Modeler/Generator/Schema/components

/DBICx/Modeler/Generator/Schema/is_debug

/DBICx/Modeler/Generator/Tree/application

/DBICx/Modeler/Generator/Tree/library

/DBICx/Modeler/Generator/Tree/source

/DBICx/Modeler/Generator/Tree/target