From b336994d07e4087222e6f84078d008bc9dbc25d0 Mon Sep 17 00:00:00 2001
From: bigbes <bigbes@gmail.com>
Date: Mon, 6 Apr 2015 14:46:04 +0300
Subject: [PATCH] Update searchbox and remove forgotten userdoc files
---
doc/sphinx/_templates/searchbox.html | 2 +-
doc/user/configuration-reference.xml | 766 ---------------------------
doc/user/connectors.xml | 324 -----------
3 files changed, 1 insertion(+), 1091 deletions(-)
delete mode 100644 doc/user/configuration-reference.xml
delete mode 100644 doc/user/connectors.xml
diff --git a/doc/sphinx/_templates/searchbox.html b/doc/sphinx/_templates/searchbox.html
index 508b4b3025..d2d38c46c8 100644
--- a/doc/sphinx/_templates/searchbox.html
+++ b/doc/sphinx/_templates/searchbox.html
@@ -1,6 +1,6 @@
{%- if builder != "singlehtml" %}
<form id="searchbox" role="search" class="search b-search" action="{{ pathto('search') }}" method="get">
- <input class="b-search-text" name="q" type="text"/ placeholder="Search">
+ <input class="b-search-text" name="q" type="text"/ placeholder="Search the manual">
<input class="b-search-but" type="submit" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml
deleted file mode 100644
index 11ae16e312..0000000000
--- a/doc/user/configuration-reference.xml
+++ /dev/null
@@ -1,766 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="configuration-reference">
-
-<title>Configuration reference</title>
-<blockquote><para>
- This chapter provides a reference of options which
- can be set on the command line or in an initialization file.
-</para></blockquote>
-
-<para>
-Tarantool is started by entering the command:
-
-<programlisting><prompt>$ </prompt><userinput>tarantool</userinput></programlisting>
-or
-<programlisting><prompt>$ </prompt><userinput>tarantool <replaceable>options</replaceable></userinput></programlisting>
-or
-<programlisting><prompt>$ </prompt><userinput>tarantool <replaceable>Lua-initialization-file</replaceable> [<replaceable>arguments</replaceable>]</userinput></programlisting>
-
-</para>
-
-<section xml:id="command-line-options">
-<title>Command options</title>
- <para>
-
- </para>
- <itemizedlist>
- <listitem xml:id="help-option">
- <para><option>--help</option>, <option>-h</option></para>
- <para>Print an annotated list of all available options and exit.</para>
- </listitem>
-
- <listitem xml:id="version-option">
- <para><option>--version</option>, <option>-V</option></para>
- <para>Print product name and version, for example:
- <programlisting><prompt>$ </prompt> <userinput>./tarantool --version</userinput>
-Tarantool 1.6.3-439-g7e1011b
-Target: Linux-x86_64-Debug
-...
- </programlisting>
- In this example:
- <simplelist>
- <member>
- <quote>Tarantool</quote> is the name
- of the reusable asynchronous networking programming framework.
- </member>
- <member>
- The 3-number version follows the standard
- <literal><major>-<minor>-<patch></literal>
- scheme, in which <literal><major></literal> number
- is changed only rarely, <literal><minor></literal>
- is incremented for each new milestone and
- indicates possible incompatible changes,
- and <literal><patch></literal> stands for the number of
- bug fix releases made after the start of the
- milestone. For non-released versions only, there may be a
- commit number and commit SHA1
- to indicate how much this particular build has diverged
- from the last release.
- </member>
- <member>
- <quote>Target</quote> is the platform tarantool was built on.
- Some platform-specific details may follow this line.
- </member>
- </simplelist>
- </para>
- <note><para>
- Tarantool uses <link
- xlink:href="http://www.kernel.org/pub/software/scm/git/docs/git-describe.html">git describe</link> to produce its version id, and
- this id can be used at any time to check out the
- corresponding source from our <link
- xlink:href="http://github.com/tarantool/tarantool.git">git repository</link>.
- </para></note>
- </listitem>
-
- </itemizedlist>
-
-</section>
-
-
-<section xml:id="URI" xreflabel="URI">
- <title>URI</title>
- <para>
-Some configuration parameters and some functions
-depend on a URI, or "Universal Resource Identifier".
-The URI string format is similar to the
-<link
-xlink:href="http://en.wikipedia.org/wiki/URI_scheme#Generic_syntax">generic syntax for a URI schema</link>.
-So it may contain (in order) a user name for login, a password,
-a host name or host IP address, and a port number.
-Only the port number is always mandatory. The password
-is mandatory if the user name is specified,
-unless the user name is 'guest'.
-So, formally, the URI syntax is
-<code>[host:]port</code>
-or <code>[username:password@]host:port</code>.
-If host is omitted, then 'localhost' is assumed.
-If username:password is omitted, then 'guest' is assumed.
-Some examples:
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry>URI fragment</entry><entry>Example</entry></row>
- </thead>
- <tbody>
- <row><entry>port</entry><entry> 3301</entry></row>
- <row><entry>host:port</entry><entry> 127.0.0.1:3301</entry></row>
- <row><entry>username:password@host:port</entry><entry> guest:sesame@mail.ru:3301</entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-In certain circumstances a Unix socket may be used where a URI is required.
-</para>
-</section>
-
-
-<section xml:id="initialization-file" xreflabel="initialization file">
-<title>Initialization file</title>
-<para>
-If the command to start Tarantool includes <option><replaceable>lua-initialization-file</replaceable></option>,
-then Tarantool begins by invoking the Lua program in the file,
-which by convention may have the name <filename>"script.lua"</filename>.
-
-The Lua program may get further arguments from the command line
-or may use operating-system functions, such as getenv().
-The Lua program almost always begins by invoking <code>box.cfg()</code>,
-if the database server will be used or if ports need to be opened.
-For example, suppose <filename>script.lua</filename> contains the lines<programlisting>#!/usr/bin/env tarantool
-box.cfg{
- listen = os.getenv("LISTEN_URI"),
- slab_alloc_arena = 0.1,
- pid_file = "tarantool.pid",
- rows_per_wal = 50
-}
-print('Starting ',arg[1])</programlisting>
-and suppose the environment variable LISTEN_URI contains 3301,
-and suppose the command line is <code>~/tarantool/src/tarantool script.lua ARG</code>.
-Then the screen might look like this:<programlisting>
-<prompt>$</prompt> <userinput>export LISTEN_URI=3301</userinput>
-<prompt>$</prompt> <userinput>~/tarantool/src/tarantool script.lua ARG</userinput>
-... main/101/script.lua C> version 1.6.3-439-g7e1011b
-... main/101/script.lua C> log level 5
-... main/101/script.lua I> mapping 107374184 bytes for a shared arena...
-... main/101/script.lua I> recovery start
-... main/101/script.lua I> recovering from `./00000000000000000000.snap'
-... main/101/script.lua I> primary: bound to 0.0.0.0:3301
-... main/102/leave_local_hot_standby I> ready to accept requests
-Starting ARG
-... main C> entering the event loop</programlisting>
-</para>
-</section>
-
-<section xml:id="configuration-parameters" xreflabel="configuration parameters">
-<title>Configuration parameters</title>
-<para>
- Configuration parameters have the form
- <code>box.cfg{<replaceable> key = value [, key = value ...]</replaceable>}</code>.
- Since box.cfg may contain many configuration parameters
- and since some of the parameters (such as directory addresses)
- are semi-permanent, it's best to keep box.cfg in a Lua file.
- Typically this Lua file is the initialization file
- which is specified on the tarantool command line.
- </para>
- <para>
- Most configuration parameters are for allocating resources,
- opening ports, and specifying database behavior.
- All parameters are optional.
- A few parameters are dynamic, that is, they can be changed
- at runtime by calling box.cfg{} a second time.
- </para>
- <para>
- To see all the non-null parameters, say <code>box.cfg</code> (no parentheses).
- To see a particular parameter, for example the listen address, say <code>box.cfg.listen</code>.
- </para>
- <para>
- The following tables describe all parameters for basic operation,
- for storage, for binary logging and snapshots, for replication,
- for networking, and for logging.
- </para>
-
- <table frame='all' pgwide='1'>
- <title>Basic parameters</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>username</entry>
- <entry>string</entry>
- <entry>null</entry>
- <entry>no</entry>
- <entry>UNIX user name to switch to after start.</entry>
- </row>
-
- <row>
- <entry xml:id="work_dir" xreflabel="work_dir">work_dir</entry>
- <entry>string</entry>
- <entry>null</entry>
- <entry>no</entry>
- <entry>A directory where database working files will be stored.
- The server switches to work_dir with chdir(2) after
- start. Can be relative to the current directory.
- If not specified, defaults to the current directory.</entry>
- </row>
-
- <row>
- <entry xml:id="wal_dir" xreflabel="wal_dir">wal_dir</entry>
- <entry>string</entry>
- <entry>"."</entry>
- <entry>no</entry>
- <entry>A directory where write-ahead log (.xlog) files are stored.
- Can be relative to work_dir. Most commonly used so
- that snapshot files and write-ahead log files
- can be stored on separate disks.
- If not specified, defaults to work_dir.</entry>
- </row>
-
- <row>
- <entry xml:id="snap_dir" xreflabel="snap_dir">snap_dir</entry>
- <entry>string</entry>
- <entry>"."</entry>
- <entry>no</entry>
- <entry>A directory where snapshot (.snap) files will be stored. Can be
- 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>
- <entry>false</entry>
- <entry>no</entry>
- <entry>Deprecated. Do not use.</entry>
- </row>
- <row>
- <entry xml:id="primary_port" xreflabel="primary_port">listen</entry>
- <entry>integer or string</entry>
- <entry>null</entry>
- <entry>yes</entry>
- <entry>The read/write data port number or <link linkend="URI">URI</link> (Universal Resource Identifier) string.
- Has no default value, so <emphasis
- role="strong">must be specified</emphasis>
- if connections will occur from remote clients
- that do not use "admin address" (the administrative host and port).
- 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.
- The listen parameter may also be set for <olink targetptr="local_hot_standby">local hot standby</olink>.</entry>
- </row>
-
- <row>
- <entry>pid_file</entry>
- <entry>string</entry>
- <entry>null</entry>
- <entry>no</entry>
- <entry>Store the process id in this file. Can be
- relative to work_dir. A typical value is "tarantool.pid".</entry>
- </row>
-
- <row>
- <entry xml:id="custom_proc_title"
- xreflabel="custom_proc_title">
- custom_proc_title
- </entry>
- <entry>string</entry>
- <entry>null</entry>
- <entry>no</entry>
- <entry>
- <para>Inject the given string into <olink
- targetptr="proctitle">server process title</olink>
- (what's shown in the COMMAND column for <command>ps</command>
- and <command>top</command> commands). For example,
- ordinarily <command>ps</command> shows the Tarantool server process thus:
- </para><programlisting><prompt>$</prompt> <userinput>ps -ef | grep tarantool</userinput>
-1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running
-1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner
-tarantool: primary pri: 3301 adm: 3313</programlisting>
- <para>But if the configuration parameters include custom_proc_title='sessions' then
- the output looks like:</para>
-<programlisting><prompt>$</prompt> <userinput>ps -ef | grep tarantool</userinput>
-1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running@sessions
-1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner@sessions
-tarantool: primary pri: 3301 adm: 3313</programlisting>
- </entry>
- </row>
-
- <row>
- <entry>background</entry>
- <entry>boolean</entry>
- <entry>false</entry>
- <entry>no</entry>
- <entry>Run the server as a background task.
- The logger and pid_file parameters must be non-null for this to work.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <table frame='all' pgwide='1'>
- <title>Configuring the storage</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>slab_alloc_arena</entry>
- <entry>float</entry>
- <entry>1.0</entry>
- <entry>no</entry>
- <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
- <olink targetptr="ER_MEMORY_ISSUE"/>.
- While the server does not go
- beyond the defined limit to allocate tuples, there is
- additional memory used to store indexes and connection
- information. Depending on actual configuration and
- workload, Tarantool can consume up to 20% more than the
- limit set here.</entry>
- </row>
-
- <row>
- <entry>slab_alloc_minimal</entry>
- <entry>integer</entry>
- <entry>64</entry>
- <entry>no</entry>
- <entry>Size of the smallest allocation unit. It can be
- tuned down if most of the tuples are very small.</entry>
- </row>
-
- <row>
- <entry>slab_alloc_factor</entry>
- <entry>float</entry>
- <entry>2.0</entry>
- <entry>no</entry>
- <entry>Use slab_alloc_factor as the multiplier for
- 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>
- </row>
-
- <row>
- <entry>sophia</entry>
- <entry>table</entry>
- <entry>(see the note)</entry>
- <entry>no</entry>
- <entry>The default sophia configuration can be changed with
- sophia={page_size=<replaceable>number</replaceable>, threads=<replaceable>number</replaceable>,
- node_size=<replaceable>number</replaceable>, memory_limit=<replaceable>number</replaceable> }.
- This method may change in the future.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
-
- <table xml:id="snapshot-daemon" frame='all' pgwide='1'>
- <title>Snapshot daemon</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>snapshot_period</entry>
- <entry>float</entry>
- <entry>0</entry>
- <entry>yes</entry>
- <entry>
- The interval between actions by the snapshot daemon, in seconds.
- The snapshot daemon is a fiber which is constantly running.
- If snapshot_period is set to a value greater than zero,
- then the snapshot daemon
- will call <olink targetptr="box.snapshot"/> every snapshot_period seconds, creating
- a new snapshot file each time.
- For example, <code>box.cfg{snapshot_period=3600}</code>
- will cause the snapshot daemon to create a new database
- snapshot once per hour.
- </entry>
- </row>
-
- <row>
- <entry>snapshot_count</entry>
- <entry>integer</entry>
- <entry>6</entry>
- <entry>yes</entry>
- <entry>
- <para>
- The maximum number of snapshots that the snapshot daemon maintains.
- For example, <code>box.cfg{snapshot_period=3600, snapshot_count=10}</code>
- will cause the snapshot daemon
- to create a new snapshot each hour until it has created
- ten snapshots. After that, it will remove the oldest
- snapshot (and any associated write-ahead-log files) after creating
- a new one. If snapshot_count equals zero, then the snapshot
- daemon does not remove old snapshots.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame='all' pgwide='1'>
- <title>Binary logging and snapshots</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>panic_on_snap_error</entry>
- <entry>boolean</entry>
- <entry>true</entry>
- <entry>no</entry>
- <entry>If there is an error while reading the snapshot file (at
- server start), abort.</entry>
- </row>
-
- <row>
- <entry>panic_on_wal_error</entry>
- <entry>boolean</entry>
- <entry>false</entry>
- <entry>no</entry>
- <entry>If there is an error while reading a write-ahead
- log file (at server start), abort.</entry>
- </row>
-
- <row>
- <entry xml:id="rows_per_wal" xreflabel="rows_per_wal">rows_per_wal</entry>
- <entry>integer</entry>
- <entry>500000</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>.xlog</filename>
- This can be useful for simple rsync-based backups.
- </entry>
- </row>
-
- <row>
- <entry>snap_io_rate_limit</entry>
- <entry>float</entry>
- <entry>null</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry>Reduce the throttling effect of <olink
- targetptr="box.snapshot"/> on 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 xml:id="wal_mode" xreflabel="wal_mode">wal_mode</entry>
- <entry>string</entry>
- <entry>"write"</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry>Specify fiber-WAL-disk synchronization mode as:
- <emphasis>none:</emphasis> write-ahead log is not maintained; <emphasis>write:</emphasis> fibers wait for their data to
- be written to the write-ahead log (no fsync(2)); <emphasis>fsync</emphasis>:
- fibers wait for their data, fsync(2) follows each write(2);
- </entry>
- </row>
-
- <row>
- <entry xml:id="wal_dir_rescan_delay" xreflabel="wal_dir_rescan_delay">wal_dir_rescan_delay</entry>
- <entry>float</entry>
- <entry>0.1</entry>
- <entry>no</entry>
- <entry>Number of seconds between periodic scans of the
- write-ahead-log file directory, when checking for
- changes to write-ahead-log files for the sake of
- replication or local hot standby.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <table frame='all' pgwide='1'>
- <title>Replication</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry xml:id="replication_source"
- xreflabel="replication_source">replication_source</entry>
- <entry>string</entry>
- <entry>null</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry>If replication_source is not an empty string, the
- server is considered to be a Tarantool replica.
- The replica server will try to connect to the master
- which replication_source specifies with a <link linkend="URI">URI</link> (Universal Resource Identifier),
- for example 'konstantin:secret_password@tarantool.org:3301'.
- The default user name is 'guest'.
- A replica server does not accept data-change requests
- on the <olink targetptr="primary_port">listen</olink> port.
- The replication_source parameter is
- dynamic, that is, to enter master mode, simply set
- replication_source to an empty string and issue
- "box.cfg{replication_source=new-value}".</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <table frame='all' pgwide='1'>
- <title>Networking</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>io_collect_interval</entry>
- <entry>float</entry>
- <entry>null</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry>The server will sleep for io_collect_interval seconds
- between iterations of the event loop. Can be
- used to reduce CPU load in deployments in which the
- number of client connections is large, but requests are
- not so frequent (for example, each connection issues
- just a handful of requests per second). </entry>
- </row>
-
- <row>
- <entry>readahead</entry>
- <entry>integer</entry>
- <entry>16320</entry>
- <entry>yes</entry>
- <entry>The size of the read-ahead buffer associated with a
- client connection. The larger the buffer, the more
- memory an active connection consumes and the more requests
- can be read from the operating system buffer in a single
- system call. The rule of thumb is to make sure the buffer
- can contain at least a few dozen requests. Therefore, if
- a typical tuple in a request is large, e.g. a few
- kilobytes or even megabytes, the read-ahead buffer size should
- be increased. If batched request processing is not
- used, it's prudent to leave this setting at its
- default.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <table frame='all' pgwide='1'>
- <title>Logging</title>
- <tgroup cols='5' colsep='1' rowsep='1'>
- <colspec colnum="1" colname="col1" colwidth="2*"/>
- <colspec colnum="5" colname="col4" colwidth="6*"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- <entry>Dynamic?</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry xml:id="log_level" xreflabel="log_level">log_level</entry>
- <entry>integer</entry>
- <entry>5</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry>How verbose the logging is. There are six log
- verbosity classes: 1 -- SYSERROR, 2 -- ERROR, 3 -- CRITICAL, 4 --
- WARNING, 5 -- INFO, 6 -- DEBUG. By setting log_level,
- one can enable logging of all classes below or equal
- to the given level. Tarantool prints its logs to the
- standard error stream by default, but this can be
- changed with the "logger" configuration parameter.
- </entry>
- </row>
-
- <row>
- <entry xml:id="logger" xreflabel="logger">logger</entry>
- <entry>string</entry>
- <entry>null</entry>
- <entry>no</entry>
- <entry>By default, the log is sent to the standard
- error stream (<filename>stderr</filename>). If logger
- is specified, the log is sent to the file named in the string.
- Example setting: logger = 'tarantool.log'
- (this will open tarantool.log for output on the
- server's default directory).
- </entry>
- </row>
-
- <row>
- <entry>logger_nonblock</entry>
- <entry>boolean</entry>
- <entry>true</entry>
- <entry>no</entry>
- <entry>If logger_nonblock equals true, Tarantool does not
- block on the log file descriptor when it's not
- ready for write, and drops the message instead. If
- log_level is high, and a lot of messages go to the log
- file, setting logger_nonblock to true may improve logging
- performance at the cost of some log messages getting
- lost.</entry>
- </row>
-
- <row>
- <entry>too_long_threshold</entry>
- <entry>float</entry>
- <entry>0.5</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry>If processing a request takes longer than the
- given value (in seconds), warn about it in the log.
- Has effect only if log_level is less than or equal to 4
- (WARNING).</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
-</section>
-
-<section xml:id="local_hot_standby" xreflabel="local_hot_standby">
-<title>Local hot standby</title>
-
- <para>
- Local hot standby is a feature which provides a simple form of failover without replication.
- To initiate it, start a second instance of the Tarantool server on the same computer with
- the same <code>box.cfg</code> configuration settings -- including the same directories and
- same non-null URIs.
- A warning should appear with a message like
- "W> primary: [URI] is already in use, will retry binding after [n] seconds".
- This is fine.
- It means that the second instance is ready to take over if the first instance goes down.
- </para>
- <para>
- The expectation is that there will be two
- instances of the server using the same configuration.
- The first one to start will be the "primary" instance.
- The second one to start will be the "standby" instance.
- The standby instance will initialize and will try to connect on listen
- address and admin address, but will fail because the
- primary instance has already taken them.
- So the standby instance goes into a loop, reading the write
- ahead log which the primary instance is writing (so the
- two instances are always in synch), and trying to connect on the
- ports. If the primary instance goes down for any reason,
- the ports will become free so the standby instance will
- succeed in connecting, and will become the primary instance.
- Thus there is no noticeable downtime if the primary instance goes down.
- </para>
- <para>
- If this local_hot_standby feature is being used, then replication_source should be an
- empty string and wal_mode should not be equal to "none".
- </para>
-
-</section>
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/connectors.xml b/doc/user/connectors.xml
deleted file mode 100644
index 578ed4a6cb..0000000000
--- a/doc/user/connectors.xml
+++ /dev/null
@@ -1,324 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="connectors">
-
-<title>Connectors</title>
-<blockquote><para>
- This chapter documents APIs for various programming languages.
-</para></blockquote>
-
-<section xml:id="protocol">
- <title>Protocol</title>
- <para>Tarantool protocol was designed with a focus on asynchronous
- I/O and easy integration with proxies. Each client
- request starts with a variable-length binary header, containing
- request id, request type, server id, log sequence number, and
- so on.
- </para>
-
- <para>
- The mandatory length, present in request header simplifies
- client or proxy I/O. A response to a request is sent to the
- client as soon as it is ready. It always carries in its header
- the same type and id as in the request. The id makes it
- possible to match a request to a response, even if the latter
- arrived out of order.
- </para>
-
- <para>Unless implementing a client driver, one needn't
- concern oneself with the complications of the binary
- protocol. <olink targetptr="connectors">Language-specific
- drivers</olink> provide a friendly way to store domain
- language data structures in Tarantool.
- A complete description of the binary protocol
- is maintained in annotated Backus-Naur
- form in the source tree: please see
- <link xlink:href="http://tarantool.org/doc/box-protocol.html"><filename>doc/box-protocol.html</filename></link>.
- </para>
-</section>
-
-<section xml:id="connector-packet-example">
-<title>Packet example</title>
-<para>
-The Tarantool API exists so that a client program can send a request packet
-to the server, and receive a response. Here is an example of a what the client
- would send for <command>box.space[513]:insert{'A', 'BB'}</command>. The BNF description of the components
-is in file <link xlink:href="http://tarantool.org/doc/box-protocol.html" xlink:title="A complete BNF of Tarantool client/server protocol">doc/box-protocol.html</link>.
-
-</para>
- <informaltable frame='topbot'>
- <tgroup cols='5' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <colspec colname='c4'/>
- <colspec colname='c5'/>
- <thead>
- <row>
- <entry>Component</entry>
- <entry>Byte#0</entry>
- <entry>Byte#1</entry>
- <entry>Byte#2</entry>
- <entry>Byte#3</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>code for insert</entry>
- <entry>2</entry>
- </row>
- <row>
- <entry>rest of header</entry>
- <entry>...</entry>
- <entry>...</entry>
- <entry>...</entry>
- <entry>...</entry>
- </row>
- <row>
- <entry>2-digit number: space id</entry>
- <entry>cd</entry>
- <entry>02</entry>
- <entry>01</entry>
- </row>
- <row>
- <entry>code for tuple</entry>
- <entry>21</entry>
- </row>
- <row>
- <entry>1-digit number: field count = 2</entry>
- <entry>92</entry>
- </row>
- <row>
- <entry>1-character string: field[1]</entry>
- <entry>a1</entry>
- <entry>41</entry>
- </row>
- <row>
- <entry>2-character string: field[2]</entry>
- <entry>a2</entry>
- <entry>42</entry>
- <entry>42</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-<para>
-Now, one could send that packet to the tarantool server,
-and interpret the response (doc/box-protocol.html has a description
-of the packet format for responses as well as requests).
-But it would be easier, and less error-prone, if one could
-invoke a routine that formats the packet according to typed
-parameters. Something like <code>response=tarantool_routine("insert",513,"A","B");</code>.
-And that is why APIs exist for drivers for Perl, Python, PHP, and so on.
-</para>
- </section>
-
- <section xml:id="connector-server">
- <title>Setting up the server for connector examples</title>
- <para>
- This chapter has examples that show how to connect to the Tarantool
- server via the Perl, PHP, and Python connectors.
- The examples contain hard code that will work if and only if
- the server (tarantool) is running on localhost (127.0.0.1) and is listening on port 3301
- (<code>box.cfg.listen='3301'</code>) and space 'examples' has id = 999
- (<code>box.space.tester.id = 999</code>), and
- space 'examples' has a primary-key index for a numeric field
- (<code>box.space[999].index[0].parts[1].type = "NUM"</code>)
- and user 'guest' has privileges for reading and writing.
- </para>
- <para>
- It is easy to meet all the conditions by starting the
- server and executing this script:<programlisting>
-box.cfg{listen=3301}
-box.schema.space.create('examples',{id=999})
-box.space.examples:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
-box.schema.user.grant('guest','read,write','space','examples')
-box.schema.user.grant('guest','read','space','_space')
-</programlisting>
- </para>
- </section>
-
- <section xml:id="connector-java">
- <title>Java</title>
- <para>
- Please see <link xlink:href="http://dgreenru.github.io/tarantool-java/"><filename>http://dgreenru.github.io/tarantool-java/</filename></link>.
- </para>
- </section>
-
- <section xml:id="connector-go">
- <title>Go</title>
- <para>
- Please see <link xlink:href="https://github.com/mialinx/go-tarantool-1.6"><filename>https://github.com/mialinx/go-tarantool-1.6</filename></link>.
- </para>
- </section>
-
- <section xml:id="connector-perl">
- <title>Perl</title>
- <para>
- The most commonly used Perl driver is <link xlink:href='http://search.cpan.org/~unera/DR-Tarantool/'>DR::Tarantool</link>.
- It is not supplied as part of the Tarantool repository; it must be installed separately.
- The most common way to install it is with <link xlink:href='https://en.wikipedia.org/wiki/Cpan'>CPAN, the Comprehensive Perl Archive Network</link>.
- DR::Tarantool requires other modules which should be installed first.
- For example, on Ubuntu, the installation could look like this:<programlisting>
-sudo cpan install AnyEvent
-sudo cpan install Devel::GlobalDestruction
-sudo cpan install Coro
-sudo cpan install Test::Pod
-sudo cpan install Test::Spelling
-sudo cpan install PAR::Dist
-sudo cpan install List::MoreUtils
-sudo cpan install DR::Tarantool</programlisting>
- </para>
- <para>
- Here is a complete Perl program that inserts [99999,'BB'] into space[999] via the Perl API.
- Before trying to run, check that the server is listening and that <code>examples</code> exists,
- as described <link linkend="connector-server">earlier</link>.
- To run, paste the code into a file named example.pl and say <code>perl example.pl</code>.
- The program will connect using an application-specific definition of the space.
- The program will open a socket connection
- with the tarantool server at localhost:3301, then send an INSERT request,
- then — if all is well — end without displaying any messages.
- If tarantool is not running on localhost with listen address = 3301, the program will print
- <quote>Connection refused</quote>.
- </para>
- <para>
- <programlisting language="perl">
-#!/usr/bin/perl
-use DR::Tarantool ':constant', 'tarantool';
-use DR::Tarantool ':all';
-use DR::Tarantool::MsgPack::SyncClient;
-
-my $tnt = DR::Tarantool::MsgPack::SyncClient->connect(
- host => '127.0.0.1', # look for tarantool on localhost
- port => 3301, # assume tarantool listen address = default
- user => 'guest', # username. one could also say 'password=>...'
-
- spaces => {
- 999 => { # definition of space[999] ...
- name => 'examples', # space[999] name = 'examples'
- default_type => 'STR', # space[999] field type is 'STR' if undefined
- fields => [ { # definition of space[512].fields ...
- name => 'field1', type => 'NUM' } ], # space[999].field[1] name='field1',type='NUM'
- indexes => { # definition of space[999] indexes ...
- 0 => {
- name => 'primary', fields => [ 'field1' ] } } } } );
-
-$tnt->insert('examples' => [ 99999, 'BB' ]);</programlisting>
- </para>
- <para>
- The example program only shows one command and does not show all that's necessary for
- good practice. For that, please see
- <link xlink:href='http://search.cpan.org/~unera/DR-Tarantool/'>DR::Tarantool CPAN repository</link>.
- </para>
- </section>
-
- <section xml:id="connector-php">
- <title>PHP</title>
-
- <para>
- The PHP driver is <link xlink:href='https://github.com/tarantool/tarantool-php'>tarantool-php</link>.
- It is not supplied as part of the Tarantool repository; it must be installed separately.
- It can be installed with git.
- It requires other modules which should be installed first.
- For example, on Ubuntu, the installation could look like this:
- <programlisting>
-sudo apt-get install php5-cli
-sudo apt-get install php5-dev
-sudo apt-get install php-pear
-cd ~
-git clone https://github.com/tarantool/tarantool-php.git
-cd tarantool-php
-phpize
-./configure
-make
-#make install is optional</programlisting>
- </para>
- <para>
- At this point there is a file named <filename>~/tarantool-php/modules/tarantool.so</filename>.
- PHP will only find it if the PHP initialization file <filename>php.ini</filename> contains a line like
- <code>extension=./tarantool.so</code>.
- So copy <filename>tarantool.so</filename> to the working directory and tell PHP where
- to find the <filename>php.ini</filename> file that contains that line ...
- <programlisting>
-cd ~
-cp ./tarantool-php/modules/tarantool.so .
-export PHP_INI_SCAN_DIR=~/tarantool-php/test/shared</programlisting>
- </para>
- <para>
- Here is a complete PHP program that inserts [99999,'BB'] into a space named 'examples' via the PHP API.
- Before trying to run, check that the server is listening and that <code>examples</code> exists,
- as described <link linkend="connector-server">earlier</link>.
- To run, paste the code into a file named example.php and say <code>php example.php</code>.
- The program will open a socket connection
- with the tarantool server at localhost:3301, then send an INSERT request,
- then — if all is well — print "Insert succeeded".
- If the tuple already exists, the program will print <quote>Duplicate key exists in unique index 0</quote>.
- </para>
- <para>
- <programlisting>
-<?php
-$tarantool = new Tarantool("localhost", 3301);
-try {
- $tarantool->insert("examples", array(99999, "BB"));
- print "Insert succeeded\n";
- }
-catch (Exception $e) {
- echo "Exception: ", $e->getMessage(), "\n";
- }
-?></programlisting>
- </para>
- <para>
- After running the example, it is good practice to delete the file ./tarantool.so,
- since it is only compatible with PHP and its existence could confuse non-PHP applications.
- </para>
- <para>
- The example program only shows one command and does not show all that's necessary for
- good practice. For that, please see
- <link
- xlink:href="https://github.com/tarantool/tarantool-php/"><filename>tarantool-php</filename></link> project at GitHub.
- </para>
- </section>
-
- <section xml:id="connector-python">
- <title>Python</title>
- <para>
- Here is a complete Python program that inserts [99999,'Value','Value'] into space <code>examples</code> via the high-level Python API.
- </para>
-<programlisting language="python">
-#!/usr/bin/python
-from tarantool import Connection
-
-c = Connection("127.0.0.1", 3301)
-result = c.insert("examples",(99999,'Value', 'Value'))
-print result
-</programlisting>
- <para>
- To prepare, paste the code into a file named example.py and install tarantool-python with either
- <userinput><code>pip install tarantool\>0.4</code></userinput> to install in <filename>/usr</filename> (requires root privilege)
- or
- <userinput><code>pip install tarantool\>0.4 --user</code></userinput> to install in <filename>~</filename> i.e. user's default directory.
- Before trying to run, check that the server is listening and that <code>examples</code> exists,
- as described <link linkend="connector-server">earlier</link>.
- To run the program, say <code>python example.py</code>.
- The program will connect to the server, will send the request, and will not throw an exception if all went well.
- If the tuple already exists, the program will throw DatabaseException(“Duplicate key exists in unique indexâ€).
- </para>
- <para>
- The example program only shows one request and does not show all that's necessary for
- good practice. For that, see
- <link xlink:href="http://github.com/tarantool/tarantool-python"><filename>http://github.com/tarantool/tarantool-python</filename></link>.
- For an example of a Python API for <link xlink:href="https://github.com/tarantool/queue">Queue managers on Tarantool</link>, see
- <link xlink:href="https://github.com/tarantool/tarantool-queue-python"><filename>https://github.com/tarantool/tarantool-queue-python</filename></link>.
- </para>
- </section>
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
--
GitLab