transactd 1.0.1

data/README

@@ -0,0 +1,406 @@
+Transactd release note
+===============================================================================
+Transactd is plugin which adds NoSQL access to MySQL/MariaDB.
+
+This document consists of the following topics.
+  * Introduction
+  * Preparation of Transactd Plugin binary
+  * Installing Transactd Plugin
+  * Preparation of Transactd clients binaries
+  * Installing Transactd clients
+  * Setting host permission to access Transactd
+  * Execution of test and benchmark program
+  * Development of applications using Transactd clients
+  * Details of the test program
+  * Details of the benchmark program
+  * About the license of Transactd Plugin
+  * About the license of Transactd Client
+  * Bug reporting, requests and questions
+  * Copyright of related products
+
+
+
+Introduction
+-------------------------------------------------------------------------------
+Transactd consists of the server side plugin and the client side modules.
+The server side plugin is called "Transactd Plugin" and the client side module
+is called "Transactd clients".
+
+
+
+Preparation of Transactd Plugin binary
+-------------------------------------------------------------------------------
+Check the version of your MySQL/MariaDB and download suitable Transactd Plugin
+binary. If you don't know what is version, start MySQL Command Line client and
+ run following command:
+```
+mysql>show variables like 'version';
++---------------+--------+
+| Variable_name | Value  |
++---------------+--------+
+| version       | 5.6.14 |
++---------------+--------+
+```
+The names of file to download are formed under following rules:
+
+  * Windows - transactd-[platform]-1.1.0_[mysql-version].zip
+  * Linux - transactd-linux-x86_64-1.1.0_[mysql-version].tar.gz
+
+[platform] is win32 or win64, [mysql-version] is mysql-5.x.x or mariadb-5.5.x.
+For example, the URL for Linux-x86_64bit mysql-5.6.14 is as follows:
+
+http://www.bizstation.jp/al/transactd/download/transactd-1.1.0/transactd-linux-x86_64-1.1.0_mysql-5.6.14.tar.gz
+
+You also can download source code archive and build from it.
+In this case, the source code of MySQL/MariaDB is also required.
+
+See BUILD_WIN-{lang}.md or BUILD_UNIX-{lang}.md in the source code archive
+for how to build.
+
+
+
+Installing Transactd Plugin
+-------------------------------------------------------------------------------
+Transactd Plugin can be installed by copying file, without adding any change to
+the binary of MySQL/MariaDB.
+You don't have to stop MySQL/MariaDB to install the plugin. It requires
+administrator authority.
+
+### Installing on Windows
+1. Open the zip file downloaded in Explorer. Check if transactd.dll is exists.
+
+2. Copy transactd.dll to `[MySQL|MariaDB installed directory]/lib/plugin`.
+   If you don't know where is [MySQL|MariaDB installed directory], start MySQL
+   Command Line client and run following command:
+```
+mysql>show variables like 'plugin%';
++---------------+----------------------------------------------------+
+| Variable_name | Value                                              |
++---------------+----------------------------------------------------+
+| plugin_dir    | C:\Program Files\MySQL\MySQL Server 5.6\lib\Plugin |
++---------------+----------------------------------------------------+
+```
+
+3. Start MySQL Command Line client and run following command:
+```
+mysql>INSTALL PLUGIN transactd SONAME 'transactd.dll';
+```
+Installation of Transactd Plugin is finished now.
+
+
+### Installing on Linux
+1. Move to the directory where downloaded tar.gz file is.
+```
+shell>cd [TargetFolder]
+```
+
+2. Extract the tar.gz file and move into it.
+```
+shell>tar zxf transactd-linux-x86_64-1.1.0_mysql-5.6.14.tar.gz
+shell>cd transactd-linux-x86_64-1.1.0_mysql-5.6.14
+```
+
+3. Copy libtransactd.so to `[MySQL|MariaDB installed directory]/lib/plugin`.
+   If you don't know where is [MySQL|MariaDB installed directory], start MySQL
+   Command Line client and run following command:
+```
+mysql>show variables like 'plugin%';
++---------------+-----------------------------+
+| Variable_name | Value                       |
++---------------+-----------------------------+
+| plugin_dir    | /usr/local/mysql/lib/plugin |
++---------------+-----------------------------+
+mysql>exit
+shell>cp libtransactd.so /usr/local/mysql/lib/plugin/
+```
+
+4. Start mysql client and run following command:
+```
+mysql>INSTALL PLUGIN transactd SONAME 'libtransactd.so';
+```
+Installation of Transactd Plugin is finished now.
+
+
+
+Preparation of Transactd client binaries
+-------------------------------------------------------------------------------
+The Transactd clients are required to access data through Transactd Plugin.
+Download the Transactd client binaries for your platform.
+The names of file to download are formed under following rules:
+
+  * Windows - transactd-client-[platform]_with_sdk-1.1.0.msi
+  * Linux -  transactd-client-linux-x86_64_with_sdk-1.1.0.tar.gz
+
+[platform] is win32 or win64.
+For example, the URL for Linux-x86_64bit is as follows:
+
+http://www.bizstation.jp/al/transactd/download/transactd-client/transactd-client-linux-x86_64_with_sdk-1.1.0.tar.gz
+
+
+
+Installing Transactd clients
+-------------------------------------------------------------------------------
+
+### Installing on Windows
+1. Double click transactd-client-[platform]_with_sdk-1.1.0.msi will start
+   installation by Windows installer.
+
+If you want to install the clients for Embarcadero C++Builder XE series, select
+[custom] on setup type selection window. Installable target compiler is:
+
+  * Microsoft Visual studio 2010 (Include ActiveX(COM) client)
+  * Embarcadero C++Builder XE series
+
+For Microsoft Visual studio is certainly installed.
+
+
+### Installing on Linux
+1. Move to the directory where downloaded tar.gz file is.
+```
+shell>cd [TargetFolder]
+```
+
+2. Extract the tar.gz file and move into it.
+```
+shell>tar zxf transactd-client-linux-x86_64_with_sdk-1.1.0.tar.gz
+shell>cd transactd-client-linux-x86_64_with_sdk-1.1.0
+```
+
+3. Run the install script.
+```
+shell>./install_client.sh
+```
+Installation of Transactd client is finished now.
+
+
+
+Setting host permission to access Transactd
+-------------------------------------------------------------------------------
+To access data through Transactd, register root@[host] to user table of MySQL.
+
+* `root@127.0.0.1` allows access from a local machine.
+* `root@192.168.0.3` allows access from host 192.168.0.3.
+* `root@192.168.0.0/255.255.255.0` allows access from host 192.168.0.x.
+
+Start MySQL Command Line client and run following commands to register hosts.
+```
+mysql>CREATE USER root@'192.168.0.0/255.255.255.0';
+```
+This operation allow root user to access database. If the root password is not set,
+you MUST SET IT.
+
+### Setup root password on Windows
+Open command prompt and run following command:
+```
+shell>"C:\Program Files\MySQL\MySQL Server 5.6\bin\mysqladmin" -u root password 'xxxxx'
+```
+(Replace xxxxx to your password.)
+
+### Setup root password on Linux
+```
+shell>/usr/local/mysql/bin/mysqladmin -u root password 'xxxxx'
+```
+(Replace xxxxx to your password.)
+
+### Using other name than root
+It is also possible to register another user name than "root".
+In order to use another user name, please add the following to the [mysqld] section
+of my.cnf or my.ini.
+```
+loose-transactd_hostcheck_username = yourUserName
+```
+Replace yourUserName to an actual user name.
+
+
+
+Execution of test and benchmark program
+-------------------------------------------------------------------------------
+See also the detail of the test and the benchmark program topic.
+
+### Executing on Windows
+1. Click [Start menu]-[All programs]-[BizStation]-[Transactd Client]-
+   [Test (compiler)(charset)] or [Benchmark local (compiler)].
+   (compiler) is VC100 or BCB. (charset) is Unicode or Multibyte.
+
+### Executing on Linux
+1. Move to the client directory.
+```
+shell>cd transactd-client-linux-x86_64_with_sdk-1.1.0
+```
+
+2. run test:
+```
+./exec_test_local.sh
+```
+
+
+
+Development of applications using Transactd clients
+-------------------------------------------------------------------------------
+Refer to the following SDK documents for development of the applications
+using Transactd clients.
+
+http://www.bizstation.jp/ja/transactd/client/sdk/doc/
+
+
+
+Details of the test program
+-------------------------------------------------------------------------------
+The executable file which starts with test_ is a Test program.
+
+Please be sure to run test with only an instance. It will fail if test runs two or
+more instances.
+If others access to test database during test runs, fail to drop database and can't
+release database.
+In such a case, reboot a server or run following command in MySQL command line client
+to drop a database.
+```
+mysql>drop database test;
+```
+
+If `-- showprogress=yes` is passed, it shows progress like:
+ ```
+0%   10   20   30   40   50   60   70   80   90   100%
+|----|----|----|----|----|----|----|----|----|----|
+************
+```
+
+Using `-- host=xxxxx` can specify host.
+The test using Japanese database name, table name and field name.
+To pass this test, set `character-set-server` as cp932 or utf8 in my.cnf.
+```
+[mysqld]
+character-set-server=utf8
+```
+
+
+
+Details of the benchmark program
+-------------------------------------------------------------------------------
+By changing processNumber argument, the benchmark program can be ran two or more
+instances simultaneously, and can measure them. The command line option is:
+```
+bench_tdclcpp_xxx.exe databaseUri processNumber functionNumber
+
+|----------------|--------------------------------------------------------|
+| option name    | description                                            |
+|----------------|--------------------------------------------------------|
+| databaseUri    | URI of a database.                                     |
+|----------------|--------------------------------------------------------|
+| processNumber  | Specify different number to run two or more instances. |
+|----------------|--------------------------------------------------------|
+| functionNumber | Specify the operation number.                          |
+|                | The operations:                                        |
+|                | -1: all of following                                   |
+|                |  0: Insert                                             |
+|                |  1: Insert in transaction. 20rec x 1000times           |
+|                |  2: Insert by bulkmode. 20rec x 1000times              |
+|                |  3: read each record                                   |
+|                |  4: read each record with snapshot                     |
+|                |  5: read range. 20rec x 1000times                      |
+|                |  6: read range with snapshot . 20rec x 1000times       |
+|                |  7: update                                             |
+|                |  8: update in transaction. 20rec x 1000times           |
+|----------------|--------------------------------------------------------|
+ex)
+shell>bench_tdclcpp_c_bcb_64.exe "tdap://localhost/test?dbfile=test.bdf" 0 -1
+```
+
+
+
+About the license of Transactd Plugin
+-------------------------------------------------------------------------------
+According to the license of MySQL/MariaDB, Transactd Plugin can be used under
+General Public License (GPLv2). The license information is in COPYING.
+
+
+
+About the license of Transactd clients
+-------------------------------------------------------------------------------
+You can select the license of Transactd clients from General Public License
+(GPLv2) or commercial license.
+
+* The license information of GPLv2 is in COPYING file.
+* You can examine a commercial license which not restricted by GPLv2 if wants.
+* Please see BizStation website about the details of licenses.
+  [BizStation website](http://www.bizstation.jp/en/transactd/support/)
+
+See also "Transactd clients OSS Exception" for OSS projects not subject to GPLv2.
+  - [Transactd clients OSS Exception](http://www.bizstation.jp/en/transactd/support/ossex.html)
+
+
+
+Bug reporting, requests and questions
+-------------------------------------------------------------------------------
+* If you find any bugs or if you have any requests, please send it to Issues
+  tracker on github. It requires github account(free).
+  - [Transactd Issues](https://github.com/bizstation/transactd/issues)
+* If you have any questions, please see our website or send to Issues tracker
+  on github above.
+  - [Transactd Documents](http://www.bizstation.jp/ja/transactd/documents/)
+  - [Transactd License/Support](http://www.bizstation.jp/ja/transactd/support/)
+
+
+
+********************************************************************************
+
+The copyrights of products related to Transactd Plugin and clients are below.
+
+********************************************************************************
+The following software may be included in Transactd Plugin and Client:
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+
+********************************************************************************
+The following software may be included in Transactd Plugin:
+HandlerSocket plugin for MySQL
+
+Copyright (c) 2010 DeNA Co.,Ltd.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of DeNA Co.,Ltd. nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY DeNA Co.,Ltd. "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL DeNA Co.,Ltd. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+********************************************************************************