diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml index 81b2ccca1f47f8cf597db2f0fb1075a36cf4bda5..b86c48c7e7033162ef53581cfc2d9f206b82b9b1 100644 --- a/doc/user/configuration-reference.xml +++ b/doc/user/configuration-reference.xml @@ -3,7 +3,7 @@ %tnt; ]> <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" - xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="configuration-reference"> @@ -265,7 +265,7 @@ lsn:4 tm:1301572313.691 t:65534 127.0.0.1:52728 UPDATE_FIELDS n:0flags:00000000 </row> <row> - <entry>wal_dir</entry> + <entry xml:id="wal_dir" xreflabel="wal_dir">wal_dir</entry> <entry>string</entry> <entry>""</entry> <entry>no</entry> @@ -278,14 +278,14 @@ lsn:4 tm:1301572313.691 t:65534 127.0.0.1:52728 UPDATE_FIELDS n:0flags:00000000 </row> <row> - <entry>snap_dir</entry> + <entry xml:id="snap_dir" xreflabel="snap_dir">snap_dir</entry> <entry>string</entry> <entry>""</entry> <entry>no</entry> <entry>no</entry> <entry>A directory to store snapshots in. Can be relative to work_dir. If not specified, defaults to - work_dir. See also wal_dir.</entry> + work_dir. See also <olink targetptr="wal_dir"/>.</entry> </row> <!-- <row> @@ -295,7 +295,7 @@ lsn:4 tm:1301572313.691 t:65534 127.0.0.1:52728 UPDATE_FIELDS n:0flags:00000000 </row> --> <row> - <entry>primary_port</entry> + <entry xml:id="primary_port" xreflabel="primary_port">primary_port</entry> <entry>integer</entry> <entry><emphasis role="strong">none</emphasis></entry> <entry><emphasis role="strong">yes</emphasis></entry> @@ -383,12 +383,15 @@ tarantool: box:primary@sessions pri:33013 sec:33014 adm:33015</programlisting> <tbody> <row> - <entry xml:id="slab_alloc_arena" xreflabel="slab_alloc_arena">slab_alloc_arena</entry> + <entry>slab_alloc_arena</entry> <entry>float</entry> <entry>1.0</entry> <entry>no</entry> <entry>no</entry> - <entry>How much memory Tarantool allocates to actually + <entry> + <anchor xml:id="slab_alloc_arena" xreflabel="slab_alloc_arena"/> + How much memory Tarantool + allocates to actually store tuples, <emphasis role="strong">in gigabytes</emphasis>. When the limit is reached, INSERT or UPDATE requests begin failing with error @@ -421,7 +424,7 @@ tarantool: box:primary@sessions pri:33013 sec:33014 adm:33015</programlisting> computing the sizes of memory chunks that tuples are stored in. A lower value may result in less wasted memory depending on the total amount of memory available - and the distribution of item sizes.</entry> + and the distribution of item sizes.</entry> </row> <row> @@ -433,7 +436,7 @@ tarantool: box:primary@sessions pri:33013 sec:33014 adm:33015</programlisting> <entry>This is the main Tarantool parameter, describing the data structure that users get access to via client/server protocol. It holds an array of - entries, and each entry represents a tuple set + entries, and each entry represents a tuple set served by the server. Every entry is a composite object, best seen as a C programming language "struct" <footnote><xi:include href="namespace.xml"/></footnote>. @@ -445,7 +448,7 @@ tarantool: box:primary@sessions pri:33013 sec:33014 adm:33015</programlisting> </table> <table frame='all'> - <title>Binary logging, snapshots and replication</title> + <title>Binary logging and snapshots</title> <tgroup cols='6' colsep='1' rowsep='1'> <thead> @@ -481,57 +484,151 @@ tarantool: box:primary@sessions pri:33013 sec:33014 adm:33015</programlisting> log (at server start), abort.</entry> </row> + <row> + <entry>rows_per_wal</entry> + <entry>integer</entry> + <entry>500000</entry> + <entry>no</entry> + <entry>no</entry> + <entry>How many log records to store in a single write + ahead log file. When this limit is reached, Tarantool + creates another WAL file named + <filename><first-lsn-in-wal>.wal</filename> + This can be useful for simple rsync-based backups. + </entry> + </row> + + <row> + <entry>snap_io_rate_limit</entry> + <entry>float</entry> + <entry>0.0</entry> + <entry>no</entry> + <entry>no</entry> + <entry>Reduce the throttling effect of <olink + targetptr="save-snapshot"/> on the INSERT/UPDATE/DELETE + performance by setting a limit on + how many megabytes per second it can write to disk. + The same can be achieved by splitting <olink + targetptr="wal_dir"/> and <olink targetptr="snap_dir"/> + locations and moving snapshots to a separate disk.</entry> + </row> + + <row> + <entry>wal_writer_inbox_size</entry> + <entry>integer</entry> + <entry>128</entry> + <entry>no</entry> + <entry>no</entry> + <entry>WAL writer is a separate process whose sole + purpose is to write the change log to disk. Every + incoming data change is sent to this process and + queued for write. This parameter sets the size + of the queue. However, it has no effect + due to <link + xlink:href="https://bugs.launchpad.net/tarantool/+bug/791498">Bug#791498</link>.</entry> + </row> + + <row> + <entry>readahead</entry> + <entry>integer</entry> + <entry>16384</entry> + <entry>no</entry> + <entry>no</entry> + <entry>WAL writer network read-ahead buffer size, in + bytes. + It's not recommended to change this value until + <link xlink:href="https://bugs.launchpad.net/tarantool/+bug/791498">Bug#791498</link> + is fixed. + </entry> + </row> + + <row> + <entry>wal_fsync_delay</entry> + <entry>integer</entry> + <entry>0</entry> + <entry>no</entry> + <entry>no</entry> + <entry>Do not flush the write ahead log to disk more often + than once in wal_fsync_delay seconds. By default the + delay is zero, + that is, the write ahead log is flushed after every write. + Setting the delay may be necessary to increase write + throughput, but may lead to several last updates being + lost in case of a power failure. Such failure, however, + does not read to data corruption: all WAL records have a + checksum, and only complete records are processed during + recovery.</entry> + </row> + </tbody> </tgroup> </table> -<!-- -Storage parameters. -****************** - -Replication settings -******************** -# Write no more rows in WAL -rows_per_wal=500000, ro - + <table frame='all'> + <title>Replication</title> + <tgroup cols='6' colsep='1' rowsep='1'> -# delay between loop iterations -io_collect_interval=0.0, ro -# do not write snapshot faster then snap_io_rate_limit MBytes/sec -snap_io_rate_limit=0.0, ro + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>Default</entry> + <entry>Required?</entry> + <entry>Dynamic?</entry> + <entry>Description</entry> + </row> + </thead> -# fsync WAL delay, only issue fsync if last fsync was wal_fsync_delay seconds ago -# WARNING: actually, several last requsts may stall for much longer -wal_fsync_delay=0, ro + <tbody> + <row> + <entry>replication_port</entry> + <entry>integer</entry> + <entry>0</entry> + <entry>no</entry> + <entry>no</entry> + <entry>Replication port. If non-zero, Tarantool listens + on the given port for incoming connections from + replicas. See also <olink + targetptr="replication_source_port"/>, which complements + this setting on the replica side.</entry> + </row> -# size of WAL writer requests buffer -wal_writer_inbox_size=128, ro + <row> + <entry xml:id="replication_source_port" + xreflabel="replication_source_port">replication_source_port</entry> + <entry>integer</entry> + <entry>0</entry> + <entry>no</entry> + <entry><emphasis role="strong">yes</emphasis></entry> + <entry>Remote port of the master. If non-zero, + replication is on, and Tarantool does not accept updates + on <olink targetptr="primary_port"/>. This parameter is + dynamic, that is, to enter master mode, simply set the + port value to 0 and issue <olink + targetptr="reload-configuration"/>.</entry> + </row> -# network io readahead -readahead=16320 -# size of listen backlog -backlog=1024, ro + <row> + <entry>replication_source_ipaddr</entry> + <entry>string</entry> + <entry>0</entry> + <entry>no</entry> + <entry><emphasis role="strong">yes</emphasis></entry> + <entry>IP address of replication master.</entry> + </row> ---> -<!-- + </tbody> + </tgroup> </table> - <table> - <title>Replication</title> ---> <!-- -# Remote hot standby (if enabled server will run in hot standby mode -# continuously fetching WAL records from wal_feeder_ipaddr:wal_feeder_port -remote_hot_standby=0, ro -wal_feeder_ipaddr=NULL, ro -wal_feeder_port=0, ro ---> -<!-- - </table> +# delay between loop iterations +io_collect_interval=0.0, ro + +# size of listen backlog +backlog=1024, ro - <table> - <title>Memcached support</title> --> <table frame='all'> diff --git a/doc/user/language-reference.xml b/doc/user/language-reference.xml index e32d889c844c153e017474767cc6cd19a35afdc7..2115197c7dd927d0983d9dc8c48187f72dc14455 100644 --- a/doc/user/language-reference.xml +++ b/doc/user/language-reference.xml @@ -38,9 +38,9 @@ configuration option. </para></listitem> </itemizedlist> - + The data protocol is binary; a complete description is - provided in doc/box-protocol.txt. + provided in doc/box-protocol.txt. </para> <para> @@ -58,7 +58,7 @@ <title>Data console</title> - <para>The default data port is 33014. It can be set in the + <para>The default data port is 33014. It can be set in the configuration file. Data console supports asynchronous I/O. Four commands are supported. For a complete protocol manual, see developers guide. @@ -83,10 +83,29 @@ configuration</emphasis> Re-read the configuration file. If the file contains changes to dynamic parameters, update the runtime settings. If configuration syntax is incorrect, or a read-only parameter is changed, produce an error and do nothing.</para> - <para><emphasis xml:id="show-configuration" xreflabel="SHOW CONFIGURATION" role="tntadmin">show - configuration</emphasis> Show the current settings. Displays all + <para><emphasis xml:id="show-configuration" xreflabel="SHOW CONFIGURATION" role="tntadmin">show configuration</emphasis> Show the current settings. Displays all settings, including those that have default values and thus are not necessarily present in the configuration file.</para> + + <para><emphasis xml:id="save-snapshot" xreflabel="SAVE SNAPSHOT" + role="tntadmin">save snaspshot</emphasis> + Take a snapshot of all data and store it in + <filename><olink targetptr="snap_dir"/>/<latest-lsn>.snap</filename>. + To take a snapshot, Tarantool forks and quickly munmap(2)s all + memory except one that stores tuples. Since all modern operating + systems support virtual memory copy-on-write, this effectively + creates a consistent snapshot of all tuples in the child + process, which is then written to disk tuple by tuple. Since a + snapshot is written + sequentially, you can expect a very high write performance + (averaging to 70MB/second on modern disks), which means an + average database instance gets saved in a matter of minutes. + Note, that as long as there are any changes to the parent + memory through concurrent updates, there are going to be page + splits, and therefore you need to have some extra free memory + to run this command. 15%-30% of <olink + targetptr="slab_alloc_arena"/> is, on average, sufficient. + </para> </section> </chapter> diff --git a/doc/user/target.db b/doc/user/target.db index 6e72234af57972f8c47d28558d57556dbdf2bba0..ff99ff1b803f520c7e643fc84b1546a807392282 100644 --- a/doc/user/target.db +++ b/doc/user/target.db @@ -1 +1 @@ -<div element="book" href="#tarantool-user-guide" number="" targetptr="tarantool-user-guide"><ttl>Tarantool/Box User Guide, version 1.4.1-30-gc8e17c6</ttl><xreftext>Tarantool/Box User Guide, version 1.4.1-30-gc8e17c6</xreftext><div element="chapter" href="#id362532" number="1"><ttl>Preface</ttl><xreftext>Chapter 1, <i>Preface</i></xreftext><div element="section" href="#preface" number="" targetptr="preface"><ttl>Tarantool/Box: an overview</ttl><xreftext>the section called “Tarantool/Box: an overviewâ€</xreftext></div><div element="section" href="#id362575" number=""><ttl>Conventions</ttl><xreftext>the section called “Conventionsâ€</xreftext></div><div element="section" href="#id362649" number=""><ttl>Reporting bugs</ttl><xreftext>the section called “Reporting bugsâ€</xreftext></div></div><div element="chapter" href="#id363788" number="2"><ttl>Getting started</ttl><xreftext>Chapter 2, <i>Getting started</i></xreftext></div><div element="chapter" href="#id364795" number="3"><ttl>Dynamic data model</ttl><xreftext>Chapter 3, <i>Dynamic data model</i></xreftext></div><div element="chapter" href="#language-reference" number="4" targetptr="language-reference"><ttl>Language reference</ttl><xreftext>Chapter 4, <i>Language reference</i></xreftext><div element="section" href="#id362959" number=""><ttl>Administrative console</ttl><xreftext>the section called “Administrative consoleâ€</xreftext><obj element="emphasis" href="#reload-configuration" number="" targetptr="reload-configuration"><ttl>???TITLE???</ttl><xreftext>RELOAD CONFIGURATION</xreftext></obj><obj element="emphasis" href="#show-configuration" number="" targetptr="show-configuration"><ttl>???TITLE???</ttl><xreftext>SHOW CONFIGURATION</xreftext></obj></div></div><div element="chapter" href="#configuration-reference" number="5" targetptr="configuration-reference"><ttl>Configuration reference</ttl><xreftext>Chapter 5, <i>Configuration reference</i></xreftext><div element="section" href="#id363074" number=""><ttl>Command line options</ttl><xreftext>the section called “Command line optionsâ€</xreftext><obj element="listitem" href="#help-option" number="" targetptr="help-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#version-option" number="" targetptr="version-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#config-option" number="" targetptr="config-option"><ttl>???TITLE???</ttl><xreftext/></obj></div><div element="section" href="#id364408" number=""><ttl>The option file</ttl><xreftext>the section called “The option fileâ€</xreftext><obj element="table" href="#id366923" number="5.1"><ttl>Basic parameters</ttl><xreftext>Table 5.1, “Basic parametersâ€</xreftext></obj><obj element="table" href="#id367265" number="5.2"><ttl>Configuring the storage</ttl><xreftext>Table 5.2, “Configuring the storageâ€</xreftext></obj><obj element="entry" href="#slab_alloc_arena" number="" targetptr="slab_alloc_arena"><ttl>???TITLE???</ttl><xreftext>slab_alloc_arena</xreftext></obj><obj element="para" href="#namespace" number="" targetptr="namespace"><ttl>???TITLE???</ttl><xreftext>the section called “The option fileâ€</xreftext></obj><obj element="table" href="#id367533" number="5.3"><ttl>Binary logging, snapshots and replication</ttl><xreftext>Table 5.3, “Binary logging, snapshots and replicationâ€</xreftext></obj><obj element="table" href="#id367659" number="5.4"><ttl>Logging</ttl><xreftext>Table 5.4, “Loggingâ€</xreftext></obj><obj element="table" href="#id367845" number="5.5"><ttl>Memcached protocol support</ttl><xreftext>Table 5.5, “Memcached protocol supportâ€</xreftext></obj></div></div><div element="appendix" href="#errcode" number="A" targetptr="errcode"><ttl>List of error codes</ttl><xreftext>Appendix A, <i>List of error codes</i></xreftext><obj element="term" href="#ERR_CODE_NONMASTER" number="" targetptr="ERR_CODE_NONMASTER"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NONMASTER</xreftext></obj><obj element="term" href="#ERR_CODE_ILLEGAL_PARAMS" number="" targetptr="ERR_CODE_ILLEGAL_PARAMS"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_ILLEGAL_PARAMS</xreftext></obj><obj element="term" href="#ERR_CODE_NODE_IS_RO" number="" targetptr="ERR_CODE_NODE_IS_RO"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NODE_IS_RO</xreftext></obj><obj element="term" href="#ERR_CODE_MEMORY_ISSUE" number="" targetptr="ERR_CODE_MEMORY_ISSUE"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_MEMORY_ISSUE</xreftext></obj><obj element="term" href="#ERR_CODE_WAL_IO" number="" targetptr="ERR_CODE_WAL_IO"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_WAL_IO</xreftext></obj><obj element="term" href="#ERR_CODE_INDEX_VIOLATION" number="" targetptr="ERR_CODE_INDEX_VIOLATION"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_INDEX_VIOLATION</xreftext></obj><obj element="term" href="#ERR_CODE_NO_SUCH_NAMESPACE" number="" targetptr="ERR_CODE_NO_SUCH_NAMESPACE"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NO_SUCH_NAMESPACE</xreftext></obj><obj element="term" href="#ERR_CODE_NO_SUCH_INDEX" number="" targetptr="ERR_CODE_NO_SUCH_INDEX"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NO_SUCH_INDEX</xreftext></obj></div></div> +<div element="book" href="#tarantool-user-guide" number="" targetptr="tarantool-user-guide"><ttl>Tarantool/Box User Guide, version 1.4.1-31-g8a3bd2c</ttl><xreftext>Tarantool/Box User Guide, version 1.4.1-31-g8a3bd2c</xreftext><div element="chapter" href="#id502411" number="1"><ttl>Preface</ttl><xreftext>Chapter 1, <i>Preface</i></xreftext><div element="section" href="#preface" number="" targetptr="preface"><ttl>Tarantool/Box: an overview</ttl><xreftext>the section called “Tarantool/Box: an overviewâ€</xreftext></div><div element="section" href="#id502454" number=""><ttl>Conventions</ttl><xreftext>the section called “Conventionsâ€</xreftext></div><div element="section" href="#id502528" number=""><ttl>Reporting bugs</ttl><xreftext>the section called “Reporting bugsâ€</xreftext></div></div><div element="chapter" href="#id503666" number="2"><ttl>Getting started</ttl><xreftext>Chapter 2, <i>Getting started</i></xreftext></div><div element="chapter" href="#id504673" number="3"><ttl>Dynamic data model</ttl><xreftext>Chapter 3, <i>Dynamic data model</i></xreftext></div><div element="chapter" href="#language-reference" number="4" targetptr="language-reference"><ttl>Language reference</ttl><xreftext>Chapter 4, <i>Language reference</i></xreftext><div element="section" href="#id502876" number=""><ttl>Administrative console</ttl><xreftext>the section called “Administrative consoleâ€</xreftext><obj element="emphasis" href="#reload-configuration" number="" targetptr="reload-configuration"><ttl>???TITLE???</ttl><xreftext>RELOAD CONFIGURATION</xreftext></obj><obj element="emphasis" href="#show-configuration" number="" targetptr="show-configuration"><ttl>???TITLE???</ttl><xreftext>SHOW CONFIGURATION</xreftext></obj><obj element="emphasis" href="#save-snapshot" number="" targetptr="save-snapshot"><ttl>???TITLE???</ttl><xreftext>SAVE SNAPSHOT</xreftext></obj></div></div><div element="chapter" href="#configuration-reference" number="5" targetptr="configuration-reference"><ttl>Configuration reference</ttl><xreftext>Chapter 5, <i>Configuration reference</i></xreftext><div element="section" href="#id504902" number=""><ttl>Command line options</ttl><xreftext>the section called “Command line optionsâ€</xreftext><obj element="listitem" href="#help-option" number="" targetptr="help-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#version-option" number="" targetptr="version-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#config-option" number="" targetptr="config-option"><ttl>???TITLE???</ttl><xreftext/></obj></div><div element="section" href="#id504287" number=""><ttl>The option file</ttl><xreftext>the section called “The option fileâ€</xreftext><obj element="table" href="#id507149" number="5.1"><ttl>Basic parameters</ttl><xreftext>Table 5.1, “Basic parametersâ€</xreftext></obj><obj element="entry" href="#wal_dir" number="" targetptr="wal_dir"><ttl>???TITLE???</ttl><xreftext>wal_dir</xreftext></obj><obj element="entry" href="#snap_dir" number="" targetptr="snap_dir"><ttl>???TITLE???</ttl><xreftext>snap_dir</xreftext></obj><obj element="entry" href="#primary_port" number="" targetptr="primary_port"><ttl>???TITLE???</ttl><xreftext>primary_port</xreftext></obj><obj element="table" href="#id507511" number="5.2"><ttl>Configuring the storage</ttl><xreftext>Table 5.2, “Configuring the storageâ€</xreftext></obj><obj element="anchor" href="#slab_alloc_arena" number="" targetptr="slab_alloc_arena"><ttl>???TITLE???</ttl><xreftext>slab_alloc_arena</xreftext></obj><obj element="para" href="#namespace" number="" targetptr="namespace"><ttl>???TITLE???</ttl><xreftext>the section called “The option fileâ€</xreftext></obj><obj element="table" href="#id507782" number="5.3"><ttl>Binary logging and snapshots</ttl><xreftext>Table 5.3, “Binary logging and snapshotsâ€</xreftext></obj><obj element="table" href="#id508062" number="5.4"><ttl>Replication</ttl><xreftext>Table 5.4, “Replicationâ€</xreftext></obj><obj element="entry" href="#replication_source_port" number="" targetptr="replication_source_port"><ttl>???TITLE???</ttl><xreftext>replication_source_port</xreftext></obj><obj element="table" href="#id508228" number="5.5"><ttl>Logging</ttl><xreftext>Table 5.5, “Loggingâ€</xreftext></obj><obj element="table" href="#id508414" number="5.6"><ttl>Memcached protocol support</ttl><xreftext>Table 5.6, “Memcached protocol supportâ€</xreftext></obj></div></div><div element="appendix" href="#errcode" number="A" targetptr="errcode"><ttl>List of error codes</ttl><xreftext>Appendix A, <i>List of error codes</i></xreftext><obj element="term" href="#ERR_CODE_NONMASTER" number="" targetptr="ERR_CODE_NONMASTER"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NONMASTER</xreftext></obj><obj element="term" href="#ERR_CODE_ILLEGAL_PARAMS" number="" targetptr="ERR_CODE_ILLEGAL_PARAMS"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_ILLEGAL_PARAMS</xreftext></obj><obj element="term" href="#ERR_CODE_NODE_IS_RO" number="" targetptr="ERR_CODE_NODE_IS_RO"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NODE_IS_RO</xreftext></obj><obj element="term" href="#ERR_CODE_MEMORY_ISSUE" number="" targetptr="ERR_CODE_MEMORY_ISSUE"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_MEMORY_ISSUE</xreftext></obj><obj element="term" href="#ERR_CODE_WAL_IO" number="" targetptr="ERR_CODE_WAL_IO"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_WAL_IO</xreftext></obj><obj element="term" href="#ERR_CODE_INDEX_VIOLATION" number="" targetptr="ERR_CODE_INDEX_VIOLATION"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_INDEX_VIOLATION</xreftext></obj><obj element="term" href="#ERR_CODE_NO_SUCH_NAMESPACE" number="" targetptr="ERR_CODE_NO_SUCH_NAMESPACE"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NO_SUCH_NAMESPACE</xreftext></obj><obj element="term" href="#ERR_CODE_NO_SUCH_INDEX" number="" targetptr="ERR_CODE_NO_SUCH_INDEX"><ttl>???TITLE???</ttl><xreftext>ERR_CODE_NO_SUCH_INDEX</xreftext></obj></div></div>