To start mysql-proxy you can just run the command directly. However, for most situations you will want to specify at the very least the address/host name and port number of the backend MySQL server to which the MySQL Proxy should pass on queries.
You can specify options to mysql-proxy either
on the command line, or by using a configuration file and the
--defaults-file
command-line option to specify
the file location.
If you want to use a configuration file, then the file should be formatted as follows:
Options must be specified within a configuration group named
mysql-proxy
. For example:
[mysql-proxy] admin-address = host:port
All configuration options should be specified in the form of a configuration name and the value you want to set.
For options that are a simple toggle on the command-line (for
example --proxy-skip-profiling
, you must use
true
or false
. For
example, the following is invalid:
[mysql-proxy] proxy-skip-profiling
But this is valid:
[mysql-proxy] proxy-skip-profiling = true
The configuration file should have permissions of
0660
(readable and writable by user and
group, no access for everybody).
Failure to adhere to any of these requirements will trigger an error during startup.
A list of the supported configuration file and command line otpions are given in the tables below.
Table 14.3. mysql-proxy Help Options
Format | Config File | Description | Introduction | Deprecated | Removed |
---|---|---|---|---|---|
--help | help | Show help options | 0.8.0 | ||
--help-admin | help-admin | Show options for the admin-module | 0.8.0 | ||
--help-all | help-all | Show all help options | 0.8.0 | ||
--help-proxy | help-proxy | Show options for the proxy-module | 0.8.0 |
Table 14.4. mysql-proxy Admin Options
Format | Config File | Description | Introduction | Deprecated | Removed |
---|---|---|---|---|---|
--admin-address | admin-address | Defines the listening address and poirt for the admin module | 0.8.0 | ||
--admin-lua-script | admin-lua-script | Script to execute by the admin module | 0.8.0 | ||
--admin-password | admin-password | Password for authentication for admin module | 0.8.0 | ||
--admin-username | admin-username | Username for authentication for admin module | 0.8.0 | ||
--proxy-address | proxy-address | Listening address:port of the proxy server | 0.8.0 |
Table 14.5. mysql-proxy Proxy Options
Format | Config File | Description | Introduction | Deprecated | Removed |
---|---|---|---|---|---|
--no-proxy | no-proxy | Don't start the proxy module | 0.8.0 | ||
--proxy-backend-addresses | proxy-backend-addresses | Address:port of the remote MySQL server | 0.8.0 | ||
--proxy-fix-bug-25371 | proxy-fix-bug-25371 | Enable the fix for Bug#25371 (for mysqld > 0.8.0.12) for older libmysql versions | 0.8.0 | ||
--proxy-lua-script | proxy-lua-script | Filename for Lua script for proxy operations | 0.8.0 | ||
--proxy-pool-no-change-user | proxy-pool-no-change-user | Don't use the protocol CHANGE_USER to reset the connection when coming from the connection pool | 0.8.0 | ||
--proxy-read-only-backend-addresses | proxy-read-only-backend-addresses | Address:port of the remote MySQL server (read-only) | 0.8.0 | ||
--proxy-skip-profiling | proxy-skip-profiling | Disabled profiling of queries | 0.8.0 |
Table 14.6. mysql-proxy Applications Options
Format | Config File | Description | Introduction | Deprecated | Removed |
---|---|---|---|---|---|
--basedir | basedir | Specify the base directory to prepend to paths in the config | 0.8.0 | ||
--daemon | daemon | Start in daemon-mode | 0.8.0 | ||
--defaults-file | defaults-file | Specify the configuration file | 0.8.0 | ||
--event-threads | event-threads | The number of event-handling threads | 0.8.0 | ||
--keepalive | keepalive | Try to restart the proxy if a crash occurs | 0.8.0 | ||
--log-backtrace-on-crash | log-backtrace-on-crash | Try to invoke the debug and generate a backtrace on crash | 0.8.0 | ||
--log-file | log-file | Specify the file for logging error messages | 0.8.0 | ||
--log-level | log-level | Logging level | 0.8.0 | ||
--log-use-syslog | log-use-syslog | Log errors to syslog | 0.8.0 | ||
--lua-cpath | lua-cpath | Set the LUA_CPATH | 0.8.0 | ||
--lua-path | lua-path | Set the LUA_PATH | 0.8.0 | ||
--max-open-files | max-open-files | Specify the maximum number of open files to support | 0.8.0 | ||
--pid-file | pid-file | PID file to store the process ID (when in daemon mode) | 0.8.0 | ||
--plugin-dir | plugin-dir | Path to the plugin files | 0.8.0 | ||
--plugins | plugins | List of plugins to load | 0.8.0 | ||
--user | user | Specify the user to use when running mysql-proxy | 0.8.0 | ||
--version | version | Show the version information | 0.8.0 |
Except as noted in the details below, all of the options can be used within the configuration file by supplying the option and the corresponding value. For example:
log-file = /var/log/mysql-proxy.log log-level = message
Version Introduced | 0.8.0 | |
Command-Line Format | --help |
|
Config-File Format | help |
Show available help options.
Version Introduced | 0.8.0 | |
Command-Line Format | --help-all |
|
Config-File Format | help-all |
Show all help options.
Version Introduced | 0.8.0 | |
Command-Line Format | --help-admin |
|
Config-File Format | help-admin |
Show options for the admin-module.
Version Introduced | 0.8.0 | |
Command-Line Format | --help-proxy |
|
Config-File Format | help-proxy |
Show options for the proxy-module.
Version Introduced | 0.8.0 | |
Command-Line Format | --admin-address |
|
Config-File Format | admin-address |
|
Permitted Values | ||
Type | string |
|
Default | :4041 |
The host name (or IP address) and port for the administration
port. The default is localhost:4041
.
Version Introduced | 0.8.0 | |
Command-Line Format | --admin-lua-script |
|
Config-File Format | admin-lua-script |
|
Permitted Values | ||
Type | filename |
|
Default |
|
The script to use for the administration module for the proxy.
Version Introduced | 0.8.0 | |
Command-Line Format | --admin-password |
|
Config-File Format | admin-password |
|
Permitted Values | ||
Type | string |
|
Default |
|
The password to use to authenticate users wanting to connect to the administration module of mysql-proxy. The administration module uses the MySQL protocol to request a username and password for connections.
Version Introduced | 0.8.0 | |
Command-Line Format | --admin-username |
|
Config-File Format | admin-username |
|
Permitted Values | ||
Type | string |
|
Default | root |
The username to use to authenticate users wanting to connect
to the administration module of
mysql-proxy. The default username is
root
. The administration module uses the
MySQL protocol to request a username and password for
connections.
Version Introduced | 0.8.0 | |
Command-Line Format | --basedir |
|
Config-File Format | basedir |
|
Permitted Values | ||
Type | filename |
The base directory that will be prepended to all other filename configuration options. The base name should be an absolute (not relative) directory. If you specify a relative directory, mysql-proxy will generate an error during startup.
Version Introduced | 0.8.0 | |
Command-Line Format | --defaults-file |
|
Config-File Format | defaults-file |
The file to use as the file with configuration information. If not specified, configuration options are only taken from the command line.
Version Introduced | 0.8.0 | |
Command-Line Format | --event-threads |
|
Config-File Format | event-threads |
|
Permitted Values | ||
Type | numeric |
|
Default | 1 |
The number of event threads reserved to handle incoming requests.
Version Introduced | 0.8.0 | |
Command-Line Format | --keepalive |
|
Config-File Format | keepalive |
Creates a process surrounding the main mysql-proxy which will attempt to restart the true mysql-proxy process in thr event a crash or other failure.
Version Introduced | 0.8.0 | |
Command-Line Format | --log-backtrace-on-crash |
|
Config-File Format | log-backtrace-on-crash |
Logs the backtrace to the error log and tries to initialize the debugger in the event of a failure.
Version Introduced | 0.8.0 | |
Command-Line Format | --log-file |
|
Config-File Format | log-file |
|
Permitted Values | ||
Type | filename |
The name of a file to be used to record log information.
Version Introduced | 0.8.0 | |
Command-Line Format | --log-level |
|
Config-File Format | log-level |
|
Permitted Values | ||
Type | enumeration |
|
Valid Values |
error , warning , info , message , debug
|
The log level to be used when outputting error messages. The
specification will output that level (or lower) of a given
error message. For example, message
will
also output info
,
warning
, and error
messages.
Version Introduced | 0.8.0 | |
Command-Line Format | --log-use-syslog |
|
Config-File Format | log-use-syslog |
Causes errors to be sent to the syslog (Unix/Linux only).
Version Introduced | 0.8.0 | |
Command-Line Format | --lua-cpath |
|
Config-File Format | lua-cpath |
|
Permitted Values | ||
Type | filename |
The LUA_CPATH
to be used when loading
compiled modules or libraries for Lua scripts.
Version Introduced | 0.8.0 | |
Command-Line Format | --lua-path |
|
Config-File Format | lua-path |
|
Permitted Values | ||
Type | filename |
The LUA_CPATH
to be used when loading
modules for Lua.
Version Introduced | 0.8.0 | |
Command-Line Format | --max-open-files |
|
Config-File Format | max-open-files |
|
Permitted Values | ||
Type | numeric |
The maximum number of open files and sockets supported by the mysql-proxy process. You may need to increase this with certain scripts.
Version Introduced | 0.8.0 | |
Command-Line Format | --no-proxy |
|
Config-File Format | no-proxy |
Disable the proxy module.
Version Introduced | 0.8.0 | |
Command-Line Format | --plugin-dir |
|
Config-File Format | plugin-dir |
|
Permitted Values | ||
Type | filename |
The directory to use when loading plugins for mysql-proxy.
Version Introduced | 0.8.0 | |
Command-Line Format | --plugins |
|
Config-File Format | plugins |
|
Permitted Values | ||
Type | string |
A comma-separated list of the plugins to be loaded.
Version Introduced | 0.8.0 | |
Command-Line Format | --proxy-address |
|
Config-File Format | proxy-address |
|
Permitted Values | ||
Type | string |
|
Default | :4040 |
The listening host name (or IP address) and port of the proxy
server. The default is :4040
(all IPs on
port 4040).
--proxy-read-only-backend-addresses=host:port
Version Introduced | 0.8.0 | |
Command-Line Format | --proxy-read-only-backend-addresses |
|
Config-File Format | proxy-read-only-backend-addresses |
|
Permitted Values | ||
Type | string |
The listening host name (or IP address) and port of the proxy server for read-only connections. The default is for this information not to be set.
Setting this value only configures the servers within the
corresponding internal structure (see
proxy.global.backends
).
You can determine the backend type by checking the
type
field for each connection.
You should therefore only use this option in combination with a script designed to make use of ther different backend types.
When using this option on the command-line, you can specify the option and the server multiple times to specify multiple backends. For example:
shell> mysql-proxy --proxy-read-only-backend-addresses 192.168.0.1:3306 --proxy-read-only-backend-addresses 192.168.0.2:3306
When using the option within the configuration file, you should separate multiple servers with a comma. The equivalent of the above example would be:
... read-only-backend-addresses = 192.168.0.1:3306, 192.168.0.2:3306
--proxy-backend-addresses=host:port
The host name (or IP address) and port of the MySQL server to connect to. You can specify multiple backend servers by supplying multiple options. Clients are connected to each backend server in round-robin fashion. For example, if you specify two servers A and B, the first client connection will go to server A; the second client connection to server B and the third client connection to server A.
When using this option on the command-line, you can specify the option and the server multiple times to specify multiple backends. For example:
shell> mysql-proxy --backend-addresses 192.168.0.1:3306 --backend-addresses 192.168.0.2:3306
When using the option within the configuration file, you should separate multiple servers with a comma. The equivalent of the above example would be:
... backend-addresses = 192.168.0.1:3306, 192.168.0.2:3306
Version Introduced | 0.8.0 | |
Command-Line Format | --proxy-pool-no-change-user |
|
Config-File Format | proxy-pool-no-change-user |
Disables the use of the MySQL protocol
CHANGE_USER
when reusing a connection from
the pool of connections specified by the
backend-addresses
list.
Disables profiling of queries (tracking time statistics). The default is for tracking to be enabled.
Version Introduced | 0.8.0 | |
Command-Line Format | --proxy-fix-bug-25371 |
|
Config-File Format | proxy-fix-bug-25371 |
Gets round an issue when connecting to a MySQL server later than 5.1.12 when using a MySQL client library of any earlier version.
Version Introduced | 0.8.0 | |
Command-Line Format | --proxy-lua-script |
|
Config-File Format | proxy-lua-script |
|
Permitted Values | ||
Type | filename |
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 mysql-proxy is running then the updated content will automatically be used when a new connection is made.
Version Introduced | 0.8.0 | |
Command-Line Format | --daemon |
|
Config-File Format | daemon |
Starts the proxy in daemon mode.
Version Introduced | 0.8.0 | |
Command-Line Format | --pid-file |
|
Config-File Format | pid-file |
|
Permitted Values | ||
Type | filename |
Sets the name of the file to be used to store the process ID.
Version Introduced | 0.8.0 | |
Command-Line Format | --user |
|
Config-File Format | user |
|
Permitted Values | ||
Type | string |
Run mysql-proxy as the specified
user
.
Version Introduced | 0.8.0 | |
Command-Line Format | --version |
|
Config-File Format | version |
Show the version number.
The most common usage is as a simple proxy service (that is,
without addition scripting). For basic proxy operation you must
specify at least one proxy-backend-addresses
option to specify the MySQL server to connect to by default:
shell> mysql-proxy --proxy-backend-addresses=MySQL.example.com:3306
The default proxy port is 4040
, so you can
connect to your MySQL server through the proxy by specifying the
host name and port details:
shell> mysql --host=localhost --port=4040
If your server requires authentication information then this will be passed through natively without alteration by mysql-proxy, so you must also specify the authentication information if required:
shell> mysql --host=localhost --port=4040 \ --user=username --password=password
You can also connect to a read-only port (which filters out
UPDATE
and
INSERT
queries) by connecting to
the read-only port. By default the host name is the default, and
the port is 4042
, but you can alter the
host/port information by using the
--proxy-read-only-address
command-line option.
For more detailed information on how to use these command line options, and mysql-proxy in general in combination with Lua scripts, see Section 14.6.5, “Using MySQL Proxy”.
User Comments
Add your own comment.