Skip navigation links
15.7.4 MySQL Proxy Scripting »
Section Navigation      [Toggle]

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

FormatOption FileDescription
--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 Admin Options

FormatOption FileDescription
--admin-address=host:portadmin-address=host:portThe admin module listening host and port
--admin-lua-script=file_nameadmin-lua-script=file_nameScript to execute by the admin module
--admin-password=passwordadmin-password=passwordAuthentication password for admin module
--admin-username=user_nameadmin-username=user_nameAuthentication user name for admin module
--proxy-address=host:portproxy-address=host:portThe listening proxy server host and port

Table 15.6. mysql-proxy Proxy Options

FormatOption FileDescriptionRemoved
--no-proxyno-proxyDo not start the proxy module 
--proxy-backend-addresses=host:portproxy-backend-addresses=host:portThe MySQL server host and port 
--proxy-fix-bug-25371proxy-fix-bug-25371Enable the fix for Bug #25371 for older libmysql versions0.8.1
--proxy-lua-script=file_nameproxy-lua-script=file_nameFilename for Lua script for proxy operations 
--proxy-pool-no-change-userproxy-pool-no-change-userDo not use the protocol CHANGE_USER command to reset the connection when coming from the connection pool 
--proxy-read-only-backend-addresses=host:portproxy-read-only-backend-addresses=host:portThe MySQL server host and port (read only) 
--proxy-skip-profilingproxy-skip-profilingDisable query profiling 

Table 15.7. mysql-proxy Applications Options

FormatOption FileDescription
--basedir=dir_namebasedir=dir_nameThe base directory prefix for paths in the configuration
--daemondaemonStart in daemon mode
--defaults-file=file_name The configuration file to use
--event-threads=countevent-threads=countThe number of event-handling threads
--keepalivekeepaliveTry to restart the proxy if a crash occurs
--log-backtrace-on-crashlog-backtrace-on-crashTry to invoke the debugger and generate a backtrace on crash
--log-file=file_namelog-file=file_nameThe file where error messages are logged
--log-level=levellog-level=levelThe logging level
--log-use-sysloglog-use-syslogLog errors to syslog
--lua-cpath=dir_namelua-cpath=dir_nameSet the LUA_CPATH
--lua-path=dir_namelua-path=dir_nameSet the LUA_PATH
--max-open-files=countmax-open-files=countThe maximum number of open files to support
--pid-file=file_namepid-file=file_nameFile in which to store the process ID
--plugin-dir=dir_nameplugin-dir=dir_nameDirectory containing plugin files
--plugins=plugin,...plugins=plugin,...List of plugins to load
--user=user_nameuser=user_nameThe 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.log
log-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 Formatadmin-address=host:port
     Permitted Values
    Typestring
    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 Formatadmin-lua-script=file_name
     Permitted Values
    Typefile name
    Default

    The script to use for the proxy administration module.

  • --admin-password=password

    Command-Line Format--admin-password=password
    Option-File Formatadmin-password=password
     Permitted Values
    Typestring
    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 Formatadmin-username=user_name
     Permitted Values
    Typestring
    Defaultroot

    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 Formatbasedir=dir_name
     Permitted Values
    Typedirectory 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 Formatdaemon

    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 Formatevent-threads=count
     Permitted Values
    Typenumeric
    Default1

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

  • --keepalive

    Command-Line Format--keepalive
    Option-File Formatkeepalive

    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 Formatlog-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 Formatlog-file=file_name
     Permitted Values
    Typefile 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 Formatlog-level=level
     Permitted Values
    Typeenumeration
    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 Formatlog-use-syslog

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

  • --lua-cpath=dir_name

    Command-Line Format--lua-cpath=dir_name
    Option-File Formatlua-cpath=dir_name
     Permitted Values
    Typedirectory 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 Formatlua-path=dir_name
     Permitted Values
    Typedirectory name

    The LUA_CPATH to use when loading modules for Lua.

  • --max-open-files=count

    Command-Line Format--max-open-files=count
    Option-File Formatmax-open-files=count
     Permitted Values
    Typenumeric

    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 Formatno-proxy

    Disable the proxy module.

  • --plugin-dir=dir_name

    Command-Line Format--plugin-dir=dir_name
    Option-File Formatplugin-dir=dir_name
     Permitted Values
    Typedirectory name

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

  • --plugins=plugin

    Command-Line Format--plugins=plugin,...
    Option-File Formatplugins=plugin,...
     Permitted Values
    Typestring

    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 Formatproxy-address=host:port
     Permitted Values
    Typestring
    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 Formatproxy-read-only-backend-addresses=host:port
     Permitted Values
    Typestring

    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 Formatproxy-backend-addresses=host:port
     Permitted Values
    Typestring
    Default127.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 Formatproxy-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 Formatproxy-skip-profiling

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

  • --proxy-fix-bug-25371

    Version Removed0.8.1
    Command-Line Format--proxy-fix-bug-25371
    Option-File Formatproxy-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 Formatproxy-lua-script=file_name
     Permitted Values
    Typefile 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 Formatpid-file=file_name
     Permitted Values
    Typefile name

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

  • --user=user_name

    Command-Line Format--user=user_name
    Option-File Formatuser=user_name
     Permitted Values
    Typestring

    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”.

Copyright © 1997, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices