diff --git a/.gitignore b/.gitignore
index cd2dcca7ddbf1b0076cdb2be49b1f7cf4ae4e596..b79c47df76797803d9d027a7d5e02929140da049 100644
--- a/.gitignore
+++ b/.gitignore
@@ -71,3 +71,5 @@ doc/sphinx/_build/*
!doc/sphinx/_build/.gitignore
doc/www/content/doc
extra/dist/default/tarantool
+extra/com.tarantool.tarantool.plist
+extra/postflight
diff --git a/cmake/compiler.cmake b/cmake/compiler.cmake
index 32986c65c618b61829741ea12f3546f1ad9406cf..26a4f06aac982b6524b83478247c73a57aba9752 100644
--- a/cmake/compiler.cmake
+++ b/cmake/compiler.cmake
@@ -77,6 +77,10 @@ check_cxx_source_compiles("int main(void) {
}" HAVE_OPENMP)
set(CMAKE_REQUIRED_FLAGS "")
+if (NOT HAVE_OPENMP)
+ add_compile_flags("C;CXX" -Wno-unknown-pragmas)
+endif()
+
#
# Perform build type specific configuration.
#
diff --git a/doc/sphinx/book/app_d_plugins.rst b/doc/sphinx/book/app_d_plugins.rst
index c8f45a3321587002dcfc9596c0280ca542e53c91..93d63be7b1531fe6b64570f7d4e00873481300ee 100644
--- a/doc/sphinx/book/app_d_plugins.rst
+++ b/doc/sphinx/book/app_d_plugins.rst
@@ -1,30 +1,31 @@
.. _dbms-plugins:
-------------------------------------------------------------------------------
- Appendix D. Plugins
+ Appendix D. Modules
-------------------------------------------------------------------------------
-A plugin is an optional library which enhances Tarantool functionality.
+A module is an optional library which enhances Tarantool functionality.
-The details of creating one's own plugin are described on the `Tarantool Plugin API wiki page`_.
+For examples of creating one's own module with Lua or C, see
+`gist.github.com/rtsisyk/aa95cf9ed9bbb538ff80`_.
The discussion here in the user guide is about incorporating and using two
-plugins that have already been created: the "SQL DBMS plugins" for
+modules that have already been created: the "SQL DBMS rocks" for
MySQL and PostgreSQL.
===========================================================
- SQL DBMS Plugins
+ SQL DBMS Modules
===========================================================
To call another DBMS from Tarantool, the essential requirements are: another
-DBMS, and Tarantool.
+DBMS, and Tarantool. The module which connects Tarantool to another DBMS may
+be called a "connector". Within the module there is a shared library which
+may be called a "driver".
-It will be necessary to build Tarantool from source, as described in
-“:ref:`building-from-source`â€.
+Tarantool supplies DBMS connector modules with the package manager for Lua,
+LuaRocks. So the connector modules may be called "rocks".
-.. _Tarantool Plugin API wiki page: https://github.com/tarantool/tarantool/wiki/Plugin-API
-
-The Tarantool plugins allow for connecting to an SQL server and executing SQL
+The Tarantool rocks allow for connecting to an SQL server and executing SQL
statements the same way that a MySQL or PostgreSQL client does. The SQL
statements are visible as Lua methods. Thus Tarantool can serve as a "MySQL Lua
Connector" or "PostgreSQL Lua Connector", which would be useful even if that was
@@ -32,38 +33,170 @@ all Tarantool could do. But of course Tarantool is also a DBMS, so the plugin
also is useful for any operations, such as database copying and accelerating,
which work best when the application can work on both SQL and Tarantool inside
the same Lua routine.
-
-The connection method is
-:samp:`box.net.sql.connect('mysql'|'pg', {host}, {port}, {user}, {password}, {database})`.
-The methods for select/insert/etc. are the same as the ones in the
+The methods for connect/select/insert/etc. are similar to the ones in the
:ref:`net.box <package_net_box>` package.
+From a user's point of view the MySQL and PostgreSQL rocks are
+very similar, so the following sections -- "MySQL Example" and
+"PostgreSQL Example" -- contain some redundancy.
+
===========================================================
MySQL Example
===========================================================
-This example assumes that MySQL 5.5 or MySQL 5.6 has been installed (recent
-MariaDB versions should also work).
+This example assumes that MySQL 5.5 or MySQL 5.6 has been installed.
+Recent MariaDB versions should also work.
+The package that matters most is the MySQL client
+developer package, typically named something like libmysqlclient-dev.
+The file that matters most from this package is
+libmysqlclient.so or a similar name.
+One can use :code:`find` or :code:`whereis` to see what
+directories these files are installed in.
+
+It will be necessary to install Tarantool's MySQL driver shared library,
+load it, and use it to connect to a MySQL server.
+After that, one can pass any MySQL statement to the server and
+receive results, including multiple result sets.
+
+HOW TO INSTALL:
+
+Check the instructions for
+:ref:`Downloading and installing a binary package <downloading-and-installing-a-binary-package>`
+that apply for the environment where tarantool was installed.
+In addition to installing :code:`tarantool`, install :code:`tarantool-dev`.
+For example, on Ubuntu, add the line |br|
+:codebold:`sudo apt-get install tarantool-dev`
+
+Now, for the MySQL driver shared library, there are two ways to install:
+with luarocks or with github.
+
+With luarocks ... Begin by installing luarocks and making sure that
+tarantool is among the upstream servers, as in the instructions on
+`rocks.tarantool.org`_, the Tarantool luarocks page. Now execute this: |br|
+:codenormal:`luarocks install mysql [MYSQL_LIBDIR=` :codeitalic:`name` :codenormal:`] [MYSQL_INCDIR=` :codeitalic:`name` :codenormal:`] [--local]` |br|
+For example: |br|
+:codebold:`luarocks install mysql MYSQL_LIBDIR=/usr/local/mysql/lib`
+
+With github ... go the site `github.com/tarantool/mysql`_.
+Follow the instructions there, saying
+
+ | :codebold:`git clone https://github.com/tarantool/mysql.git`
+ | :codebold:`cd mysql && cmake . -DCMAKE_BUILD_TYPE=RelWithDebugInfo`
+ | :codebold:`make`
+ | :codebold:`make install`
+
+At this point it is a good idea to check that the installation
+produced a file named :code:`driver.so`, and to check that this file
+is on a directory that is searched by the :code:`require` request.
+
+HOW TO CONNECT:
+
+Begin by making a :code:`require` request for the mysql driver.
+For example, :codebold:`mysql = require('mysql')`.
+We will assume that the name is :code:`mysql` in further examples.
+
+Now, say |br|
+:codenormal:`connection_name = mysql.connect(` :codeitalic:`connection options` :codenormal:`)` |br|
+The connection-options parameter is a table.
+The possible options are: |br|
+:codenormal:`host =` :codeitalic:`host-name` -- string, default value = 'localhost' |br|
+:codenormal:`port =` :codeitalic:`port-number` -- number, default value = 3306 |br|
+:codenormal:`user =` :codeitalic:`user-name` -- string, default value = operating-system user name |br|
+:codenormal:`password =` :codeitalic:`password` or :codenormal:`pass =` :codeitalic:`password` -- string, default value = blank |br|
+:codenormal:`db =` :codeitalic:`database-name` -- string, default value = blank |br|
+The names are similar to the names that MySQL's mysql client uses, for details
+see the MySQL manual at `dev.mysql.com/doc/refman/5.6/en/connecting.html`_.
+To connect with a Unix socket rather than with TCP, specify :codenormal:`host = 'unix/'`
+and :codenormal:`port =` :codeitalic:`socket-name`. |br|
+
+Example, using a table literal enclosed in {braces}: |br|
+:codebold:`conn = mysql.connect({host='127.0.0.1', port=3306, user='p', password='p', db='test'})` |br|
+
+Example, using a table literal enclosed in {braces}: |br|
+:codebold:`conn = mysql.connect({host='unix/',port='/var/run/mysqld/mysqld.sock'})`
+
+Example, creating a function which sets each option in a separate line:
+ | :codenormal:`# Connection function. Usage: conn = mysql_connect()`
+ | :codenormal:`tarantool>` :codebold:`console = require('console'); console.delimiter('!')`
+ | :codenormal:`tarantool>` :codebold:`function mysql_connect ()`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`p = {}`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`p.host = 'widgets.com'`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`p.db = 'test'`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`conn = mysql.connect(p)`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`return conn`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`end!`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`console.delimiter('')!`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`conn = mysql_connect()`
+ | :codenormal:`---`
+ | :codenormal:`...`
+
+We will assume that the name is 'conn' in further examples.
-The example was run on a Linux machine where the base directory had a copy of
-the Tarantool source on ~/tarantool, and a copy of MySQL on ~/mysql-5.5. The
+HOW TO PING:
+
+To ensure that a connection is working, the request is:
+
+ | :codeitalic:`connection-name` :codenormal:`:` :codenormal:`ping()`
+
+Example: |br|
+ | :codenormal:`tarantool>` :codebold:`conn:ping()`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
+
+HOW TO EXECUTE A STATEMENT: |br|
+
+For all MySQL statements, the request is: |br|
+:codeitalic:`connection-name` :codenormal:`:` :codenormal:`execute(` :codeitalic:`sql-statement` [, :codeitalic:`parameters` :codenormal:`])` |br|
+where :code:`sql-statement` is a string, and the optional :code:`parameters`
+are extra values that can be plugged in to replace any question marks ("?"s) in the SQL statement. |br|
+
+For example: |br|
+ | :codenormal:`tarantool>` :codebold:`conn:execute('select table_name from information_schema.tables')`
+ | :codenormal:`---`
+ | :codenormal:`- - table_name: ALL_PLUGINS`
+ | |nbsp| |nbsp| :codenormal:`- table_name: APPLICABLE_ROLES`
+ | |nbsp| |nbsp| :codenormal:`- table_name: CHARACTER_SETS`
+ | |nbsp| :codenormal:`...`
+ | :codenormal:`- 78`
+ | :codenormal:`...`
+
+HOW TO CLOSE:
+
+To end a session that began with :code:`mysql.connect`, the request is: |br|
+:codeitalic:`connection-name` :codenormal:`:` :codenormal:`close()` |br|
+For example: |br|
+:codebold:`conn:close()`
+
+For further information, including examples of rarely-used requests,
+see the README.md file at `github.com/tarantool/mysql`_.
+
+LONG EXAMPLE:
+
+The example was run on an Ubuntu 12.04 ("precise") machine where tarantool
+had been installed in a /usr subdirectory, and a copy of MySQL had been installed on ~/mysql-5.5. The
mysqld server is already running on the local host 127.0.0.1.
+ | :codebold:`export TMDIR=~/mysql-5.5`
| :codenormal:`# Check that the include subdirectory exists by looking for .../include/mysql.h.`
| :codenormal:`# (If this fails, there's a chance that it's in .../include/mysql/mysql.h instead.)`
- | :codenormal:`$` :codebold:`[ -f ~/mysql-5.5/include/mysql.h ] && echo "OK" || echo "Error"`
+ | :codenormal:`$` :codebold:`[ -f $TMDIR/include/mysql.h ] && echo "OK" || echo "Error"`
| :codenormal:`OK`
|
| :codenormal:`# Check that the library subdirectory exists and has the necessary .so file.`
- | :codenormal:`$` :codebold:`[ -f ~/mysql-5.5/lib/libmysqlclient.so ] && echo "OK" || echo "Error"`
+ | :codenormal:`$` :codebold:`[ -f $TMDIR/lib/libmysqlclient.so ] && echo "OK" || echo "Error"`
| :codenormal:`OK`
|
| :codenormal:`# Check that the mysql client can connect using some factory defaults:`
| :codenormal:`# port = 3306, user = 'root', user password = '', database = 'test'.`
| :codenormal:`# These can be changed, provided one uses the changed values in`
| :codenormal:`# all places.`
- | :codenormal:`$` :codebold:`~/mysql-5.5/bin/mysql --port=3306 -h 127.0.0.1 --user=root --password= --database=test`
+ | :codenormal:`$` :codebold:`$TMDIR/bin/mysql --port=3306 -h 127.0.0.1 --user=root --password= --database=test`
| :codenormal:`Welcome to the MySQL monitor. Commands end with ; or \\g.`
| :codenormal:`Your MySQL connection id is 25`
| :codenormal:`Server version: 5.5.35 MySQL Community Server (GPL)`
@@ -78,63 +211,52 @@ mysqld server is already running on the local host 127.0.0.1.
| :codenormal:`mysql>` :codebold:`QUIT`
| :codenormal:`Bye`
|
- | :codenormal:`# Build the Tarantool server. Make certain that "cmake" gets the right`
- | :codenormal:`# paths for the MySQL include directory and the MySQL libmysqlclient`
- | :codenormal:`# library which were checked earlier.`
- | :codenormal:`$` :codebold:`cd ~/tarantool`
- | :codenormal:`$` :codebold:`make clean`
- | :codenormal:`$` :codebold:`rm CMakeCache.txt`
- | :codenormal:`$` :codebold:`cmake . -DWITH_MYSQL=on -DMYSQL_INCLUDE_DIR=~/mysql-5.5/include\\`
- | :codenormal:`>` |nbsp| |nbsp| :codebold:`-DMYSQL_LIBRARIES=~/mysql-5.5/lib/libmysqlclient.so`
- | :codenormal:`...`
- | :codenormal:`-- Found MySQL includes: ~/mysql-5.5/include/mysql.h`
- | :codenormal:`-- Found MySQL library: ~/mysql-5.5/lib/libmysqlclient.so`
- | :codenormal:`...`
- | :codenormal:`-- Configuring done`
- | :codenormal:`-- Generating done`
- | :codenormal:`-- Build files have been written to: ~/tarantool`
- | :codenormal:`$` :codebold:`make`
- | :codenormal:`...`
- | :codenormal:`Scanning dependencies of target mysql`
- | :codenormal:`[ 79%] Building CXX object src/module/mysql/CMakeFiles/mysql.dir/mysql.cc.o`
- | :codenormal:`Linking CXX shared library libmysql.so`
- | :codenormal:`[ 79%] Built target mysql`
- | :codenormal:`...`
- | :codenormal:`[100%] Built target man`
+ | :codenormal:`# Install luarocks`
+ | :codenormal:`$` :codebold:`sudo apt-get -y install luarocks | grep "Setting up"`
+ | :codenormal:`Setting up luarocks (2.0.8-2) ...`
+ |
+ | :codenormal:`# Set up the Tarantool rock list in ~/.luarocks,`
+ | :codenormal:`# following instructions at rocks.tarantool.org`
+ | :codenormal:`$` :codebold:`mkdir ~/.luarocks`
+ | :codenormal:`$` :codebold:`echo "rocks_servers = {[[http://rocks.tarantool.org/]]}" >> ~/.luarocks/config.lua`
+ |
+ | :codenormal:`# Ensure that the next "install" will get files from Tarantool master repository`
+ | :codenormal:`# The resultant display is normal for Ubuntu 12.04 precise`
+ | :codenormal:`$` :codebold:`cat /etc/apt/sources.list.d/tarantool.list`
+ | :codenormal:`deb http://tarantool.org/dist/master/ubuntu/ precise main`
+ | :codenormal:`deb-src http://tarantool.org/dist/master/ubuntu/ precise main`
+ |
+ | :codenormal:`# Install tarantool-dev. The displayed line should show version = 1.6`
+ | :codenormal:`$` :codebold:`sudo apt-get -y install tarantool-dev | grep "Setting up"`
+ | :codenormal:`Setting up tarantool-dev (1.6.6.222.g48b98bb~precise-1) ...`
| :codenormal:`$`
|
- | :codenormal:`# The MySQL module should now be in ./src/module/mysql/mysql.so.`
- | :codenormal:`# If a "make install" had been done, then mysql.so would be in a`
- | :codenormal:`# different place, for example`
- | :codenormal:`# /usr/local/lib/x86_64-linux-gnu/tarantool/box/net/mysql.so.`
- | :codenormal:`# In that case there should be additional cmake options such as`
- | :codenormal:`# -DCMAKE_INSTALL_LIBDIR and -DCMAKE_INSTALL_PREFIX.`
- | :codenormal:`# For this example we assume that "make install" is not done.`
+ | :codenormal:`# Use luarocks to install locally, that is, relative to $HOME`
+ | :codenormal:`$` :codebold:`luarocks install mysql MYSQL_LIBDIR=/usr/local/mysql/lib --local`
+ | :codenormal:`Installing http://rocks.tarantool.org/mysql-scm-1.rockspec...`
+ | :codenormal:`... (more information about building the Tarantool/MySQL driver appears here) ...`
+ | :codenormal:`mysql scm-1 is now built and installed in ~/.luarocks/`
+ |
+ | :codenormal:`# Ensure driver.so now has been created in a place tarantool will look at`
+ | :codenormal:`$` :codebold:`find ~/.luarocks -name "driver.so"`
+ | :codenormal:`~/.luarocks/lib/lua/5.1/mysql/driver.so`
|
| :codenormal:`# Change directory to a directory which can be used for temporary tests.`
| :codenormal:`# For this example we assume that the name of this directory is`
| :codenormal:`# /home/pgulutzan/tarantool_sandbox. (Change "/home/pgulutzan" to whatever`
- | :codenormal:`# is the actual base directory for the machine that's used for this test.)`
- | :codenormal:`# Now, to help tarantool find the essential mysql.so file, execute these lines:`
+ | :codenormal:`# is the user's actual home directory for the machine that's used for this test.)`
| :codebold:`cd /home/pgulutzan/tarantool_sandbox`
- | :codebold:`mkdir box`
- | :codebold:`mkdir box/net`
- | :codebold:`cp ~/tarantool/src/module/mysql/mysql.so ./box/net/mysql.so`
|
| :codenormal:`# Start the Tarantool server. Do not use a Lua initialization file.`
|
- | :codenormal:`$` :codebold:`~/tarantool/src/tarantool`
- | :codenormal:`~/tarantool/src/tarantool: version 1.6.3-439-g7e1011b`
+ | :codenormal:`$` :codebold:`tarantool`
+ | :codenormal:`tarantool: version 1.6.6-222-g48b98bb`
| :codenormal:`type 'help' for interactive help`
| :codenormal:`tarantool>` :codebold:`box.cfg{}`
| :codenormal:`...`
- | :codenormal:`# Enter the following lines on the prompt (again, change "/home/pgulutzan"`
- | :codenormal:`# to whatever the real directory is that contains tarantool):`
- | :codenormal:`package.path = "/home/pgulutzan/tarantool/src/module/sql/?.lua;"..package.path`
- | :codenormal:`require("sql")`
- | :codenormal:`if type(box.net.sql) ~= "table" then error("net.sql load failed") end`
- | :codenormal:`require("box.net.mysql")`
- | :codenormal:`# ... Make sure that tarantool replies "true" for both calls to "require()".`
+ | :codenormal:`# Request the mysql package`
+ | :codenormal:`tarantool>` :codebold:`mysql = require('mysql')`
+ | :codenormal:`# ... Make sure that tarantool does not reply "error" for the call to "require()".`
|
| :codenormal:`# Create a Lua function that will connect to the MySQL server,`
| :codenormal:`# (using some factory default values for the port and user and password),`
@@ -143,13 +265,14 @@ mysqld server is already running on the local host 127.0.0.1.
| :codenormal:`# Lua tutorial earlier in the Tarantool user manual.`
| :codenormal:`tarantool>` :codebold:`console = require('console'); console.delimiter('!')`
| :codenormal:`tarantool>` :codebold:`function mysql_select ()`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local dbh = box.net.sql.connect(`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`'mysql', '127.0.0.1', 3306, 'root', '', 'test')`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local test = dbh:select('SELECT * FROM test WHERE s1 = 1')`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local conn = mysql.connect(`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`{host='127.0.0.1', port=3306, user='root', db='test'})`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local test = conn:execute('SELECT * FROM test WHERE s1 = 1')`
| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local row = ''`
| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`for i, card in pairs(test) do`
| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`row = row .. card.s2 .. ' '`
| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`end`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`conn:close()`
| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`return row`
| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`end!`
| :codenormal:`---`
@@ -166,25 +289,145 @@ mysqld server is already running on the local host 127.0.0.1.
| :codenormal:`# So this is the row that was inserted into the MySQL database.`
| :codenormal:`# And now it's been selected with the Tarantool client.`
+
===========================================================
PostgreSQL Example
===========================================================
-This example assumes that a recent version of PostgreSQL has been installed.
-The PostgreSQL library and include files are also necessary. On Ubuntu they
-can be installed with
-
- | :codebold:`$ sudo apt-get install libpq-dev`
-
-If that works, then cmake will find the necessary files without requiring any
-special user input. However, because not all platforms are alike, for this
+This example assumes that PostgreSQL 8 or PostgreSQL 9 has been installed.
+More recent versions should also work.
+The package that matters most is the PostgreSQL
+developer package, typically named something like libpq-dev.
+On Ubuntu this can be installed with |br|
+:codebold:`sudo apt-get install libpq-dev` |br|
+However, because not all platforms are alike, for this
example the assumption is that the user must check that the appropriate
PostgreSQL files are present and must explicitly state where they are when
-building Tarantool from source.
+building the Tarantool/PostgreSQL driver.
+One can use :code:`find` or :code:`whereis` to see what
+directories PostgreSQL files are installed in.
+
+It will be necessary to install Tarantool's PostgreSQL driver shared library,
+load it, and use it to connect to a PostgreSQL server.
+After that, one can pass any PostgreSQL statement to the server and
+receive results.
+
+HOW TO INSTALL:
+
+Check the instructions for
+:ref:`Downloading and installing a binary package <downloading-and-installing-a-binary-package>`
+that apply for the environment where tarantool was installed.
+In addition to installing :code:`tarantool`, install :code:`tarantool-dev`.
+For example, on Ubuntu, add the line |br|
+:codebold:`sudo apt-get install tarantool-dev`
+
+Now, for the PostgreSQL driver shared library, there are two ways to install:
+with luarocks or with github.
-The example was run on a Linux machine where the base directory had a copy of
-the Tarantool source on ~/tarantool, and a copy of PostgreSQL on /usr. The
-postgres server is already running on the local host 127.0.0.1.
+With luarocks ... Begin by installing luarocks and making sure that
+tarantool is among the upstream servers, as in the instructions on
+`rocks.tarantool.org`_, the Tarantool luarocks page. Now execute this: |br|
+:codenormal:`luarocks install pg [POSTGRESQL_LIBDIR=` :codeitalic:`name` :codenormal:`] [POSTGRESQL_INCDIR=` :codeitalic:`name` :codenormal:`] [--local]` |br|
+For example: |br|
+:codebold:`luarocks install pg POSTGRESQL_LIBDIR=/usr/local/postgresql/lib`
+
+With github ... go the site `github.com/tarantool/pg`_.
+Follow the instructions there, saying
+
+ | :codebold:`git clone https://github.com/tarantool/pg.git`
+ | :codebold:`cd pg && cmake . -DCMAKE_BUILD_TYPE=RelWithDebugInfo`
+ | :codebold:`make`
+ | :codebold:`make install`
+
+At this point it is a good idea to check that the installation
+produced a file named :code:`driver.so`, and to check that this file
+is on a directory that is searched by the :code:`require` request.
+
+HOW TO CONNECT:
+
+Begin by making a :code:`require` request for the pg driver.
+For example, :codebold:`pg = require('pg')`.
+We will assume that the name is :code:`pg` in further examples.
+
+Now, say |br|
+:codenormal:`connection_name = pg.connect(` :codeitalic:`connection options` :codenormal:`)` |br|
+The connection-options parameter is a table.
+The possible options are: |br|
+:codenormal:`host =` :codeitalic:`host-name` -- string |br|
+:codenormal:`port =` :codeitalic:`port-number` -- number |br|
+:codenormal:`user =` :codeitalic:`user-name` -- string |br|
+:codenormal:`password =` :codeitalic:`password` or :codenormal:`pass =` :codeitalic:`password` -- string |br|
+:codenormal:`db =` :codeitalic:`database-name` -- string |br|
+The names are similar to the names that PostgreSQL itself uses.
+|br|
+
+Example, using a table literal enclosed in {braces}: |br|
+:codebold:`conn = pg.connect({host='127.0.0.1', port=3306, user='p', password='p', db='test'})` |br|
+
+Example, creating a function which sets each option in a separate line:
+ | :codenormal:`# Connection function. Usage: conn = pg_connect()`
+ | :codenormal:`tarantool>` :codebold:`console = require('console'); console.delimiter('!')`
+ | :codenormal:`tarantool>` :codebold:`function pg_connect ()`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`p = {}`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`p.host = 'widgets.com'`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`p.db = 'test'`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`conn = pg.connect(p)`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`return conn`
+ | |nbsp| |nbsp| |nbsp| :codenormal:`>` :codebold:`end!`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`console.delimiter('')!`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`conn = pg_connect()`
+ | :codenormal:`---`
+ | :codenormal:`...`
+
+We will assume that the name is 'conn' in further examples.
+
+HOW TO PING:
+
+To ensure that a connection is working, the request is:
+
+ | :codeitalic:`connection-name` :codenormal:`:` :codenormal:`ping()`
+
+Example: |br|
+ | :codenormal:`tarantool>` :codebold:`conn:ping()`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
+
+HOW TO EXECUTE A STATEMENT: |br|
+
+For all PostgreSQL statements, the request is: |br|
+:codeitalic:`connection-name` :codenormal:`:` :codenormal:`execute(` :codeitalic:`sql-statement` [, :codeitalic:`parameters` :codenormal:`])` |br|
+where :code:`sql-statement` is a string, and the optional :code:`parameters`
+are extra values that can be plugged in to replace any question marks ("?"s) in the SQL statement. |br|
+
+For example: |br|
+ | :codenormal:`tarantool>` :codebold:`conn:execute('select tablename from pg_tables')`
+ | :codenormal:`---`
+ | :codenormal:`- - table_name: ALL_PLUGINS`
+ | |nbsp| |nbsp| :codenormal:`- tablename: pg_statistic`
+ | |nbsp| |nbsp| :codenormal:`- tablename: pg_type`
+ | |nbsp| :codenormal:`...`
+ | :codenormal:`...`
+
+HOW TO CLOSE:
+
+To end a session that began with :code:`pg.connect`, the request is: |br|
+:codeitalic:`connection-name` :codenormal:`:` :codenormal:`close()` |br|
+For example: |br|
+:codebold:`conn:close()`
+
+For further information, including examples of rarely-used requests,
+see the README.md file at `github.com/tarantool/pg`_.
+
+LONG EXAMPLE:
+
+The example was run on an Ubuntu 12.04 ("precise") machine where tarantool
+had been installed in a /usr subdirectory, and a copy of PostgreSQL had been installed on /usr. The
+PostgreSQL server is already running on the local host 127.0.0.1.
| :codenormal:`# Check that the include subdirectory exists`
| :codenormal:`# by looking for /usr/include/postgresql/libpq-fe-h.`
@@ -192,7 +435,7 @@ postgres server is already running on the local host 127.0.0.1.
| :codenormal:`OK`
|
| :codenormal:`# Check that the library subdirectory exists and has the necessary .so file.`
- | :codenormal:`$` :codebold:`[ -f /usr/lib/libpq.so ] && echo "OK" || echo "Error"`
+ | :codenormal:`$` :codebold:`[ -f /usr/lib/x86_64-linux-gnu/libpq.so ] && echo "OK" || echo "Error"`
| :codenormal:`OK`
|
| :codenormal:`# Check that the psql client can connect using some factory defaults:`
@@ -212,80 +455,89 @@ postgres server is already running on the local host 127.0.0.1.
| :codenormal:`postgres=#` :codebold:`\\q`
| :codenormal:`$`
|
- | :codenormal:`# Build the Tarantool server. Make certain that "cmake" gets the right`
- | :codenormal:`# paths for the PostgreSQL include directory and the PostgreSQL libpq`
- | :codenormal:`# library which were checked earlier.`
- | :codenormal:`$` :codebold:`cd ~/tarantool`
- | :codenormal:`$` :codebold:`make clean`
- | :codenormal:`$` :codebold:`rm CMakeCache.txt`
- | :codenormal:`$` :codebold:`cmake . -DWITH_POSTGRESQL=on -DPostgreSQL_LIBRARY=/usr/lib/libpq.so\\`
- | :codenormal:`>` |nbsp| :codebold:`-DPostgreSQL_INCLUDE_DIR=/usr/include/postgresql`
- | :codenormal:`...`
- | :codenormal:`-- Found PostgreSQL: /usr/lib/libpq.so (found version "9.3.2")`
- | :codenormal:`...`
- | :codenormal:`-- Configuring done`
- | :codenormal:`-- Generating done`
- | :codenormal:`-- Build files have been written to: ~/tarantool`
- | :codenormal:`$` :codebold:`make`
- | :codenormal:`...`
- | :codenormal:`[ 79%] Building CXX object src/plugin/pg/CMakeFiles/pg.dir/pg.cc.o`
- | :codenormal:`Linking CXX shared library libpg.so`
- | :codenormal:`[ 79%] Built target pg`
- | :codenormal:`...`
- | :codenormal:`[100%] Built target man`
+ | :codenormal:`# Install luarocks`
+ | :codenormal:`$` :codebold:`sudo apt-get -y install luarocks | grep "Setting up"`
+ | :codenormal:`Setting up luarocks (2.0.8-2) ...`
+ |
+ | :codenormal:`# Set up the Tarantool rock list in ~/.luarocks,`
+ | :codenormal:`# following instructions at rocks.tarantool.org`
+ | :codenormal:`$` :codebold:`mkdir ~/.luarocks`
+ | :codenormal:`$` :codebold:`echo "rocks_servers = {[[http://rocks.tarantool.org/]]}" >> ~/.luarocks/config.lua`
+ |
+ | :codenormal:`# Ensure that the next "install" will get files from Tarantool master repository`
+ | :codenormal:`# The resultant display is normal for Ubuntu 12.04 precise`
+ | :codenormal:`$` :codebold:`cat /etc/apt/sources.list.d/tarantool.list`
+ | :codenormal:`deb http://tarantool.org/dist/master/ubuntu/ precise main`
+ | :codenormal:`deb-src http://tarantool.org/dist/master/ubuntu/ precise main`
+ |
+ | :codenormal:`# Install tarantool-dev. The displayed line should show version = 1.6`
+ | :codenormal:`$` :codebold:`sudo apt-get -y install tarantool-dev | grep "Setting up"`
+ | :codenormal:`Setting up tarantool-dev (1.6.6.222.g48b98bb~precise-1) ...`
| :codenormal:`$`
|
+ | :codenormal:`# Use luarocks to install locally, that is, relative to $HOME`
+ | :codenormal:`$` :codebold:`luarocks install pg POSTGRESQL_LIBDIR=/usr/lib/x86_64-linux-gnu --local`
+ | :codenormal:`Installing http://rocks.tarantool.org/pg-scm-1.rockspec...`
+ | :codenormal:`... (more information about building the Tarantool/PostgreSQL driver appears here) ...`
+ | :codenormal:`pg scm-1 is now built and installed in ~/.luarocks/`
+ |
+ | :codenormal:`# Ensure driver.so now has been created in a place tarantool will look at`
+ | :codenormal:`$` :codebold:`find ~/.luarocks -name "driver.so"`
+ | :codenormal:`~/.luarocks/lib/lua/5.1/pg/driver.so`
+ |
| :codenormal:`# Change directory to a directory which can be used for temporary tests.`
| :codenormal:`# For this example we assume that the name of this directory is`
| :codenormal:`# /home/pgulutzan/tarantool_sandbox. (Change "/home/pgulutzan" to whatever`
- | :codenormal:`# is the actual base directory for the machine that's used for this test.)`
- | :codenormal:`# Now, to help tarantool find the essential mysql.so file, execute these lines:`
+ | :codenormal:`# is the user's actual home directory for the machine that's used for this test.)`
| :codebold:`cd /home/pgulutzan/tarantool_sandbox`
- | :codebold:`mkdir box`
- | :codebold:`mkdir box/net`
- | :codebold:`cp ~/tarantool/src/module/pg/pg.so ./box/net/pg.so`
|
| :codenormal:`# Start the Tarantool server. Do not use a Lua initialization file.`
|
- | :codenormal:`$` :codebold:`~/tarantool/src/tarantool`
- | :codenormal:`~/tarantool/src/tarantool: version 1.6.3-439-g7e1011b`
+ | :codenormal:`$` :codebold:`tarantool`
+ | :codenormal:`tarantool: version 1.6.6-222-g48b98bb`
| :codenormal:`type 'help' for interactive help`
| :codenormal:`tarantool>` :codebold:`box.cfg{}`
- |
- | :codenormal:`# Enter the following lines on the prompt (again, change "/home/pgulutzan"`
- | :codenormal:`# to whatever the real directory is that contains tarantool):`
- | :codenormal:`package.path = "/home/pgulutzan/tarantool/src/module/sql/?.lua;"..package.path`
- | :codenormal:`require("sql")`
- | :codenormal:`if type(box.net.sql) ~= "table" then error("net.sql load failed") end`
- | :codenormal:`require("box.net.pg")`
- | :codenormal:`# ... Make sure that tarantool replies "true" for the calls to "require()".`
+ | :codenormal:`...`
+ | :codenormal:`# Request the pg package`
+ | :codenormal:`tarantool>` :codebold:`pg = require('pg')`
+ | :codenormal:`# ... Make sure that tarantool does not reply "error" for the call to "require()".`
|
| :codenormal:`# Create a Lua function that will connect to the PostgreSQL server,`
+ | :codenormal:`# (using some factory default values for the port and user and password),`
| :codenormal:`# retrieve one row, and display the row.`
| :codenormal:`# For explanations of the statement types used here, read the`
- | :codenormal:`# Lua tutorial in the Tarantool user manual.`
+ | :codenormal:`# Lua tutorial earlier in the Tarantool user manual.`
| :codenormal:`tarantool>` :codebold:`console = require('console'); console.delimiter('!')`
- | :codenormal:`tarantool>` :codebold:`function postgresql_select ()`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| :codebold:`local dbh = box.net.sql.connect(`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| |nbsp| :codebold:`'pg', '127.0.0.1', 5432, 'postgres', 'postgres', 'postgres')`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| :codebold:`local test = dbh:select('SELECT * FROM test WHERE s1 = 1')`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| :codebold:`local row = ''`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| :codebold:`for i, card in pairs(test) do`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| |nbsp| :codebold:`row = row .. card.s2 .. ' '`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| |nbsp| :codebold:`end`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| :codebold:`return row`
- | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| :codebold:`end!`
+ | :codenormal:`tarantool>` :codebold:`function pg_select ()`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local conn = pg.connect(`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`{host='127.0.0.1', port=5432, user='postgres', password='postgres', db='postgres'})`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local test = conn:execute('SELECT * FROM test WHERE s1 = 1')`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`local row = ''`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`for i, card in pairs(test) do`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`row = row .. card.s2 .. ' '`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| |nbsp| |nbsp| :codebold:`end`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`conn:close()`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`return row`
+ | |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`->` |nbsp| :codebold:`end!`
| :codenormal:`---`
| :codenormal:`...`
| :codenormal:`tarantool>` :codebold:`console.delimiter('')!`
| :codenormal:`tarantool>`
|
| :codenormal:`# Execute the Lua function.`
- | :codenormal:`tarantool>` :codebold:`postgresql_select()`
+ | :codenormal:`tarantool>` :codebold:`pg_select()`
| :codenormal:`---`
| :codenormal:`- 'PostgreSQL row '`
| :codenormal:`...`
- |
| :codenormal:`# Observe the result. It contains "PostgreSQL row".`
| :codenormal:`# So this is the row that was inserted into the PostgreSQL database.`
| :codenormal:`# And now it's been selected with the Tarantool client.`
+
+
+.. _gist.github.com/rtsisyk/aa95cf9ed9bbb538ff80: https://gist.github.com/rtsisyk/aa95cf9ed9bbb538ff80
+.. _rocks.tarantool.org: http://rocks.tarantool.org/
+.. _github.com/tarantool/mysql: https://github.com/tarantool/mysql
+.. _dev.mysql.com/doc/refman/5.6/en/connecting.html: https://dev.mysql.com/doc/refman/5.6/en/connecting.html
+.. _github.com/tarantool/mysql: https://github.com/tarantool/mysql
+.. _github.com/tarantool/pg: https://github.com/tarantool/pg
+
diff --git a/doc/sphinx/book/box/box_index.rst b/doc/sphinx/book/box/box_index.rst
index c269c7009b286b17e5fae6bd5c973ce5c26f1a4a..7fad8932fd69db0fe2daa496e67cbb512175c0d8 100644
--- a/doc/sphinx/book/box/box_index.rst
+++ b/doc/sphinx/book/box/box_index.rst
@@ -196,47 +196,47 @@ API is a direct binding to corresponding methods of index objects of type
**RTREE iterator types**
- +--------------------+-----------+---------------------------------------------+
- | Type | Arguments | Description |
- +====================+===========+=============================================+
- | box.index.ALL | none | All keys match. Tuples are returned in |
- | or 'ALL' | | ascending order of the primary key. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.EQ | field | Keys match if the rectangle defined by the |
- | or 'EQ' | values | field values is the same as the rectangle |
- | | | defined by the key -- where "key" means |
- | | | "the key in the RTREE index" and |
- | | | "rectangle" means "rectangle as explained |
- | | | in section RTREE_. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.GT | field | Keys match if all points of the rectangle |
- | or 'GT' | values | defined by the field values are within the |
- | | | rectangle defined by the key. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.GE | field | Keys match if all points of the rectangle |
- | or 'GE' | values | defined by the field values are within, or |
- | | | at the side of, the rectangle defined by |
- | | | the key. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.LT | field | Keys match if all points of the rectangle |
- | or 'LT' | values | defined by the key are within the rectangle |
- | | | defined by the field values. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.LE | field | Keys match if all points of the rectangle |
- | or 'LE' | values | defined by the key are within, or at the |
- | | | side of, the rectangle defined by the field |
- | | | values. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.OVERLAPS | field | Keys match if all points of the rectangle |
- | or 'OVERLAPS' | values | defined by the key are within, or at the |
- | | | side of, the rectangle defined by the field |
- | | | values. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.NEIGHBOR | field | Keys match if all points of the rectangle |
- | or 'NEIGHBOR' | values | defined by the key are within, or at the |
- | | | side of, the rectangle defined by the field |
- | | | values. |
- +--------------------+-----------+---------------------------------------------+
+ +--------------------+-----------+-----------------------------------------------------+
+ | Type | Arguments | Description |
+ +====================+===========+=====================================================+
+ | box.index.ALL | none | All keys match. Tuples are returned in |
+ | or 'ALL' | | ascending order of the primary key. |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.EQ | field | Keys match if the rectangle-or-box defined by the |
+ | or 'EQ' | values | field values is the same as the rectangle-or-box |
+ | | | defined by the key -- where "key" means |
+ | | | "the key in the RTREE index" and |
+ | | | "rectangle-or-box" means "rectangle-or-box as |
+ | | | explained in section RTREE_". |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.GT | field | Keys match if all points of the rectangle-or-box |
+ | or 'GT' | values | defined by the field values are within the |
+ | | | rectangle-or-box defined by the key. |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.GE | field | Keys match if all points of the rectangle-or-box |
+ | or 'GE' | values | defined by the field values are within, or |
+ | | | at the side of, the rectangle-or-box defined by |
+ | | | the key. |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.LT | field | Keys match if all points of the rectangle-or-box |
+ | or 'LT' | values | defined by the key are within the rectangle-or-box |
+ | | | defined by the field values. |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.LE | field | Keys match if all points of the rectangle-or-box |
+ | or 'LE' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle-or-box defined by the field |
+ | | | values. |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.OVERLAPS | field | Keys match if all points of the rectangle-or-box |
+ | or 'OVERLAPS' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle-or-box defined by the field |
+ | | | values. |
+ +--------------------+-----------+-----------------------------------------------------+
+ | box.index.NEIGHBOR | field | Keys match if all points of the rectangle-or-box |
+ | or 'NEIGHBOR' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle-or-box defined by the field |
+ | | | values. |
+ +--------------------+-----------+-----------------------------------------------------+
|br|
@@ -627,7 +627,14 @@ Lua functions `os.date()`_ and `string.sub()`_.
=============================================================================
The :mod:`box.index` package may be used for spatial searches if the index type
-is RTREE. There are operations for searching *rectangles*. Rectangles are
+is RTREE. There are operations for searching *rectangles* (geometric objects
+with 4 corners and 4 sides) and *boxes* (geometric objects with more than 4
+corners and more than 4 sides, sometimes called hyperrectangles).
+This manual uses term *rectangle-or-box* for the whole class
+of objects that includes both rectangles and boxes.
+Only rectangles will be illustrated.
+
+Rectangles are
described according to their X-axis (horizontal axis) and Y-axis (vertical axis)
coordinates in a grid of arbitrary size. Here is a picture of four rectangles on
a grid with 11 horizontal points and 11 vertical points:
@@ -693,6 +700,20 @@ NEIGHBOR iterator always returns all tuples, and the first returned tuple will
be {3,5,9,10} ("Rectangle#2" in the picture) because it is the closest neighbor
of {1,2,3,4} ("Rectangle#1" in the picture).
+Now let us create a space and index for cuboids, which are rectangle-or-boxes that have
+6 corners and 6 sides.
+
+ | :codebold:`box.schema.space.create('R')`
+ | :codebold:`box.space.R:create_index('primary',{parts={1,'NUM'}})`
+ | :codebold:`box.space.R:create_index('S',{type='RTREE',unique=false,dimension=3,parts={2,'ARRAY'}})`
+
+The additional field here is 'dimension=3'. The default dimension is 2, which is
+why it didn't need to be specified for the examples of rectangle. The maximum dimension
+is 20. Now for insertions and selections there will usually be 6 coordinates. For example:
+
+ | :codebold:`box.space.R:insert{1,{0,3,0,3,0,3}}`
+ | :codebold:`box.space.R.index.S:select({1,2,1,2,1,2},{iterator=box.index.GT})`
+
More examples of spatial searching are online in the file `R tree index quick
start and usage`_.
diff --git a/doc/sphinx/book/box/box_space.rst b/doc/sphinx/book/box/box_space.rst
index c8080e942da6825404c095e78d0ef2646ea4800d..c9f222814b08385bb235cea362366a3cd6ae8224 100644
--- a/doc/sphinx/book/box/box_space.rst
+++ b/doc/sphinx/book/box/box_space.rst
@@ -5,7 +5,7 @@
.. module:: box.space
The ``box.space`` package has the data-manipulation functions ``select``,
-``insert``, ``replace``, ``update``, ``delete``, ``get``, ``put``. It also has
+``insert``, ``replace``, ``update``, ``upsert``, ``delete``, ``get``, ``put``. It also has
members, such as id, and whether or not a space is enabled. Package source code
is available in file
`src/box/lua/schema.lua <https://github.com/tarantool/tarantool/blob/master/src/box/lua/schema.lua>`_.
@@ -65,6 +65,8 @@ A list of all ``box.space`` functions follows, then comes a list of all
| :codenormal:`---`
| :codenormal:`...`
+.. _box_insert:
+
.. function:: insert(tuple)
Insert a tuple into a space.
@@ -233,6 +235,8 @@ A list of all ``box.space`` functions follows, then comes a list of all
Example: :codenormal:`tarantool>` :codebold:`box.space.tester:replace{5000, 'New value'}`
+.. _box_update:
+
.. function:: update(key, {{operator, field_no, value}, ...})
Update a tuple.
@@ -359,6 +363,42 @@ A list of all ``box.space`` functions follows, then comes a list of all
| :codenormal:`box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})`
+ .. function:: upsert(key, {{operator, field_no, value}, ...}, {tuple})
+
+ Update or insert a tuple.
+
+ If there is an existing tuple which matches :code:`key`, then the
+ request has the same effect as :ref:`update <box_update>` and the
+ :code:`{{operator, field_no, value}, ...}` parameter is used.
+ If there is no existing tuple which matches :code:`key`, then the
+ request has the same effect as :ref:`insert <box_insert>` and the
+ :code:`{tuple}` parameter is used. However, unlike :code:`insert` or
+ :code:`update`, :code:`upsert` will not read a tuple and perform
+ error checks before returning -- this is a design feature which
+ enhances throughput but requires more caution on the part of the user.
+
+ :param space_object space-object:
+ :param lua-value key: primary-key field values, must be passed as a Lua
+ table if key is multi-part
+ :param table {operator, field_no, value}: a group of arguments for each
+ operation, indicating what the operation is, what field the
+ operation will apply to, and what value will be applied. The
+ field number can be negative, meaning the position from the
+ end of tuple (#tuple + negative field number + 1).
+
+ :return: null.
+
+
+ Possible errors: it is illegal to modify a primary-key field.
+
+ Complexity Factors: Index size, Index type, number of indexes accessed, WAL
+ settings.
+
+ | :codebold:`Example:`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:upsert({12},{{'=',3,'a'},{'=',4,'b'}},{13,'c'})`
+
+
.. function:: delete(key)
Delete a tuple identified by a primary key.
diff --git a/doc/sphinx/book/box/index.rst b/doc/sphinx/book/box/index.rst
index 458a72ad79349fd0d24852c21ebecac0946ccc1b..4bb9b957a2712ff500563257f508eb2ca38838b1 100644
--- a/doc/sphinx/book/box/index.rst
+++ b/doc/sphinx/book/box/index.rst
@@ -199,8 +199,8 @@ For more tuple examples see :ref:`box.tuple <box-tuple>`.
Operations
----------
-The basic operations are: the four data-change operations
-(insert, update, delete, replace), and the data-retrieval
+The basic operations are: the five data-change operations
+(insert, update, upsert, delete, replace), and the data-retrieval
operation (select). There are also minor operations like
“ping†which can only be used with the binary protocol.
Also, there are :ref:`index iterator <index-iterator>` operations, which can only
@@ -422,10 +422,10 @@ Data manipulation
-----------------
The basic "data-manipulation" requests are:
-:codenormal:`insert`, :codenormal:`replace`, :codenormal:`update`,
+:codenormal:`insert`, :codenormal:`replace`, :codenormal:`update`, :codenormal:`upsert`,
:codenormal:`delete`, :codenormal:`select`.
-They all are part of the :codenormal:`box` library.
-They all may return data. Usually both inputs and outputs may be Lua tables.
+All of them are part of the :codenormal:`box` library.
+Most of them may return data. Usually both inputs and outputs may be Lua tables.
The Lua syntax for data-manipulation functions can vary.
Here are examples of the variations with :codenormal:`select` examples;
@@ -495,7 +495,7 @@ no arguments. The packages inside the box library are:
box.schema, box.tuple, box.space, box.index, net.box, box.cfg, box.info, box.slab, box.stat.
Every package contains one or more Lua functions. A few packages contain
members as well as functions. The functions allow data definition (create
-alter drop), data manipulation (insert delete update select replace), and
+alter drop), data manipulation (insert delete update upsert select replace), and
introspection (inspecting contents of spaces, accessing server configuration).
diff --git a/doc/sphinx/book/box/limitations.rst b/doc/sphinx/book/box/limitations.rst
index 7851d49ad1c081f9b3c8626ac2187e5254614cd1..755deb9e01543a8272fcdd277e23d637f8139b5c 100644
--- a/doc/sphinx/book/box/limitations.rst
+++ b/doc/sphinx/book/box/limitations.rst
@@ -4,8 +4,8 @@
Number of fields in an index
For BITSET indexes, the maximum is 1. For TREE or HASH indexes, the maximum
- is 255 (``box.schema.INDEX_PART_MAX``). For RTREE indexes, the number of
- fields must be either 2 or 4.
+ is 255 (``box.schema.INDEX_PART_MAX``). For RTREE indexes, the
+ maximum is 1 but the field is an ARRAY.
Number of indexes in a space
10 (``box.schema.INDEX_MAX``).
diff --git a/doc/sphinx/book/box/triggers.rst b/doc/sphinx/book/box/triggers.rst
index 80864adbe38b83695107cefcb3fc164b113961bd..b47f01108bf7ab22bef5f38eb11bb751309a87b6 100644
--- a/doc/sphinx/book/box/triggers.rst
+++ b/doc/sphinx/book/box/triggers.rst
@@ -145,7 +145,7 @@ Here is what might appear in the log file in a typical installation:
.. function:: box.space.<space-name>:on_replace(trigger-function [, old-trigger-function])
Create a "``replace trigger``". The ``function-name`` will be executed whenever
- a ``replace()`` or ``insert()`` or ``update()`` or ``delete()`` happens to a
+ a ``replace()`` or ``insert()`` or ``update()`` or ``upsert()`` or ``delete()`` happens to a
tuple in ``<space-name>``.
:param function trigger-function: function which will become the trigger function
diff --git a/doc/sphinx/dev_guide/building_documentation.rst b/doc/sphinx/dev_guide/building_documentation.rst
new file mode 100644
index 0000000000000000000000000000000000000000..70aa4a85bc8d17b15b514170eff4c9e3c95b5499
--- /dev/null
+++ b/doc/sphinx/dev_guide/building_documentation.rst
@@ -0,0 +1,49 @@
+.. _building-documentation:
+
+-------------------------------------------------------------------------------
+ Building Documentation
+-------------------------------------------------------------------------------
+
+After building and testing your local instance of Tarantool, you can build a local version of this documentation and contribute to it.
+
+Documentation is based on the python-based Sphinx generator. So, make sure to install all python modules indicated in the BUILDING FROM SOURCE (http://tarantool.org/doc/dev_guide/building_from_source.html) section of this documentation. The procedure below implies that you already took those steps and successfully tested your instance of Tarantool.
+
+1. Build a local version of the existing documentation package.
+
+Run the following set of commands (the example below is based on Ubuntu OS, but the precedure is similar for other supported OS's):
+
+ .. code-block:: bash
+
+ cd ~/tarantool
+ cmake -DENABLE_DOC=TRUE
+ make -C doc
+
+Documentation is created and stored at ``doc/www/output``.
+
+2. Set up a web-server.
+
+Note that if your Tarantool Database runs on a Virtual machine, you need to make sure that your host and client machines operate in the same network, i.e., to configure port forwarding. If you use Oracle VM VirtualBox, follow the guidelines below:
+
+* To create a network, navigate to **Network > Advanced > Port Forwarding** in your VirtualBox instance menu.
+* Enable the **Cable connected** checkbox.
+* Click the **Port Forwarding** button.
+* Set Host and Guest Ports to ``8000``, Host IP to ``127.0.0.1`` and Guest IP to ``10.0.2.15``. Make sure to check the IP of your VB instance, it must be 10.0.2.15 (``ifconfig`` command)
+* Save your settings
+
+If all the prerequisites are met, run the following command to set up a web-server (the example below is based on Ubuntu, but the procedure is similar for other supported OS's). Make sure to run it from the documentation output folder, as specified below:
+
+ .. code-block:: bash
+
+ cd ~/tarantool/doc/www/output
+ python -m SimpleHTTPServer 8000
+
+3. Open your browser and enter ``127.0.0.1:8000`` into the address box. If your local documentation build is valid, the HTML version will be displayed in the browser.
+
+To contribute to documentation, use the ``.rst`` format for drafting and submit your updates as "Pull Requests" via GitHub.
+
+To comply with the writing and formatting style, use guidelines provided in the documentation, common sense and existing documents.
+
+Note that if you suggest creating a new documentation section (i.e., a whole new page), it has to be saved to the relevant section at GitHub.
+
+* Root folder for documentation source files is located at https://github.com/tarantool/tarantool/tree/master/doc/sphinx.
+* Source files for the developers' guide are located at https://github.com/tarantool/tarantool/tree/master/doc/sphinx/dev_guide.
diff --git a/doc/sphinx/getting_started.rst b/doc/sphinx/getting_started.rst
index dcd45fad51dd3d626186cd17af5ee044f576abd9..ee623d302becd97b0060fcd6567476cf3bb7e4b7 100644
--- a/doc/sphinx/getting_started.rst
+++ b/doc/sphinx/getting_started.rst
@@ -23,6 +23,8 @@ provided some instructions that you can use to make a temporary “sandboxâ€. I
few minutes you can start the server and type in some database-manipulation
statements. The section about sandbox is “`Starting Tarantool and making your first database`_â€.
+.. _downloading-and-installing-a-binary-package:
+
=====================================================================
Downloading and installing a binary package
=====================================================================
diff --git a/src/box/vclock.h b/src/box/vclock.h
index ce35b2ab7478af9ef381be0a40d0a9473ef08084..ccd8bf8b044e87154ed477737710d1169915bbbf 100644
--- a/src/box/vclock.h
+++ b/src/box/vclock.h
@@ -46,7 +46,7 @@
extern "C" {
#endif /* defined(__cplusplus) */
-enum { VCLOCK_MAX = 16 };
+enum { VCLOCK_MAX = 32 };
/** Cluster vector clock */
struct vclock {