Author: mcbrown
Date: 2007-08-17 14:04:08 +0200 (Fri, 17 Aug 2007)
New Revision: 7466
Log:
Interim commit with some minor rewrites
Modified:
trunk/refman-common/mysql-proxy.xml
Modified: trunk/refman-common/mysql-proxy.xml
===================================================================
--- trunk/refman-common/mysql-proxy.xml 2007-08-17 09:27:29 UTC (rev 7465)
+++ trunk/refman-common/mysql-proxy.xml 2007-08-17 12:04:08 UTC (rev 7466)
Changed blocks: 24, Lines Added: 199, Lines Deleted: 170; 24658 bytes
@@ -10,12 +10,12 @@
<title>MySQL Proxy</title>
<para>
- The MySQL Proxy is a small application that communicates over the
- network using the MySQL Network Protocol and provides communication
- between one or more MySQL servers and one or more MySQL clients. In
- the most basic configuration, MySQL Proxy simply passes on queries
- from the client to the MySQL Server and returns the responses from
- the MySQL Server to the client.
+ The MySQL Proxy is an application that communicates over the network
+ using the MySQL Network Protocol and provides communication between
+ one or more MySQL servers and one or more MySQL clients. In the most
+ basic configuration, MySQL Proxy simply passes on queries from the
+ client to the MySQL Server and returns the responses from the MySQL
+ Server to the client.
</para>
<para>
@@ -31,7 +31,7 @@
is also capable of monitoring and altering the communication between
the client and the server. This interception of the queries enables
you to add profiling The interception of the exchanges is scriptable
- using the LUA scripting language.
+ using the Lua scripting language.
</para>
<para>
@@ -105,7 +105,7 @@
as the main MySQL server. Currently MySQL Proxy is compatible only
with MySQL 5.0.1 and later. MySQL Proxy is provided as a
standalone, statically linked binary. You do not need to have
- MySQL or LUA installed.
+ MySQL or Lua installed.
</para>
</section>
@@ -216,12 +216,35 @@
<programlisting>$ tar zxf <replaceable>mysql-proxy-0.5.0.tar.gz</replaceable>
$ cd mysql-proxy-0.5.0
$ ./configure
-$ make
-$ make install</programlisting>
+$ make</programlisting>
<para>
+ If you want to test the build, then use the
+ <literal>check</literal> target to <command>make</command>:
+ </para>
+
+<programlisting>$ make check</programlisting>
+
+ <para>
+ The tests try to connect to <literal>localhost</literal> using
+ the <literal>root</literal> user. If you need to provide a
+ password, set the <literal>MYSQL_PASSWORD</literal> envirionment
+ variable:
+ </para>
+
+<programlisting>$ MYSQL_PASSWORD=root_pwd make check</programlisting>
+
+ <para>
+ You can install using the <literal>install</literal> target:
+ </para>
+
+<programlisting>$ make install</programlisting>
+
+ <para>
By default <command>mysql-proxy</command> is installed into
- <filename>/usr/local/sbin/mysql-proxy</filename>
+ <filename>/usr/local/sbin/mysql-proxy</filename>. The Lua
+ example scripts are copied into
+ <filename>/usr/local/share</filename>.
</para>
</section>
@@ -316,7 +339,8 @@
<para>
The script creates the standard <command>configure</command>
- script, which you can then use to configure and build:
+ script, which you can then use to configure and build weith
+ <command>make</command>:
</para>
<programlisting>$ ./configure
@@ -354,43 +378,13 @@
<para>
You can get a list of the supported command-line options using the
- <literal>--help-all</literal>:
+ <literal>--help-all</literal> command line option. The majority of
+ these options set up the environment, either in terms of the
+ address/port number that <command>mysql-proxy</command> should
+ listen on for connections, or the onward connection to a MySQL
+ server. A full description of the options is shown below:
</para>
-<programlisting>$ mysql-proxy --help-all
-Usage:
- mysql-proxy [OPTION...] - MySQL Proxy
-
-Help Options:
- -?, --help Show help options
- --help-all Show all help options
- --help-admin Show options for the admin-module
- --help-proxy Show options for the proxy-module
-
-admin module
- --admin-address=<ip:port> listening address:port of pseudo MySQL-server (default: :4041)
-
-proxy-module
- --proxy-address=<ip:port> listening address:port of the proxy-server (default: :4040)
- --proxy-read-only-address=<ip:port> listening address:port of the proxy-server for read-only connection (default: :4042)
- --proxy-backend-addresses=<ip:port> address:port of the remote backend-servers (default: not set)
- --proxy-skip-profiling disables profiling of queries (default: enabled)
- --proxy-fix-bug-25371 fix bug #25371 (MySQLd > 5.1.12) for older libMySQL versions
- --proxy-lua-script=<file> filename of the lua script (default: not set)
-
-Application Options:
- -V, --version Show version
- -D, --no-daemon Don't start in daemon-mode
- --pid-file=<file> PID file in case we are started as daemon</programlisting>
-
- <para>
- The majority of these options set up the environment, either in
- terms of the address/port number that
- <command>mysql-proxy</command> should listen on for connections,
- or the onward connection to a MySQL server. A full description of
- the options is shown below:
- </para>
-
<itemizedlist>
<listitem>
@@ -469,10 +463,10 @@
<listitem>
<para>
<literal>--proxy-lua-script=file </literal> — specify
- the LUA script file to be loaded. Note that the script file is
+ the Lua script file to be loaded. Note that the script file is
not physically loaded and parsed until a connection is made.
- Also note that the specified LUA script is reloaded for each
- connection; if the content of the LUA script changes while
+ Also note that the specified Lua script is reloaded for each
+ connection; if the content of the Lua script changes while
<command>mysql-proxy</command> is running then the updated
content will automatically be used when a new connection is
made.
@@ -481,8 +475,8 @@
<listitem>
<para>
- <literal>--no-daemon</literal> — prevents the proxy from
- becoming a daemon and changing it's working directory to root.
+ <literal>--daemon</literal> — starts the proxy in daemon
+ mode.
</para>
</listitem>
@@ -502,12 +496,6 @@
</itemizedlist>
<para>
- By default, <command>mysql-proxy</command> will start up as a
- Daemon process and sets the home directory to root
- (<filename>/</filename>).
- </para>
-
- <para>
The most common usage is as a simple proxy service (i.e. without
addition scripting). For basic proxy operation you must specify at
least one <literal>proxy-backend-addresses</literal> option to
@@ -547,7 +535,7 @@
<para>
For more detailed information on how to use these command line
options, and <command>mysql-proxy</command> in general in
- combination with LUA scripts, see
+ combination with Lua scripts, see
<xref linkend="mysql-proxy-using"/>.
</para>
@@ -560,15 +548,17 @@
<para>
You can control how MySQL Proxy manipulates and works with the
queries and results that are passed on to the MySQL server through
- the use of the embedded LUA scripting language. You can find out
- more about the LUA programming language from the
- <ulink url="http://www.lua.org">LUA Website</ulink>.
+ the use of the embedded Lua scripting language. You can find out
+ more about the Lua programming language from the
+ <ulink url="http://www.lua.org">Lua Website</ulink>.
</para>
<para>
The primary interaction between MySQL Proxy and the server is
- provided by defining on or more functions through an LUA script.
- Three functions are currently supported:
+ provided by defining one or more functions through an Lua script.
+ A number of functions are supported, according to different events
+ and operations in the communication sequence between a client and
+ one or more backend MySQL servers:
</para>
<itemizedlist>
@@ -628,10 +618,14 @@
<listitem>
<para>
<literal>read_query_result()</literal> — this function
- is called each time a result is returned from the server. You
- can use this to edit the result set, or to remove or filter
- the result sets generated from additional queries you injected
- into the queue when using <literal>read_query()</literal>.
+ is called each time a result is returned from the server,
+ providing you have manually injected queries into the query
+ queue. If you have not explicitly inject queries within the
+ <function>read_query()</function> function then this function
+ is not triggered. You can use this to edit the result set, or
+ to remove or filter the result sets generated from additional
+ queries you injected into the queue when using
+ <literal>read_query()</literal>.
</para>
</listitem>
@@ -697,104 +691,122 @@
that are returned.
</para>
- <para>
- The figure below gives an example of how the proxy might be used.
- Because the proxy sits between the client and MySQL server, what
- the proxy sends to the server, and the information that the proxy
- ultimately returns to the client do not have to match correlate.
- Once the client has connected to the proxy, the following sequence
- occurs for each individual query sent by the client.
- </para>
+ <section id="mysql-proxy-scripting-connection">
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/published/proxy-architecture.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase lang="en">MySQL Proxy architecture</phrase>
- </textobject>
- </mediaobject>
+ <title>Proxy Scripting Sequence During Connection</title>
- <orderedlist>
+ </section>
- <listitem>
- <para>
- The client submits one query to the proxy, the
- <function>read_query()</function> function within the proxy is
- triggered. The function adds the query to the query queue.
- </para>
- </listitem>
+ <section id="mysql-proxy-scripting-query">
- <listitem>
- <para>
- Once manipulation by <function>read_query()</function> has
- completed, the queries are submitted, sequentially, to the
- MySQL server.
- </para>
- </listitem>
+ <title>Proxy Scripting Sequence During Query Submission</title>
- <listitem>
- <para>
- The MySQL server returns the results from each query, one
- result set for each query submitted. The
- <function>read_query_results()</function> function is
- triggered for each result set, and each invocation can decide
- which result set to return to the client
- </para>
- </listitem>
+ </section>
- </orderedlist>
+ <section id="mysql-proxy-scripting-injection">
- <para>
- For example, you can queue additional queries into the global
- query queue to be processed by the server. This can be used to add
- statistical information by adding queries before and after the
- original query, changing the original query:
- </para>
+ <title>Proxy Scripting Sequence During Query Injection</title>
+ <para>
+ The figure below gives an example of how the proxy might be
+ used. Because the proxy sits between the client and MySQL
+ server, what the proxy sends to the server, and the information
+ that the proxy ultimately returns to the client do not have to
+ match correlate. Once the client has connected to the proxy, the
+ following sequence occurs for each individual query sent by the
+ client.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/published/proxy-architecture.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase lang="en">MySQL Proxy architecture</phrase>
+ </textobject>
+ </mediaobject>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ The client submits one query to the proxy, the
+ <function>read_query()</function> function within the proxy
+ is triggered. The function adds the query to the query
+ queue.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Once manipulation by <function>read_query()</function> has
+ completed, the queries are submitted, sequentially, to the
+ MySQL server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The MySQL server returns the results from each query, one
+ result set for each query submitted. The
+ <function>read_query_result()</function> function is
+ triggered for each result set, and each invocation can
+ decide which result set to return to the client
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ For example, you can queue additional queries into the global
+ query queue to be processed by the server. This can be used to
+ add statistical information by adding queries before and after
+ the original query, changing the original query:
+ </para>
+
<programlisting>SELECT * FROM City;</programlisting>
- <para>
- Into a sequence of queries:
- </para>
+ <para>
+ Into a sequence of queries:
+ </para>
<programlisting>SELECT NOW();
SELECT * FROM City;
SELECT NOW();</programlisting>
- <para>
- You can also modify the original statement, for example to add
- <literal>EXPLAIN</literal> to each statement executed to get
- information on how the statement was processed, again altering our
- original SQL statement into a number of statements:
- </para>
+ <para>
+ You can also modify the original statement, for example to add
+ <literal>EXPLAIN</literal> to each statement executed to get
+ information on how the statement was processed, again altering
+ our original SQL statement into a number of statements:
+ </para>
<programlisting>SELECT * FROM City;
EXPLAIN SELECT * FROM City;</programlisting>
- <para>
- In both of these examples, the client would have received more
- result sets than expected. Regardless of how you manipulate the
- incoming query and the returned result, the number of queries
- returned by the proxy must match the number of original queries
- sent by the client.
- </para>
+ <para>
+ In both of these examples, the client would have received more
+ result sets than expected. Regardless of how you manipulate the
+ incoming query and the returned result, the number of queries
+ returned by the proxy must match the number of original queries
+ sent by the client.
+ </para>
- <para>
- You could adjust the client to handle the multiple result sets
- sent by the proxy, but in most cases you will want the existence
- of the proxy to remain transparent. To ensure that the number of
- queries and result sets match, you can use the MySQL Proxy
- <function>read_query_results()</function> to extract the
- additional result set information and return only the result set
- the client originally requested back to the client. You can
- achieve this by giving each query that you add to the query queue
- a unique ID, and then filter out queries that do not match the
- original query ID when processing them with
- <function>read_query_results()</function>.
- </para>
+ <para>
+ You could adjust the client to handle the multiple result sets
+ sent by the proxy, but in most cases you will want the existence
+ of the proxy to remain transparent. To ensure that the number of
+ queries and result sets match, you can use the MySQL Proxy
+ <function>read_query_result()</function> to extract the
+ additional result set information and return only the result set
+ the client originally requested back to the client. You can
+ achieve this by giving each query that you add to the query
+ queue a unique ID, and then filter out queries that do not match
+ the original query ID when processing them with
+ <function>read_query_result()</function>.
+ </para>
- <para></para>
+ </section>
<section id="mysql-proxy-scripting-structures">
@@ -802,12 +814,13 @@
<para>
There are a number of internal structures within the scripting
- element of MySQL Proxy. The primary, global, structure is
+ element of MySQL Proxy. The primary structure is
<literal>proxy</literal> and this provides an interface to the
- global structures, such as connection lists and configured
- backend servers. Other structures, such as the incoming packet
- from the client and result sets are only available within the
- context of one of the scriptable functions.
+ many common structures used throughout the script, such as
+ connection lists and configured backend servers. Other
+ structures, such as the incoming packet from the client and
+ result sets are only available within the context of one of the
+ scriptable functions.
</para>
<informaltable id="mysql-proxy-scripting-structures-proxy">
@@ -850,7 +863,7 @@
<entry><literal>PROXY_VERSION</literal></entry>
<entry>The version number of MySQL Proxy, encoded in hex. You can use this to
check that the version number supports a particular
- option from within the LUA script. Note that the value
+ option from within the Lua script. Note that the value
is encoded as a hex value, so to check the version is at
least 0.5.1 you compare against
<literal>0x00501</literal>.</entry>
@@ -951,11 +964,18 @@
<para>
The <literal>proxy.queries</literal> object is a queue
representing the list of queries to be sent to the server. The
- queue is automatically populated with the original query from
- the client. You can <literal>append()</literal> or
- <literal>prepend()</literal> queries to the query queue.
+ queue is not populated automatically, but if you do not
+ explicitly populate the queue then queries are passed on to the
+ backend server verbatim. Also, if you do not populate the query
+ queue by hand, then the <function>read_query_result()</function>
+ function is not triggered.
</para>
+ <para>
+ When populating the queue, you can <literal>append()</literal>
+ or <literal>prepend()</literal> queries to the query queue.
+ </para>
+
<informaltable>
<tgroup cols="2">
<colspec colwidth="30*"/>
@@ -1520,20 +1540,29 @@
Normally, the <function>read_query()</function> and
<function>read_query_result()</function> function are used in
conjunction with each other to inject additional queries and
- remove the additional result sets.
+ remove the additional result sets. However,
+ <function>read_query_result()</function> is only called if you
+ populate the query queue within
+ <function>read_query()</function>.
</para>
+ <para>
+ Because <function>read_query()</function> is called
+ </para>
+
</section>
<section id="mysql-proxy-scripting-read-query-result">
- <title>Manipulating Results with <function>read_query_results()</function></title>
+ <title>Manipulating Results with <function>read_query_result()</function></title>
<para>
The <function>reach_query_results()</function> is called for
- each result set returned by the server. The function supports a
- single argument, the result packet, which provides a number of
- properties:
+ each result set returned by the server only if you have manually
+ injected queries into the query queue. If you have not
+ manipulated the query queue then this function is not called.
+ The function supports a single argument, the result packet,
+ which provides a number of properties:
</para>
<itemizedlist>
@@ -1586,7 +1615,7 @@
</para>
<para>
- The LUA script below, for example, will output the query,
+ The Lua script below, for example, will output the query,
followed by the query time and response time (i.e. the time to
execute the query and the time to return the data for the query)
for each query sent to the server:
@@ -1613,7 +1642,7 @@
result that is exposed through
<function>read_query_result()</function>. For example, you can
iterate over the results showing the first column from each row
- using this LUA fragment:
+ using this Lua fragment:
</para>
<programlisting>for row in inj.resultset.rows do
@@ -1622,7 +1651,7 @@
<para>
Just like <function>read_query()</function>,
- <function>read_query_results()</function> can return different
+ <function>read_query_result()</function> can return different
values for each result according to the result returned. If you
have injected additional queries into the query queue, for
example, then you will want to remove the results returned from
@@ -1634,7 +1663,7 @@
The example below injects additional <literal>SELECT
NOW()</literal> statements into the query queue, given them a
different ID to the ID of the original query. Within
- <function>read_query_results()</function>, if the ID for the
+ <function>read_query_result()</function>, if the ID for the
injected queries is identified, we display the result row, and
return the <literal>proxy.PROXY_IGNORE_RESULT</literal> from the
function so that the result is not returned to the client. If
@@ -1716,9 +1745,9 @@
</programlisting>
<para>
- LUA scripts enable a finer level of control, both over the
+ Lua scripts enable a finer level of control, both over the
connections and their distribution and how queries and result sets
- are processed. When using an LUA script, you must specify the name
+ are processed. When using an Lua script, you must specify the name
of the script on the command line using the
<option>--proxy-lua-script</option> option:
</para>
@@ -1727,15 +1756,15 @@
<para>
When you specify a script, the script is not executed until a
- connection a made. This means that faults with the script will not
- be raised until the script is executed. Script faults will not
+ connection is made. This means that faults with the script will
+ not be raised until the script is executed. Script faults will not
affect the distribution of queries to backend MySQL servers.
</para>
<note>
<para>
Because the script is not read until the connection is made, you
- can modify the contents of the LUA script file while the proxy
+ can modify the contents of the Lua script file while the proxy
is still running and the script will automatically be used for
the next connection. This ensures that MySQL Proxy remains
available because it does not have to be restarted for the
@@ -1746,14 +1775,14 @@
<para>
You can control how clients are distributed among backend servers,
for example, choosing slaves in a master/slave replication
- environment, by using an LUA script to manage incoming
+ environment, by using an Lua script to manage incoming
connections. See
<xref
linkend="mysql-proxy-using-loadbalancer"/>.
</para>
<para>
- You can also use an LUA script to profile your SQL statements by
+ You can also use an Lua script to profile your SQL statements by
adding and/or monitoring the execution of the statements and
reporting extended information about their execution. For more
information, see <xref linkend="mysql-proxy-using-profiling"/>.
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r7466 - trunk/refman-common | mcbrown | 17 Aug |
