NAME

Promised::Mysqld - MySQL server wrapper for development and testing

SYNOPSIS

use Promised::Mysqld;
$mysqld = Promised::Mysqld->new;
$mysqld->start->then (sub {
  ...;
  return $mysqld->stop;
})->then (sub {
  warn "done";
});

DESCRIPTION

The Promised::Mysqld class provides a Promise-aware interface to start and stop mysqld process, for the purpose of development and testing of Perl applications. It creates a database in the temporary directory (or in the directory specified by the application) and starts a MySQL server instance using it.

Use of this module is DEPRECATED in favor of MariaDB Docker image with Promised::Command::Docker.

METHODS

There are following methods:

$mysqld = Promised::Mysqld->new

Create a new instance.

$promise = $mysqld->start

Start the MySQL server instance and return a promise (Promise), which is resolved when the server is ready to accept SQL queries. The promise is rejected if the server failed to start.

$promise = $mysqld->stop

0Stop the MySQL server instance and return a promise (Promise), which is resolved after the server is shutdown.

This method must be invoked after the start method is invoked. It can be invoked even after the start's promise is rejected.

$mysqld->set_mysqld_and_mysql_install_db ($mysqld, $mysql_install_db)

Set the paths to the mysqld and mysql_install_db commands.

This method must be invoked before the start method is invoked. If not invoked, directories in PATH and well-known locations are used to find these commands.

$mysqld->set_db_dir ($path)

Set the path to the directory used to create files for the MySQL server. It can be an existing database directory, an empty directory, or a path to directory that does not exist yet. Please note that any existing file in the directory, especially etc/my.cnf, can be modified by the module and/or mysqld.

This method must be invoked before the start method is invoked. If not invoked, a temporary directory is created and used. The temporary directory is removed after the MySQL server is shutdown, unless the PROMISED_MYSQLD_DEBUG environment variable is set to a true value.

$hashref = $mysqld->my_cnf

Return a hash reference, which is used to generate the my.cnf configuration file for the mysqld process.

The hash can contain zero or more name/value character string pairs, which is used as name/value pairs in the generated my.cnf file. If the value is the empty string or undef, only the name is inserted in the file.

Some of name/value pairs are set by default (or to be set implicitly when the start method is invoked). Unless otherwise specified, the mysqld process is configured such that any file read or written (including database files) is located within the directory specified by the db_dir method and that no TCP/IP port is listen but a Unix domain socket is created in the db_dir's directory.

If you want mysqld to listen a TCP port, following lines should be executed before the start method invocation:

$mysqld->my_cnf->{port} = $port;
delete $mysqld->my_cnf->{'skip-networking'};

$time = $mysqld->start_timeout

$mysqld->start_timeout ($time)

Get or set the timeout for the start, i.e. the maximum time interval between the invocation of the mysqld command and when the server becomes ready to accept queries.

This method must be invoked before the start method is invoked.

$hashref = $mysqld->get_dsn_options

Return a hash reference, which contains name/value pairs that can be use to construct the options component of the DSN string for the DBI (DBD::mysql) module used to connect to the database. Note that the dbname option is set to mysql, which is the only database in the server when the server is created with no initial data.

This method must be invoked after the start's promise is resolved.

$dsn = $mysqld->get_dsn_string (NAME => VALUE, ...)

Return a DSN string which can be use to connect to the database using the DBI (DBD::mysql) module. By default the dbname option is set to mysql, which is the only database in the server when the server is created with no initial data. This can be replaced by specifying the dbname named argument to the method. Likewise, other options such as user and password can also be specified as named arguments.

This method must be invoked after the start's promise is resolved.

$mysqld->client_connect (NAME => VALUE, ...)->then (sub { $client = shift })

Connect to the MySQL server as a client and return a promise (Promise), which is resolved with the AnyEvent::MySQL::Client object which is connected to the database. By default it is connected to the mysql database on the server, which is the only database when the database is initialized without data. This can be altered by specifying the dbname named argument to the method.

This method must be invoked after the start's promise is resolved. The disconnect method of the client object does not have to be explicitly invoked. The stop method will invoke the method before shutting down the MySQL server, if necessary.

This method requires the AnyEvent::MySQL::Client module.

$promise = $mysqld->create_db_and_execute_sqls ($dbname, [$sql, $sql, ...])

Execute a set of SQL stagements and return a promise (Promise), which is resolved after the SQL statements specified by the arguments are executed on the created database. The promise is rejected if the execution is failed.

The first argument must be the database name. If there is no database with the specified name on the server, a new database is created (by an SQL CREATE DATABASE statement).

The second argument must be an array reference of zero or more strings, which are sent to the MySQL server as SQL statements, in order.

This method must be invoked after the start's promise is resolved.

This method requires the AnyEvent::MySQL::Client module.

During the server is running, signal handlers for SIGINT, SIGTERM, and SIGQUIT are installed such that these signal will terminate the server (and the current script). If the script wants to handle signal in other ways, the handling should be specified using the Promised::Command::Signals API from <https://github.com/wakaba/perl-promised-command> to avoid confliction of signal handlers.

DEPENDENCY

This module requires Perl 5.12 or later on Linux, or the latest version of Perl 5 on Mac OS X. The latest version of Perl 5 on Linux is recommended.

The module requires Promise <https://github.com/wakaba/perl-promise>, Promised::Command <https://github.com/wakaba/perl-promised-command>, Promised::File <https://github.com/wakaba/perl-promised-file>, and AnyEvent.

As described in the earlier section, some methods require AnyEvent::MySQL::Client <https://github.com/wakaba/perl-anyevent-mysql-client>.

It also requires MySQL version 5 (mysqld and mysql_install_db commands).

AUTHOR

Wakaba <wakaba@suikawiki.org>.

HISTORY

This module is inspired by Test::mysqld <https://github.com/kazuho/p5-test-mysqld> and Test::MySQL::CreateDatabase <https://github.com/wakaba/perl-rdb-utils/tree/master/lib/Test/MySQL>.

This Git repository was located at <https://github.com/wakaba/perl-promised-mysqld> until 7 March, 2022.

LICENSE

Copyright 2015-2022 Wakaba <wakaba@suikawiki.org>.

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