15.7.3. MySQL Proxy Command Options

To start MySQL Proxy, you can run it directly from the command line:

shell> mysql-proxy

For most situations, you specify at least the host name or address and the port number of the backend MySQL server to which the MySQL Proxy should pass 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 use a configuration file, format it as follows:

Specify the options within a [mysql-proxy] configuration group. For example:
```
[mysql-proxy]admin-address = host:port
```
Specify all configuration options in the form of a configuration name and the value to set.
For options that are a simple toggle on the command line (for example, --proxy-skip-profiling), 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
```
Give the configuration file Unix permissions of 0660 (readable and writable by user and group, no access for others).

Failure to adhere to any of these requirements causes mysql-proxy to generate an error during startup.

The following tables list the supported configuration file and command-line options.

Table 15.4. mysql-proxy Help Options

Format	Option File	Description
--help		Show help options
--help-admin		Show admin module options
--help-all		Show all help options
--help-proxy		Show proxy module options

Table 15.5. mysql-proxy AdminOptions

Format	Option File	Description
--admin-address=host:port	admin-address=host:port	The admin module listening host and port
--admin-lua-script=file_name	admin-lua-script=file_name	Script to execute by the admin module
--admin-password=password	admin-password=password	Authentication password for admin module
--admin-username=user_name	admin-username=user_name	Authentication user name for admin module
--proxy-address=host:port	proxy-address=host:port	The listening proxy server host and port

Table 15.6. mysql-proxy ProxyOptions

Format	Option File	Description	Removed
--no-proxy	no-proxy	Do not start the proxy module
--proxy-backend-addresses=host:port	proxy-backend-addresses=host:port	The MySQL server host and port
--proxy-fix-bug-25371	proxy-fix-bug-25371	Enable the fix for Bug #25371 for older libmysql versions	0.8.1
--proxy-lua-script=file_name	proxy-lua-script=file_name	Filename for Lua script for proxy operations
--proxy-pool-no-change-user	proxy-pool-no-change-user	Do not use the protocol CHANGE_USER command to reset the connection when coming from the connection pool
--proxy-read-only-backend-addresses=host:port	proxy-read-only-backend-addresses=host:port	The MySQL server host and port (read only)
--proxy-skip-profiling	proxy-skip-profiling	Disable query profiling

Table 15.7. mysql-proxy ApplicationsOptions

Format	Option File	Description
--basedir=dir_name	basedir=dir_name	The base directory prefix for paths in the configuration
--daemon	daemon	Start in daemon mode
--defaults-file=file_name		The configuration file to use
--event-threads=count	event-threads=count	The number of event-handling threads
--keepalive	keepalive	Try to restart the proxy if a crash occurs
--log-backtrace-on-crash	log-backtrace-on-crash	Try to invoke the debugger and generate a backtrace on crash
--log-file=file_name	log-file=file_name	The file where error messages are logged
--log-level=level	log-level=level	The logging level
--log-use-syslog	log-use-syslog	Log errors to syslog
--lua-cpath=dir_name	lua-cpath=dir_name	Set the LUA_CPATH
--lua-path=dir_name	lua-path=dir_name	Set the LUA_PATH
--max-open-files=count	max-open-files=count	The maximum number of open files to support
--pid-file=file_name	pid-file=file_name	File in which to store the process ID
--plugin-dir=dir_name	plugin-dir=dir_name	Directory containing plugin files
--plugins=plugin,...	plugins=plugin,...	List of plugins to load
--user=user_name	user=user_name	The user to use when running mysql-proxy
--version		Show version information

Except as noted in the following details, all of the options can be used within the configuration file by supplying the option and the corresponding value. For example:

[mysql-proxy]log-file = /var/log/mysql-proxy.loglog-level = message

--help, -h

Command-Line Format	`--help`
	`-h`

Show available help options.

--help-admin

Command-Line Format --help-admin

Show options for the admin module.

--help-all

Command-Line Format --help-all

Show all help options.

--help-proxy

Command-Line Format --help-proxy

Show options for the proxy module.

--admin-address=host:port

Command-Line Format	`--admin-address=host:port`
Option-File Format	`admin-address=host:port`
	Permitted Values
	Type	`string`
	Default	`:4041`

The host name (or IP address) and port for the administration port. The default is localhost:4041.

--admin-lua-script=file_name

Command-Line Format	`--admin-lua-script=file_name`
Option-File Format	`admin-lua-script=file_name`
	Permitted Values
	Type	`file name`
	Default

The script to use for the proxy administration module.

--admin-password=password

Command-Line Format	`--admin-password=password`
Option-File Format	`admin-password=password`
	Permitted Values
	Type	`string`
	Default

The password to use to authenticate users wanting to connect to the MySQL Proxy administration module. This module uses the MySQL protocol to request a user name and password for connections.

--admin-username=user_name

Command-Line Format	`--admin-username=user_name`
Option-File Format	`admin-username=user_name`
	Permitted Values
	Type	`string`
	Default	`root`

The user name to use to authenticate users wanting to connect to the MySQL Proxy administration module. This module uses the MySQL protocol to request a user name and password for connections. The default user name is root.

--basedir=dir_name

Command-Line Format	`--basedir=dir_name`
Option-File Format	`basedir=dir_name`
	Permitted Values
	Type	`directory name`

The base directory to use as a prefix for all other file name configuration options. The base name should be an absolute (not relative) directory. If you specify a relative directory, mysql-proxy generates an error during startup.

--daemon

Command-Line Format	`--daemon`
Option-File Format	`daemon`

Starts the proxy in daemon mode.

--defaults-file=file_name

Command-Line Format --defaults-file=file_name

The file to read for configuration options. If not specified, MySQL Proxy takes options only from the command line.

--event-threads=count

Command-Line Format	`--event-threads=count`
Option-File Format	`event-threads=count`
	Permitted Values
	Type	`numeric`
	Default	`1`

The number of event threads to reserve to handle incoming requests.

--keepalive

Command-Line Format	`--keepalive`
Option-File Format	`keepalive`

Create a process surrounding the main mysql-proxy process that attempts to restart the main mysql-proxy process in the event of a crash or other failure.

Note

The --keepalive option is not available on Microsoft Windows. When running as a service, mysql-proxy automatically restarts.

--log-backtrace-on-crash

Command-Line Format	`--log-backtrace-on-crash`
Option-File Format	`log-backtrace-on-crash`

Log a backtrace to the error log and try to initialize the debugger in the event of a failure.

--log-file=file_name

Command-Line Format	`--log-file=file_name`
Option-File Format	`log-file=file_name`
	Permitted Values
	Type	`file name`

The file to use to record log information. If this option is not given, mysql-proxy logs to the standard error output.

--log-level=level

Command-Line Format	`--log-level=level`
Option-File Format	`log-level=level`
	Permitted Values
	Type	`enumeration`
	Valid Values	`error`
		`warning`
		`info`
		`message`
		`debug`

The log level to use when outputting error messages. Messages with that level (or lower) are output. For example, message level also outputs message with info, warning, and error levels.

--log-use-syslog

Command-Line Format	`--log-use-syslog`
Option-File Format	`log-use-syslog`

Log errors to the syslog (Unix/Linux only).

--lua-cpath=dir_name

Command-Line Format	`--lua-cpath=dir_name`
Option-File Format	`lua-cpath=dir_name`
	Permitted Values
	Type	`directory name`

The LUA_CPATH to use when loading compiled modules or libraries for Lua scripts.

--lua-path=dir_name

Command-Line Format	`--lua-path=dir_name`
Option-File Format	`lua-path=dir_name`
	Permitted Values
	Type	`directory name`

The LUA_CPATH to use when loading modules for Lua.

--max-open-files=count

Command-Line Format	`--max-open-files=count`
Option-File Format	`max-open-files=count`
	Permitted Values
	Type	`numeric`

The maximum number of open files and sockets supported by the mysql-proxy process. Certain scripts might require a higher value.

--no-proxy

Command-Line Format	`--no-proxy`
Option-File Format	`no-proxy`

Disable the proxy module.

--plugin-dir=dir_name

Command-Line Format	`--plugin-dir=dir_name`
Option-File Format	`plugin-dir=dir_name`
	Permitted Values
	Type	`directory name`

The directory to use when loading plugins for mysql-proxy.

--plugins=plugin

Command-Line Format	`--plugins=plugin,...`
Option-File Format	`plugins=plugin,...`
	Permitted Values
	Type	`string`

Loads a plugin.

When using this option on the command line, you can specify the option multiple times to specify multiple plugins. For example:

shell> mysql-proxy --plugins=proxy
                    --plugins=admin

When using the option within the configuration file, you should separate multiple plugins by commas. The equivalent of the preceding example would be:

...plugins=proxy,admin

--proxy-address=host:port, -P host:port

Command-Line Format	`--proxy-address=host:port`
	`-P host:port`
Option-File Format	`proxy-address=host:port`
	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, -r host:port

Command-Line Format	`--proxy-read-only-backend-addresses=host:port`
	`-r host:port`
Option-File Format	`proxy-read-only-backend-addresses=host:port`
	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.

Note

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 the 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 by commas. The equivalent of the preceding example would be:

...proxy-read-only-backend-addresses = 192.168.0.1:3306,192.168.0.2:3306

--proxy-backend-addresses=host:port, -b host:port

Command-Line Format	`--proxy-backend-addresses=host:port`
	`-b host:port`
Option-File Format	`proxy-backend-addresses=host:port`
	Permitted Values
	Type	`string`
	Default	`127.0.0.1:3306`

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
                    --proxy-backend-addresses 192.168.0.1:3306 --proxy-backend-addresses
                    192.168.0.2:3306

When using the option within the configuration file, you should separate multiple servers by commas. The equivalent of the preceding example would be:

...proxy-backend-addresses = 192.168.0.1:3306,192.168.0.2:3306

--proxy-pool-no-change-user

Command-Line Format	`--proxy-pool-no-change-user`
Option-File Format	`proxy-pool-no-change-user`

Disable use of the MySQL protocol CHANGE_USER command when reusing a connection from the pool of connections specified by the proxy-backend-addresses list.

--proxy-skip-profiling

Command-Line Format	`--proxy-skip-profiling`
Option-File Format	`proxy-skip-profiling`

Disable query profiling (statistics time tracking). The default is for tracking to be enabled.

--proxy-fix-bug-25371

Removed	0.8.1
Command-Line Format	`--proxy-fix-bug-25371`
Option-File Format	`proxy-fix-bug-25371`

Enable a workaround for an issue when connecting to a MySQL server later than 5.1.12 when using a MySQL client library of any earlier version.

This option was removed in mysql-proxy 0.8.1. Now, mysql-proxy returns an error message at the protocol level if it sees a COM_CHANGE_USER being sent to a server that has a version from 5.1.14 to 5.1.17.

--proxy-lua-script=file_name, -s file_name

Command-Line Format	`--proxy-lua-script=file_name`
	`-s file_name`
Option-File Format	`proxy-lua-script=file_name`
	Permitted Values
	Type	`file name`

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, the updated content is automatically used when a new connection is made.

--pid-file=file_name

Command-Line Format	`--pid-file=file_name`
Option-File Format	`pid-file=file_name`
	Permitted Values
	Type	`file name`

The name of the file in which to store the process ID.

--user=user_name

Command-Line Format	`--user=user_name`
Option-File Format	`user=user_name`
	Permitted Values
	Type	`string`

Run mysql-proxy as the specified user.

--version, -V

Command-Line Format	`--version`
	`-V`

Show the version number.

The most common usage is as a simple proxy service (that is, without additional 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, this will be passed through natively without alteration by mysql-proxy, so you must also specify the required authentication information:

shell> mysql --host=localhost --port=4040
        \   --user=user_name --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-backend-addresses 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 15.7.5, "Using MySQL Proxy".