diff --git a/README.md b/README.md
index 223a68b012f233464ca4dcae0cfe63331e14c9b2..6fff09fb017f203294c4e8d52a7eaf9285b9ab5d 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
# tarantool [](https://travis-ci.org/tarantool/tarantool)
+[](https://gitter.im/tarantool/tarantool?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
http://tarantool.org
Tarantool is an efficient NoSQL database and a
diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml
index 991b02d654f912c65b99cd565c1ece1a4e53b0d3..2fc5e80431ee9e7d3dbdfe4e95ed0080026c479e 100644
--- a/doc/user/configuration-reference.xml
+++ b/doc/user/configuration-reference.xml
@@ -244,6 +244,17 @@ Starting ARG
relative to work_dir. If not specified, defaults to
work_dir. See also <olink targetptr="wal_dir"/>.</entry>
</row>
+
+ <row>
+ <entry xml:id="sophia_dir" xreflabel="sophia_dir">sophia_dir</entry>
+ <entry>string</entry>
+ <entry>"sophia"</entry>
+ <entry>no</entry>
+ <entry>A directory where sophia files will be stored. Can be
+ relative to work_dir. If not specified, defaults to
+ work_dir/sophia.</entry>
+ </row>
+
<row>
<entry xml:id="core-dump" xreflabel="core-dump">coredump</entry>
<entry>boolean</entry>
@@ -264,7 +275,8 @@ Starting ARG
Note: a replica also binds to this port, and accepts
connections, but these connections can only serve
reads until the replica becomes a master.
- A typical value is 3301.</entry>
+ A typical value is 3301.
+ The listen parameter may also be set for <olink targetptr="local_hot_standby">local hot standby</olink>.</entry>
</row>
<row>
diff --git a/doc/user/data-model.xml b/doc/user/data-model.xml
index 49f391d34a5b9acd9f2b09495b1880837de5e469..1688352de019fcf63a121f329adf0a6e181b9cd5 100644
--- a/doc/user/data-model.xml
+++ b/doc/user/data-model.xml
@@ -302,7 +302,7 @@ Since all data-change operations end with an implicit yield and
an implicit commit, and since no data-change operation can change
more than one tuple, there is no need for any locking.
Consider, for example, a Lua function that does three Tarantool operations:<programlisting>
-s:sel...{999} -- this does not yield and does not commit
+s:select{999} -- this does not yield and does not commit
s:update({...},{{...}}) -- this yields and commits
s:select{999} -- this does not yield and does not commit */</programlisting>
The combination <quote>SELECT plus UPDATE</quote> is an atomic transaction:
diff --git a/doc/user/databases.xml b/doc/user/databases.xml
index f5bdf3791ef6218914de7a0ca6bc049891965e4b..c3dbb6ebc438c292b541738ab5c97534cd5c53db 100644
--- a/doc/user/databases.xml
+++ b/doc/user/databases.xml
@@ -142,6 +142,21 @@
about which Complexity Factors might affect the function's resource usage.
</para>
+ <para>
+ <bridgehead renderas="sect4">The two storage engines: memtx and sophia</bridgehead>
+ A storage engine is a set of very-low-level routines which actually store and retrieve tuple values.
+ Tarantool offers a choice of two storage engines: memtx (the in-memory storage engine)
+ and sophia (the on-disk storage engine). To specify that the engine should be sophia,
+ add a clause: <code>engine = 'sophia'</code>. The manual concentrates on memtx because it is
+ the default and has been around longer. But sophia is a working key-value engine and will especially
+ appeal to users who like to see data go directly to disk, so that recovery time might be
+ shorter and database size might be larger.
+ For architectural explanations and benchmarks, see <link xlink:href="http://sphia.org">sphia.org</link>.
+ On the other hand, sophia lacks some functions and options that are available with memtx.
+ Where that is the case, the relevant description will contain the words
+ "only applicable for the memtx storage engine".
+ </para>
+
</section>
<section xml:id="sp-box-schema">
@@ -180,9 +195,6 @@
<row>
<entry>id</entry><entry>unique identifier</entry><entry>number</entry><entry>last space's id, +1</entry>
</row>
- <row>
- <entry>enabled</entry><entry>space is enabled</entry><entry>true|false</entry><entry>true</entry>
- </row>
<row>
<entry>field_count</entry><entry>fixed field count</entry><entry>number</entry><entry>0 i.e. not fixed</entry>
</row>
@@ -222,17 +234,6 @@ tarantool> <userinput>s = box.schema.space.create('space55', {if_not_exists = tr
then it is available for insert, select, and all the other
<link linkend="box.space">box.space</link> functions.
</para>
- <para>
- <bridgehead renderas="sect4">The Sophia alternative storage engine</bridgehead>
- There are actually two storage engines for Tarantool: memtx (the in-memory storage engine)
- and Sophia (the on-disk storage engine). To specify that the engine should be Sophia,
- add a clause: <code>engine = 'sophia'</code>. The manual concentrates on memtx because it is
- the default and has been around longer. But Sophia is a working key-value engine and will especially
- appeal to users who like to see data go directly to disk, so that recovery time might be
- shorter and database size might be larger. On the other hand, with Sophia the maximum
- number of indexes is 1, and the maximum number of fields per index is 1.
- For architectural explanations and benchmarks, see <link xlink:href="http://sphia.org">sphia.org</link>.
- </para>
</listitem>
</varlistentry>
@@ -306,6 +307,8 @@ tarantool> <userinput>s = box.schema.space.create('space55', {if_not_exists = tr
</para>
<para>
Possible errors: too many parts.
+ A type options other than TREE, or a unique option other than unique, or a parts option with more than one field component,
+ is only applicable for the memtx storage engine.
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
tarantool> <userinput>s = box.space.space55</userinput>
@@ -535,6 +538,7 @@ tarantool> <userinput>box.space.space56:rename('space55')</userinput>
</para>
<para>
Possible errors: The first index cannot be changed to {unique = false}.
+ The <code>alter</code> function is only applicable for the memtx storage engine.
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
tarantool> <userinput>box.space.space55.index.primary:alter({type = 'HASH'})</userinput>
@@ -553,7 +557,7 @@ tarantool> <userinput>box.space.space55.index.primary:alter({type = 'HASH'})</us
</term>
<listitem>
<para>
- Drop an index.
+ Drop an index. Dropping a primary-key index has a side effect: all tuples are deleted.
</para>
<para>
Parameters: none.
@@ -819,7 +823,7 @@ tarantool> <userinput>box.space.tester:delete('a')</userinput>
<term><emphasis role="lua">box.space.<replaceable>space-name</replaceable>.enabled</emphasis></term>
<listitem>
<para>
- (type = boolean) Whether or not this space is enabled.
+ (type = boolean) Whether or not this space is enabled. The value is false if there is no index.
</para>
</listitem>
</varlistentry>
@@ -865,6 +869,7 @@ tarantool> <userinput>box.space.tester:delete('a')</userinput>
<listitem>
<para>
Returns: (type = number) number of tuples in the space.
+ The <code>len()</code> function is only applicable for the memtx storage engine.
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>tarantool> <userinput>box.space.tester:len()</userinput>
---
@@ -1621,6 +1626,7 @@ The result will be a table of tuples and will look like this:
</para>
<para>
Returns: (type = number) the number of matching index keys.
+ The <code>index</code> function is only applicable for the memtx storage engine.
</para>
<para>
<bridgehead renderas="sect4">Example</bridgehead>
@@ -2984,6 +2990,7 @@ error: can't save snapshot, errno 17 (File exists)
In effect the fiber which executes <code>box.begin()</code>
is starting an "active multi-request transaction", blocking all
other fibers until the transaction ends.
+ All operations within this transaction should use the same storage engine.
</para></listitem>
</varlistentry>
@@ -3435,7 +3442,7 @@ box.space.T:insert{1}
<title>Limitations</title>
<variablelist>
-
+
<varlistentry>
<term xml:id="limitations-index-field-count" xreflabel="limitations-index-field-count">Number of fields in an index</term>
<listitem><para>For BITSET indexes, the maximum is 1.
@@ -3479,7 +3486,7 @@ box.space.T:insert{1}
</varlistentry>
<varlistentry>
- <term xml:id="limitations-update-count" xreflabel="limitations-updae-count">Update operations count</term>
+ <term xml:id="limitations-update-count" xreflabel="limitations-update-count">Update operations count</term>
<listitem><para>The maximum number of operations that can be in a single update is 4000 (BOX_UPDATE_OP_CNT_MAX).
</para></listitem>
</varlistentry>
@@ -3495,8 +3502,20 @@ box.space.T:insert{1}
<listitem><para>32 (box.schema.NAME_MAX).
</para></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term xml:id="sophia-limitations" xreflabel="sophia-limitations">Limitations which are only applicable for the sophia storage engine</term>
+ <listitem><para>
+ The maximum number of fields in an index is always 1, that is, multi-part indexes are not supported.
+ The maximum number of indexes in a space is always 1, that is, secondary indexes are not supported.
+ Indexes must be unique, that is, the options type=HASH or type=RTREE or type=BITSET are not supported.
+ Indexes must be unique, that is, the option unique=false is not supported.
+ The alter(), len(), and count() functions are not supported.
+ </para></listitem>
+ </varlistentry>
</variablelist>
+
</section>
diff --git a/doc/user/server-administration.xml b/doc/user/server-administration.xml
index ab651ffe294de1ea3d3b34cd7b64606b3ed244cf..fc95264abb70bbdf5872c48cbe4e4326cd21cf55 100644
--- a/doc/user/server-administration.xml
+++ b/doc/user/server-administration.xml
@@ -258,7 +258,7 @@ snap_dir = The directory for the snapshot *.snap files.
The script will add "/<replaceable>instance-name</replaceable>" to the directory-name.
</para>
<para>
-sophia_dir = The directory for the Sophia-storage-engine files.
+sophia_dir = The directory for the sophia-storage-engine files.
The script will add "/sophia/<replaceable>instance-name</replaceable>" to the directory-name.
</para>
<para>
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index ca40de5bc69a3a54b84562c5c2c52edff86913e2..8ab0fbd064b62ae92d9ddd6db6c165daf1e14d37 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -338,7 +338,7 @@ administration with the built-in packages.
<row><entry>name</entry><entry>effect</entry></row>
</thead>
<tbody>
- <row><entry><code>digest.crc32(<replaceable>string</replaceable>)</code></entry><entry> Returns 32-bit checksum made with CRC32.</entry></row>
+ <row><entry><code>digest.crc32(<replaceable>string</replaceable>)</code></entry><entry> Returns 32-bit checksum made with CRC32. See <link linkend="note-crc32">note</link>.</entry></row>
<row><entry><code>digest.crc32_update(<replaceable>number</replaceable>,<replaceable>string</replaceable>)</code></entry><entry> Returns update of a checksum calculated with CRC32.</entry></row>
<row><entry><code>digest.sha(<replaceable>string</replaceable>)</code></entry><entry> Returns 160-bit digest made with SHA-0. Not recommended.</entry></row>
<row><entry><code>digest.sha_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha.</entry></row>
@@ -358,11 +358,13 @@ administration with the built-in packages.
<row><entry><code>digest.md5_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with md5.</entry></row>
<row><entry><code>digest.base64_encode(<replaceable>string</replaceable>)</code></entry><entry> Returns base64 encoding from a regular string.</entry></row>
<row><entry><code>digest.base64_decode(<replaceable>string</replaceable>)</code></entry><entry> Returns a regular string from a base64 encoding.</entry></row>
+ <row><entry><code>digest.urandom(<replaceable>integer</replaceable>)</code></entry><entry> Returns array of random bytes with length = <replaceable>integer</replaceable>.</entry></row>
+ <row><entry><code>digest.guava(<replaceable>integer, integer</replaceable>)</code></entry><entry> Returns a number made with consistent hash. See <link linkend="note-guava">note</link>.</entry></row>
</tbody>
</tgroup>
</informaltable>
- <note><simpara>
- <code>box.digest.crc32(<replaceable>string</replaceable>)</code> uses the
+ <note xml:id="note-crc32"><simpara>
+ <code>digest.crc32(<replaceable>string</replaceable>)</code> uses the
<link xlink:href="https://en.wikipedia.org/wiki/Cyclic_redundancy_check#Standards_and_common_use">
CRC-32C (Castagnoli)</link> polynomial value: hexadecimal 11EDC6F41 / decimal 4812730177.
If it is necessary to be compatible with other checksum functions in other programming languages,
@@ -370,6 +372,14 @@ administration with the built-in packages.
For example, in Python, install the crcmod package and say:
<code>import crcmod ... fun = crcmod.mkCrcFun('4812730177') ... fun('string')</code>.
</simpara></note>
+ <note xml:id="note-guava"><simpara>
+ <code>digest.guava(<replaceable>integer, integer</replaceable>)</code> uses the
+ <link xlink:href="https://en.wikipedia.org/wiki/Consistent_hashing">
+ Consistent Hashing</link> algorithm of the Google guava library.
+ The first parameter should be a hash code; the second parameter should be the number of buckets;
+ the returned value will be an integer between 0 and the number of buckets.
+ For example, <code>digest.guava(10863919174838991, 11)</code> will return 8.
+ </simpara></note>
</para>
<bridgehead renderas="sect4">Example</bridgehead>
@@ -1021,7 +1031,7 @@ procedures.
<para>
Returns: (type = string) the status of <code>fiber</code>.
One of: <quote>dead</quote>,
- <quote>suspended</quote>, <quote>attached</quote>
+ <quote>suspended</quote>,
or <quote>running</quote>.
</para>
</listitem>
@@ -1041,7 +1051,7 @@ procedures.
<para>
Returns: (type = string) the status of <code>fiber</code>.
One of: <quote>dead</quote>,
- <quote>suspended</quote>, <quote>attached</quote>
+ <quote>suspended</quote>,
or <quote>running</quote>.
</para>
</listitem>