NAME

       Test::DBIx::Class::SchemaManager::Trait::Testmysqld - deploy to a test mysql instance

DESCRIPTION

       This trait uses Test::mysqld to auto create a test instance of mysql in a temporary area.
       This way you can test against mysql without having to create a test database, users, etc.
       Mysql needs to be installed (but doesn't need to be running) as well as DBD::mysql.  You
       need to install these yourself.

       Please review Test::mysqld for help if you get stuck.

CONFIGURATION

       This trait supports all the existing features but adds some additional options you can put
       into your inlined configuration files.  These following additional configuration options
       basically map to the options supported by Test::mysqld and the docs are adapted
       shamelessly from that module.

       For the most part, if you have mysql installed in a normal, findable manner you should be
       able to leave all these options blank.

   base_dir
       Returns directory under which the mysqld instance is being created. If you leave this
       unset we automatically create a place in the temporary directory and then clean it up
       later.  Unless you plan to roundtrip to the same database a lot you can just leave this
       blank.

       Please note if you set this to a particular area, we will delete it unless you
       specifically use the 'keep_db' option.  SO be care where you point it!

       Here's an example use.  I often want the test database setup in my local testing
       directory, that makes it easy for me to examine the logs, etc.  I do:

               BASE_DIR=t/tmp KEEP_DB=1 prove -lv t/my-mysql-test.t

       Now I can roundtrip the test as often as I want and in between tests I can review the
       logs, start the database manually and login (see the 'keep_db' section below for an
       example of how to do this).  Next time I run the tests the framework will automatically
       clean it up and rest the schema for testing.

       You may need to do this if you are stuck on a shared host and can't write anything to
       /tmp.  Remember, you can also put the 'base_dir' option into configuration instead of
       having to type it into the commandline each time!

   my_cnf
       A hashref containing the list of name=value pairs to be written into "my.cnf", which is
       the primary configuration file for the mysql instance.  Again, unless you have some
       specific needs you can leave this empty, since we set the few things most needed to get a
       server running.  You will need to review the documentation on the Mysql website for
       options related to this.

   port_to_try_first
       This is the port that will be used when starting mysqld. We check that this port is
       available for use before starting mysqld. If it is not available we increment by 1 and try
       again. We use the first free port found.

       By default this is a random port between 8000 and 10000. The randomness is an attempt to
       avoid race condition issues when running tests in parallel, between checking the
       availability of a port and actually starting the server.  Spreading the "first port"
       numbers used greatly reduces the chance of these issues occuring.

   mysql_install_db or mysqld
       If your mysqld is not in the $PATH you might need to specify the location to one of there
       binaries.  If you have a normal mysql setup this should not be a problem and you can leave
       this blank.

       For example, I often use MySQL::Sandbox to setup various versions of mysql in my local
       user directory, particularly if I am on a shared host, or in the case where I don't want
       mysql installed globally.  Personally I think this is really your safest option (and there
       will probably be a trait based on this in the future)

NOTES

       The following are notes regarding the way this trait alters or extends the core
       functionality as described in the basic documentation.

   force_drop_table
       Since it is always safe to use the 'force_drop_table' option with mysql, we set the
       default to true.  We recommend you leave it this way, particularly if you want to
       'roundtrip' the same test database.

   keep_db
       If you use the 'keep_db' option, this will preserve the temporarily created database
       files, however it will not prevent Test::mysqld from stopping the database when you are
       finished.  This is a safety measure, since if we didn't stop a test generated database
       instance automatically, you could easily end up with many databases running at once, and
       that could bring your server or testing box to a halt.

       If you use the 'keep_db' option and want to start and log into the test generated database
       instance, you can start the database by noticing the diagnostic output that should be
       generated at the top of your test.  It will look similar to:

               # Starting mysqld with: /usr/local/mysql/bin/mysqld --defaults-file=/tmp/KHKfJf0Yf6/etc/my.cnf --user=root

       If you have specified the base_dir to use, this output will not be displayed by default.
       You can force it's display by setting tdbic_debug to true. eg.

               TDBIC_DEBUG=1 BASE_DIR=t/tmp KEEP_DB=1 prove -lv t/my-mysql-test.t

       You can then start the database instance yourself with something like:

               /usr/local/mysql/bin/mysqld --defaults-file=/tmp/WT0P0VutAe/etc/my.cnf \
               --user=root &
               [1] 3447
               ....
               090827 15:06:16  InnoDB: Started; log sequence number 0 78863
               090827 15:06:16 [Note] Event Scheduler: Loaded 0 events
               090827 15:06:16 [Note] /usr/local/mysql/bin/mysqld: ready for connections.
               Version: '5.1.37'  socket: '/tmp/WT0P0VutAe/tmp/mysql.sock'  port: 0  MySQL Community Server (GPL)

       There will be some additional output to the term and then the server will go into the
       background.  If you don't like the extra output, you can just redirect it all to /dev/null
       or whatever is similar for your OS.

       You can now log into the test generated database instance with:

               mysql --socket=/tmp/WT0P0VutAe/tmp/mysql.sock -u root test

       You may need to specify the full path to 'mysql' if it's not in your search $PATH.

       When you are finished you can then kill the process.  In this case our reported process id
       is '3447'

               kill 3447

       And then you might wish to 'tidy' up temp

               rm -rf /tmp/WT0P0VutAe

       All the above assume you are on a unix or unixlike system.  Would welcome document patches
       for how to do all the above on windows.

AUTHOR

       John Napiorkowski "<jjnapiork@cpan.org>"

COPYRIGHT & LICENSE

       Copyright 2009, John Napiorkowski "<jjnapiork@cpan.org>"

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

perl v5.36.0                             Test::DBIx::Class::SchemaManager::Trait::Testmysqld(3pm)