Skip to content

Latest commit

 

History

History
204 lines (139 loc) · 6.54 KB

README.md

File metadata and controls

204 lines (139 loc) · 6.54 KB

Build Status

Overview

Amy is a C++11 compliant header-only Asynchronous MySQL client library based on Asio. It enables you to work with MySQL in both asynchronous and blocking ways. Amy had been tested using Clang++ 3.8 under Ubuntu 16.04, FreeBSD 11.0, and Mac OS X 10.10. It should also works under other similar UNIX-like systems with minimum efforts.

Getting Started

Dependencies

Using vanilla Asio

By default, Amy compiles against vanilla Asio. You may claim this explicitly by defining macro USE_BOOST_ASIO to 0.

Using Boost.Asio

Amy also allows you to compile against Boost.Asio by defineing USE_BOOST_ASIO to 1.

Using MariaDB Non-blocking API

The main difference of amy::mariadb_connector and amy::mysql_connector is that: amy::mysql_connector using an internal thread running mysql blocking API while amy::mariadb_connector using the original mariadb non-blocking API without internal thread.

Installing dependencies

You can probably obtain all the dependencies pretty easily using the package manager on your favorite operating system. For example:

  • Ubuntu 16.04:

    $ sudo apt-get install libboost-all-dev libmysqlclient-dev libasio-dev
    
  • FreeBSD 11.0:

    $ sudo pkg instal boost-all mysql-connector-c asio
    
  • Mac OS X 10.10+:

    $ brew install boost mysql-connector-c asio
    

Optionally, to build examples and tests, you may also want to install SCons:

$ sudo pip install scons

and LCov:

  • Ubuntu 16.04:

    $ sudo apt-get install lcov
    
  • FreeBSD 11.0:

    $ sudo pkg instal lcov
    
  • Mac OS X 10.10+:

    $ brew install lcov
    

Compile your program with Amy

Get Amy:

$ git clone https://github.com/liancheng/amy.git amy
$ cd amy
$ export AMY_HOME=$(pwd)

Add $AMY_HOME/include to your header search path and make sure to link your program against the following libraries:

  • libmysqlclient
  • pthread
  • libboost_system (only required when using Boost.Asio)

Most of the time, the following compiler options should be sufficient:

  • Building against vanilla Asio

    clang++ -DUSE_BOOST_ASIO=0  \
            -I$AMY_HOME/include \
            -L/usr/lib          \
            -L/usr/local/lib    \
            -lmysqlclient       \
            -lpthread           \
            ...
    
  • Building against Boost.Asio

    clang++ -DUSE_BOOST_ASIO=1  \
            -I$AMY_HOME/include \
            -L/usr/lib          \
            -L/usr/local/lib    \
            -lmysqlclient       \
            -lpthread           \
            -lboost_system      \
            ...
    

You may need an extra library path /usr/local/lib/mysql under FreeBSD since that's where the pkg package manager installs the MySQL client library:

Examples

Please check the following examples for a taste of Amy:

To build the examples, run:

$ cd $AMY_ROOT
$ scons USE_BOOST_ASIO=0 example # Using vanilla Asio
$ scons USE_BOOST_ASIO=1 example # Using Boost.Asio

Built executables can be found under $AMY_ROOT/build/example. Run each example with --help to find out how to use them.

Run the example programs with -h command line option to find out how to use them.

Tests

Note that an extra dependency, Boost.Test, is used to build and write test cases for Amy. Usually, it should have already been installed together with Boost.

Some (integration) test cases need to establish actual connections to an existing MySQL server. To make sure these tests succeed, you need to start a MySQL server listening on localhost:3306 and setup the following testing database and user account:

CREATE DATABASE test_amy;
CREATE USER 'amy'@'localhost' IDENTIFIED BY 'amy';
GRANT ALL PRIVILEGES ON test_amy.* TO 'amy'@'localhost';
FLUSH PRIVILEGES;

To test Amy, run:

$ cd $AMY_ROOT
$ scons USE_BOOST_ASIO=0 test # Using vanilla Asio
$ scons USE_BOOST_ASIO=1 test # Using Boost.Asio