Class: Mysql

Inherits:
Object
  • Object
show all
Defined in:
lib/mysql.rb,
lib/mysql/stmt.rb,
lib/mysql/error.rb,
lib/mysql/field.rb,
lib/mysql/packet.rb,
lib/mysql/result.rb,
lib/mysql/charset.rb,
lib/mysql/protocol.rb,
lib/mysql/constants.rb,
lib/mysql/authenticator.rb,
lib/mysql/authenticator/sha256_password.rb,
lib/mysql/authenticator/caching_sha2_password.rb,
lib/mysql/authenticator/mysql_native_password.rb

Overview

Copyright © 2003 TOMITA Masahiro [email protected]

Defined Under Namespace

Classes: Authenticator, Charset, ClientError, Error, Field, Packet, Protocol, ProtocolError, RawRecord, Result, ResultBase, ServerError, Stmt, StmtRawRecord

Constant Summary collapse

VERSION =

Version number of this library

-'4.1.0'             # Version number of this library
MYSQL_UNIX_PORT =

UNIX domain socket filename

-"/tmp/mysql.sock"   # UNIX domain socket filename
MYSQL_TCP_PORT =

TCP socket port number

3306
DEFAULT_OPTS = 
{
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze
COM_SLEEP =

Command

0
COM_QUIT = 
1
COM_INIT_DB = 
2
COM_QUERY = 
3
COM_FIELD_LIST = 
4
COM_CREATE_DB = 
5
COM_DROP_DB = 
6
COM_REFRESH = 
7
COM_SHUTDOWN = 
8
COM_STATISTICS = 
9
COM_PROCESS_INFO = 
10
COM_CONNECT = 
11
COM_PROCESS_KILL = 
12
COM_DEBUG = 
13
COM_PING = 
14
COM_TIME = 
15
COM_DELAYED_INSERT = 
16
COM_CHANGE_USER = 
17
COM_BINLOG_DUMP = 
18
COM_TABLE_DUMP = 
19
COM_CONNECT_OUT = 
20
COM_REGISTER_SLAVE = 
21
COM_STMT_PREPARE = 
22
COM_STMT_EXECUTE = 
23
COM_STMT_SEND_LONG_DATA = 
24
COM_STMT_CLOSE = 
25
COM_STMT_RESET = 
26
COM_SET_OPTION = 
27
COM_STMT_FETCH = 
28
COM_DAEMON = 
29
COM_BINLOG_DUMP_GTID = 
30
COM_RESET_CONNECTION = 
31
COM_CLONE = 
32
CLIENT_LONG_PASSWORD =

Client flag

1
CLIENT_FOUND_ROWS =

new more secure passwords

1 << 1
CLIENT_LONG_FLAG =

Found instead of affected rows

1 << 2
CLIENT_CONNECT_WITH_DB =

Get all column flags

1 << 3
CLIENT_NO_SCHEMA =

One can specify db on connect

1 << 4
CLIENT_COMPRESS =

Don’t allow database.table.column

1 << 5
CLIENT_ODBC =

Can use compression protocol

1 << 6
CLIENT_LOCAL_FILES =

Odbc client

1 << 7
CLIENT_IGNORE_SPACE =

Can use LOAD DATA LOCAL

1 << 8
CLIENT_PROTOCOL_41 =

Ignore spaces before ‘(’

1 << 9
CLIENT_INTERACTIVE =

New 4.1 protocol

1 << 10
CLIENT_SSL =

This is an interactive client

1 << 11
CLIENT_IGNORE_SIGPIPE =

Switch to SSL after handshake

1 << 12
CLIENT_TRANSACTIONS =

IGNORE sigpipes

1 << 13
CLIENT_RESERVED =

Client knows about transactions

1 << 14
CLIENT_SECURE_CONNECTION =

Old flag for 4.1 protocol

1 << 15
CLIENT_MULTI_STATEMENTS =

New 4.1 authentication

1 << 16
CLIENT_MULTI_RESULTS =

Enable/disable multi-stmt support

1 << 17
CLIENT_PS_MULTI_RESULTS =

Enable/disable multi-results

1 << 18
CLIENT_PLUGIN_AUTH =

Multi-results in PS-protocol

1 << 19
CLIENT_CONNECT_ATTRS =

Client supports plugin authentication

1 << 20
CLIENT_PLUGIN_AUTH_LENENC_CLIENT_DATA =

Client supports connection attribute

1 << 21
CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS =

Enable authentication response packet to be larger than 255 bytes.

1 << 22
CLIENT_SESSION_TRACK =

Don’t close the connection for a connection with expired password.

1 << 23
CLIENT_DEPRECATE_EOF =

Capable of handling server state change information. Its a hint to the server to include the state change information in Ok packet.

1 << 24
CLIENT_OPTIONAL_RESULTSET_METADATA =

Client no longer needs EOF packet

1 << 25
CLIENT_ZSTD_COMPRESSION_ALGORITHM =

The client can handle optional metadata information in the resultset.

1 << 26
CLIENT_CAPABILITY_EXTENSION =

Compression protocol extended to support zstd compression method

1 << 29
CLIENT_SSL_VERIFY_SERVER_CERT =

This flag will be reserved to extend the 32bit capabilities structure to 64bits.

1 << 30
CLIENT_REMEMBER_OPTIONS =

Verify server certificate.

1 << 31
OPT_CONNECT_TIMEOUT =

Connection Option

0
OPT_COMPRESS = 
1
OPT_NAMED_PIPE = 
2
INIT_COMMAND = 
3
READ_DEFAULT_FILE = 
4
READ_DEFAULT_GROUP = 
5
SET_CHARSET_DIR = 
6
SET_CHARSET_NAME = 
7
OPT_LOCAL_INFILE = 
8
OPT_PROTOCOL = 
9
SHARED_MEMORY_BASE_NAME = 
10
OPT_READ_TIMEOUT = 
11
OPT_WRITE_TIMEOUT = 
12
OPT_USE_RESULT = 
13
REPORT_DATA_TRUNCATION = 
14
OPT_RECONNECT = 
15
PLUGIN_DIR = 
16
DEFAULT_AUTH = 
17
OPT_BIND = 
18
OPT_SSL_KEY = 
19
OPT_SSL_CERT = 
20
OPT_SSL_CA = 
21
OPT_SSL_CAPATH = 
22
OPT_SSL_CIPHER = 
23
OPT_SSL_CRL = 
24
OPT_SSL_CRLPATH = 
25
OPT_CONNECT_ATTR_RESET = 
26
OPT_CONNECT_ATTR_ADD = 
27
OPT_CONNECT_ATTR_DELETE = 
28
SERVER_PUBLIC_KEY = 
29
ENABLE_CLEARTEXT_PLUGIN = 
30
OPT_CAN_HANDLE_EXPIRED_PASSWORDS = 
31
OPT_MAX_ALLOWED_PACKET = 
32
OPT_NET_BUFFER_LENGTH = 
33
OPT_TLS_VERSION = 
34
OPT_SSL_MODE = 
35
OPT_GET_SERVER_PUBLIC_KEY = 
36
OPT_RETRY_COUNT = 
37
OPT_OPTIONAL_RESULTSET_METADATA = 
38
OPT_SSL_FIPS_MODE = 
39
OPT_TLS_CIPHERSUITES = 
40
OPT_COMPRESSION_ALGORITHMS = 
41
OPT_ZSTD_COMPRESSION_LEVEL = 
42
OPT_LOAD_DATA_LOCAL_DIR = 
43
SSL_MODE_DISABLED =

SSL Mode

1
SSL_MODE_PREFERRED = 
2
SSL_MODE_REQUIRED = 
3
SSL_MODE_VERIFY_CA = 
4
SSL_MODE_VERIFY_IDENTITY = 
5
OPTION_MULTI_STATEMENTS_ON =

Server Option

0
OPTION_MULTI_STATEMENTS_OFF = 
1
SERVER_STATUS_IN_TRANS =

Server Status

1
SERVER_STATUS_AUTOCOMMIT = 
1 << 1
SERVER_MORE_RESULTS_EXISTS = 
1 << 3
SERVER_QUERY_NO_GOOD_INDEX_USED = 
1 << 4
SERVER_QUERY_NO_INDEX_USED = 
1 << 5
SERVER_STATUS_CURSOR_EXISTS = 
1 << 6
SERVER_STATUS_LAST_ROW_SENT = 
1 << 7
SERVER_STATUS_DB_DROPPED = 
1 << 8
SERVER_STATUS_NO_BACKSLASH_ESCAPES = 
1 << 9
SERVER_STATUS_METADATA_CHANGED = 
1 << 10
SERVER_QUERY_WAS_SLOW = 
1 << 11
SERVER_PS_OUT_PARAMS = 
1 << 12
SERVER_STATUS_IN_TRANS_READONLY = 
1 << 13
SERVER_SESSION_STATE_CHANGED = 
1 << 14
REFRESH_GRANT =

Refresh parameter

1
REFRESH_LOG = 
1 << 1
REFRESH_TABLES = 
1 << 2
REFRESH_HOSTS = 
1 << 3
REFRESH_STATUS = 
1 << 4
REFRESH_THREADS = 
1 << 5
REFRESH_SLAVE = 
1 << 6
REFRESH_MASTER = 
1 << 7
REFRESH_ERROR_LOG = 
1 << 8
REFRESH_ENGINE_LOG = 
1 << 9
REFRESH_BINARY_LOG = 
1 << 10
REFRESH_RELAY_LOG = 
1 << 11
REFRESH_GENERAL_LOG = 
1 << 12
REFRESH_SLOW_LOG = 
1 << 13
REFRESH_READ_LOCK = 
1 << 14
REFRESH_FAST = 
1 << 15
REFRESH_QUERY_CACHE = 
1 << 16
REFRESH_QUERY_CACHE_FREE = 
1 << 17
REFRESH_DES_KEY_FILE = 
1 << 18
REFRESH_USER_RESOURCES = 
1 << 19
REFRESH_FOR_EXPORT = 
1 << 20
REFRESH_OPTIMIZER_COSTS = 
1 << 21
REFRESH_PERSIST = 
1 << 22
SESSION_TRACK_SYSTEM_VARIABLES =

Session system variables

0
SESSION_TRACK_SCHEMA =

Current schema

1
SESSION_TRACK_STATE_CHANGE =

track session state changes

2
SESSION_TRACK_GTIDS =

See also: session_track_gtids

3
SESSION_TRACK_TRANSACTION_CHARACTERISTICS =

Transaction chistics

4
SESSION_TRACK_TRANSACTION_STATE =

Transaction state

5

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(uri, **opts) ⇒ Mysql #initialize(host, username, password, database, port, socket, flags, **opts) ⇒ Mysql #initialize(host: nil, username: nil, password: nil, database: nil, port: nil, socket: nil, flags: nil, **opts) ⇒ Mysql

Returns a new instance of Mysql.

Overloads:

  • #initialize(uri, **opts) ⇒ Mysql

    Parameters:

    • uri (String, URI) —

      "mysql://username:password@host:port/database?param=value&..." / "mysql://username:password@%2Ftmp%2Fmysql.sock/database" / "mysql://username:password@/database?socket=/tmp/mysql.sock"

    • opts (Hash) —

      options

  • #initialize(host, username, password, database, port, socket, flags, **opts) ⇒ Mysql

    Parameters:

    • host (String) —

      hostname mysqld running

    • username (String) —

      username to connect to mysqld

    • password (String) —

      password to connect to mysqld

    • database (String) —

      initial database name

    • port (String) —

      port number (used if host is not 'localhost' or nil)

    • socket (String) —

      socket filename (used if host is 'localhost' or nil)

    • flags (Integer) —

      connection flag. Mysql::CLIENT_* ORed

    • opts (Hash) —

      options

  • #initialize(host: nil, username: nil, password: nil, database: nil, port: nil, socket: nil, flags: nil, **opts) ⇒ Mysql

    Parameters:

    • host (String) (defaults to: nil) —

      hostname mysqld running

    • username (String) (defaults to: nil) —

      username to connect to mysqld

    • password (String) (defaults to: nil) —

      password to connect to mysqld

    • database (String) (defaults to: nil) —

      initial database name

    • port (String) (defaults to: nil) —

      port number (used if host is not 'localhost' or nil)

    • socket (String) (defaults to: nil) —

      socket filename (used if host is 'localhost' or nil)

    • flags (Integer) (defaults to: nil) —

      connection flag. Mysql::CLIENT_* ORed

    • opts (Hash) —

      options

    Options Hash (**opts):

    • :host (String) —

      hostname mysqld running

    • :username (String) —

      username to connect to mysqld

    • :password (String) —

      password to connect to mysqld

    • :database (String) —

      initial database name

    • :port (String) —

      port number (used if host is not 'localhost' or nil)

    • :socket (String) —

      socket filename (used if host is 'localhost' or nil)

    • :flags (Integer) —

      connection flag. Mysql::CLIENT_* ORed

    • :charset (Mysql::Charset, String) —

      character set

    • :connect_timeout (Numeric, nil)
    • :read_timeout (Numeric, nil)
    • :write_timeout (Numeric, nil)
    • :local_infile (Boolean)
    • :load_data_local_dir (String)
    • :ssl_mode (Integer)
    • :ssl_context_params (Hash<Symbol, String>)
    • :get_server_public_key (Boolean)
    • :connect_attrs (Hash)
    • :io (BasicSocket, OpenSSL::SSL::SSLSocket) —

      Existing socket instance that will be used instead of creating a new socket



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/mysql.rb', line 179

def initialize(*args, **opts)
  @fields = nil
  @result = nil
  @protocol = nil
  @sqlstate = "00000"
  @host_info = nil
  @last_error = nil
  @opts = Mysql.default_options.dup
  parse_args(args, opts)
end

Instance Attribute Details

#auto_store_result ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#cast ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#connect_attrs ⇒ Hash

Returns:

  • (Hash) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#connect_timeout ⇒ Numeric?

Returns:

  • (Numeric, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#database ⇒ String?

Returns:

  • (String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#fields ⇒ Array<Mysql::Field> (readonly)

Returns fields of result set.

Returns:



106
107
108
 
# File 'lib/mysql.rb', line 106

def fields
  @fields
end

#flags ⇒ Integer?

Returns:

  • (Integer, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#get_server_public_key ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#host ⇒ String?

Returns:

  • (String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#init_command ⇒ String?

Returns:

  • (String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#io ⇒ [BasicSocket, OpenSSL::SSL::SSLSocket]?

Returns:

  • ([BasicSocket, OpenSSL::SSL::SSLSocket], nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#load_data_local_dir ⇒ String?

Returns:

  • (String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#local_infile ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#password ⇒ String?

Returns:

  • (String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#port ⇒ Integer, ...

Returns:

  • (Integer, String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#protocol ⇒ Object (readonly) 



103
104
105
 
# File 'lib/mysql.rb', line 103

def protocol
  @protocol
end

#read_timeout ⇒ Numeric?

Returns:

  • (Numeric, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#result ⇒ Mysql::Result (readonly)

Returns:



109
110
111
 
# File 'lib/mysql.rb', line 109

def result
  @result
end

#return_result ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#socket ⇒ String?

Returns socket filename.

Returns:

  • (String, nil) —

    socket filename



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#ssl_context_params ⇒ Hash

Returns See OpenSSL::SSL::Context#set_params.

Returns:

  • (Hash) —

    See OpenSSL::SSL::Context#set_params



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#ssl_mode ⇒ String, Integer

Returns 1 or “disabled” / 2 or “preferred” / 3 or “required”.

Returns:

  • (String, Integer) —

    1 or "disabled" / 2 or "preferred" / 3 or "required"



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#username ⇒ String?

Returns:

  • (String, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#with_table ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#write_timeout ⇒ Numeric?

Returns:

  • (Numeric, nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

#yield_null_result ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mysql.rb', line 75

DEFAULT_OPTS = {
  host: nil,
  username: nil,
  password: nil,
  database: nil,
  port: nil,
  socket: nil,
  flags: 0,
  io: nil,
  charset: nil,
  connect_timeout: nil,
  read_timeout: nil,
  write_timeout: nil,
  init_command: nil,
  local_infile: nil,
  load_data_local_dir: nil,
  ssl_mode: SSL_MODE_PREFERRED,
  ssl_context_params: {},
  get_server_public_key: false,
  connect_attrs: {},
  yield_null_result: true,
  return_result: true,
  with_table: false,
  auto_store_result: true,
  cast: true,
}.freeze

Class Method Details

.connect(*args, **opts) ⇒ Mysql

Make Mysql object and connect to mysqld. parameter is same as arguments for #initialize.

Returns:



115
116
117
 
# File 'lib/mysql.rb', line 115

def connect(*args, **opts)
  self.new(*args, **opts).connect
end

.default_options ⇒ Object 



135
136
137
 
# File 'lib/mysql.rb', line 135

def default_options
  @default_options ||= DEFAULT_OPTS.dup
end

.escape_string(str) ⇒ String

Escape special character in string.

Parameters:

  • str (String)

Returns:

  • (String) 


122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/mysql.rb', line 122

def escape_string(str)
  str.gsub(/[\0\n\r\\'"\x1a]/) do |s|
    case s
    when "\0" then "\\0"
    when "\n" then "\\n"
    when "\r" then "\\r"
    when "\x1a" then "\\Z"
    else "\\#{s}"
    end
  end
end

.quote ⇒ String

Escape special character in string.

Parameters:

  • str (String)

Returns:

  • (String) 


133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/mysql.rb', line 133

def escape_string(str)
  str.gsub(/[\0\n\r\\'"\x1a]/) do |s|
    case s
    when "\0" then "\\0"
    when "\n" then "\\n"
    when "\r" then "\\r"
    when "\x1a" then "\\Z"
    else "\\#{s}"
    end
  end
end

Instance Method Details

#affected_rows ⇒ Integer

Returns number of affected records by insert/update/delete.

Returns:

  • (Integer) —

    number of affected records by insert/update/delete.



344
345
346
 
# File 'lib/mysql.rb', line 344

def affected_rows
  @protocol ? @protocol.affected_rows : 0
end

#autocommit(flag) ⇒ Mysql

Set autocommit mode

Parameters:

  • flag (Boolean)

Returns:



523
524
525
526
 
# File 'lib/mysql.rb', line 523

def autocommit(flag)
  query "set autocommit=#{flag ? 1 : 0}"
  self
end

#character_set_name ⇒ String

Returns charset name.

Returns:

  • (String) —

    charset name



298
299
300
 
# File 'lib/mysql.rb', line 298

def character_set_name
  @protocol.charset.name
end

#charset ⇒ Mysql::Charset

Returns character set of MySQL connection.

Returns:



282
283
284
 
# File 'lib/mysql.rb', line 282

def charset
  @opts[:charset]
end

#charset=(cs) ⇒ Object

Set charset of MySQL connection.

Parameters:



288
289
290
291
292
293
294
295
 
# File 'lib/mysql.rb', line 288

def charset=(cs)
  charset = cs.is_a?(Charset) ? cs : Charset.by_name(cs)
  if @protocol
    @protocol.charset = charset
    query "SET NAMES #{charset.name}"
  end
  @opts[:charset] = charset
end

#close ⇒ Mysql

Disconnect from mysql.

Returns:



254
255
256
257
258
259
260
 
# File 'lib/mysql.rb', line 254

def close
  if @protocol
    @protocol.quit_command
    @protocol = nil
  end
  return self
end

#close! ⇒ Mysql

Disconnect from mysql without QUIT packet.

Returns:



264
265
266
267
268
269
270
 
# File 'lib/mysql.rb', line 264

def close!
  if @protocol
    @protocol.close
    @protocol = nil
  end
  return self
end

#commit ⇒ Mysql

Commit transaction

Returns:



508
509
510
511
 
# File 'lib/mysql.rb', line 508

def commit
  query 'commit'
  self
end

#connect(*args, **opts) ⇒ Mysql

Connect to mysqld. parameter is same as arguments for #initialize.

Returns:



193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/mysql.rb', line 193

def connect(*args, **opts)
  parse_args(args, opts)
  if @opts[:flags] & CLIENT_COMPRESS != 0
    warn 'unsupported flag: CLIENT_COMPRESS' if $VERBOSE
    @opts[:flags] &= ~CLIENT_COMPRESS
  end
  @protocol = Protocol.new(@opts)
  @protocol.authenticate
  @host_info = (@opts[:host].nil? || @opts[:host] == "localhost") ? 'Localhost via UNIX socket' : "#{@opts[:host]} via TCP/IP"
  query @opts[:init_command] if @opts[:init_command]
  return self
end

#errno ⇒ Integer

Returns last error number.

Returns:

  • (Integer) —

    last error number



303
304
305
 
# File 'lib/mysql.rb', line 303

def errno
  @last_error ? @last_error.errno : 0
end

#error ⇒ String

Returns last error message.

Returns:

  • (String) —

    last error message



308
309
310
 
# File 'lib/mysql.rb', line 308

def error
  @last_error&.error
end

#escape_string(str) ⇒ Object Also known as: quote

Escape special character in MySQL.

return [String]

Parameters:

  • str (String) 


276
277
278
 
# File 'lib/mysql.rb', line 276

def escape_string(str)
  self.class.escape_string str
end

#field_count ⇒ Integer

Returns number of columns for last query.

Returns:

  • (Integer) —

    number of columns for last query



318
319
320
 
# File 'lib/mysql.rb', line 318

def field_count
  @fields.size
end

#host_info ⇒ String

Returns connection type.

Returns:

  • (String) —

    connection type



323
324
325
 
# File 'lib/mysql.rb', line 323

def host_info
  @host_info
end

#info ⇒ String

Returns information for last query.

Returns:

  • (String) —

    information for last query



339
340
341
 
# File 'lib/mysql.rb', line 339

def info
  @protocol&.message
end

#insert_id ⇒ Integer

Returns latest auto_increment value.

Returns:

  • (Integer) —

    latest auto_increment value



349
350
351
 
# File 'lib/mysql.rb', line 349

def insert_id
  @protocol ? @protocol.insert_id : 0
end

#kill(pid) ⇒ Mysql

Kill query.

Parameters:

  • pid (Integer) —

    thread id

Returns:



361
362
363
364
365
 
# File 'lib/mysql.rb', line 361

def kill(pid)
  check_connection
  @protocol.kill_command pid
  self
end

#more_results? ⇒ Boolean

Returns true if multiple queries are specified and unexecuted queries exists.

Returns:

  • (Boolean) —

    true if multiple queries are specified and unexecuted queries exists.



428
429
430
 
# File 'lib/mysql.rb', line 428

def more_results?
  @protocol.more_results?
end

#next_result(**opts) ⇒ Mysql::Result, ...

execute next query if multiple queries are specified.

Returns:

  • (Mysql::Result) —

    result set of query if return_result is true.

  • (true) —

    if return_result is false and result exists.

  • (nil) —

    query returns no results.



436
437
438
439
440
441
442
443
 
# File 'lib/mysql.rb', line 436

def next_result(**opts)
  return nil unless more_results?
  opts = @opts.merge(opts)
  @protocol.get_result
  @fields = nil
  return store_result(**opts) if opts[:return_result]
  true
end

#parse_args(args, opts) ⇒ Object 



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/mysql.rb', line 206

def parse_args(args, opts)
  unless args.empty?
    case args[0]
    when URI
      uri = args[0]
    when /\Amysql:\/\//
      uri = URI.parse(args[0])
    when String, nil
      @opts[:host], user, passwd, dbname, port, socket, flags = *args
      @opts[:username] = user if user
      @opts[:password] = passwd if passwd
      @opts[:database] = dbname if dbname
      @opts[:port] = port if port
      @opts[:socket] = socket if socket
      @opts[:flags] = flags if flags
    when Hash
      # skip
    end
  end
  if uri
    host = uri.hostname.to_s
    host = URI.decode_www_form_component(host)
    if host.start_with?('/')
      @opts[:socket] = host
      host = ''
    end
    @opts[:host] = host
    @opts[:username] = URI.decode_www_form_component(uri.user.to_s)
    @opts[:password] = URI.decode_www_form_component(uri.password.to_s)
    @opts[:database] = uri.path.sub(/\A\/+/, '')
    @opts[:port] = uri.port
    opts = URI.decode_www_form(uri.query).to_h.transform_keys(&:intern).merge(opts) if uri.query
    opts[:flags] = opts[:flags].to_i if opts[:flags]
  end
  if args.last.kind_of? Hash
    opts = opts.merge(args.last)
  end
  @opts.update(opts)
end

#ping ⇒ Mysql

Check whether the connection is available.

Returns:



465
466
467
468
469
 
# File 'lib/mysql.rb', line 465

def ping
  check_connection
  @protocol.ping_command
  self
end

#prepare(str, **opts) ⇒ Mysql::Stmt

Parse prepared-statement.

Parameters:

  • str (String) —

    query string

Returns:



448
449
450
451
452
453
 
# File 'lib/mysql.rb', line 448

def prepare(str, **opts)
  opts = @opts.merge(opts)
  st = Stmt.new(@protocol, **opts)
  st.prepare str
  st
end

#query(str, **opts, &block) ⇒ Mysql::Result, ...

Execute query string.

Examples:

my.query("select 1,NULL,'abc'").fetch  # => [1, nil, "abc"]
my.query("select 1,NULL,'abc'"){|res| res.fetch}

Parameters:

  • str (String) —

    Query.

  • return_result (Boolean)
  • yield_null_result (Boolean)

Returns:

  • (Mysql::Result) —

    if return_result is true and the query returns result set.

  • (nil) —

    if return_result is true and the query does not return result set.

  • (self) —

    if return_result is false or block is specified.



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/mysql.rb', line 377

def query(str, **opts, &block)
  opts = @opts.merge(opts)
  check_connection
  @fields = nil
  begin
    @protocol.query_command str
    if block
      while true
        @protocol.get_result
        res = store_result(**opts)
        block.call res if res || opts[:yield_null_result]
        break unless more_results?
      end
      return self
    end
    @protocol.get_result
    return self unless opts[:return_result]
    return store_result(**opts)
  rescue ServerError => e
    @last_error = e
    @sqlstate = e.sqlstate
    raise
  end
end

#refresh(op) ⇒ Mysql

Flush tables or caches.

Parameters:

  • op (Integer) —

    operation. Use Mysql::REFRESH_* value.

Returns:



474
475
476
477
478
 
# File 'lib/mysql.rb', line 474

def refresh(op)
  check_connection
  @protocol.refresh_command op
  self
end

#reload ⇒ Mysql

Reload grant tables.

Returns:



482
483
484
 
# File 'lib/mysql.rb', line 482

def reload
  refresh Mysql::REFRESH_GRANT
end

#rollback ⇒ Mysql

Rollback transaction

Returns:



515
516
517
518
 
# File 'lib/mysql.rb', line 515

def rollback
  query 'rollback'
  self
end

#select_db(db) ⇒ Mysql

Select default database

Returns:



488
489
490
491
 
# File 'lib/mysql.rb', line 488

def select_db(db)
  query "use #{db}"
  self
end

#server_info ⇒ String

Returns server version.

Returns:

  • (String) —

    server version



328
329
330
331
 
# File 'lib/mysql.rb', line 328

def server_info
  check_connection
  @protocol.server_info
end

#server_version ⇒ Integer

Returns server version.

Returns:

  • (Integer) —

    server version



334
335
336
 
# File 'lib/mysql.rb', line 334

def server_version
  @protocol&.server_version
end

#session_track ⇒ Hash

session track

Returns:

  • (Hash) 


530
531
532
 
# File 'lib/mysql.rb', line 530

def session_track
  @protocol.session_track
end

#set_server_option(opt) ⇒ Mysql

Set server option.

Parameters:

Returns:



421
422
423
424
425
 
# File 'lib/mysql.rb', line 421

def set_server_option(opt)
  check_connection
  @protocol.set_option_command opt
  self
end

#shutdown(level = 0) ⇒ Mysql

shutdown server.

Returns:



495
496
497
498
499
 
# File 'lib/mysql.rb', line 495

def shutdown(level=0)
  check_connection
  @protocol.shutdown_command level
  self
end

#sqlstate ⇒ String

Returns sqlstate for last error.

Returns:

  • (String) —

    sqlstate for last error



313
314
315
 
# File 'lib/mysql.rb', line 313

def sqlstate
  @last_error ? @last_error.sqlstate : "00000"
end

#stat ⇒ String

Returns statistics message.

Returns:

  • (String) —

    statistics message



502
503
504
 
# File 'lib/mysql.rb', line 502

def stat
  @protocol ? @protocol.statistics_command : 'MySQL server has gone away'
end

#stmt(**opts) ⇒ Mysql::Stmt

Make empty prepared-statement object.

Returns:



458
459
460
461
 
# File 'lib/mysql.rb', line 458

def stmt(**opts)
  opts = @opts.merge(opts)
  Stmt.new(@protocol, **opts)
end

#store_result(**opts) ⇒ Mysql::Result?

Get all data for last query.

Returns:



405
406
407
408
409
410
 
# File 'lib/mysql.rb', line 405

def store_result(**opts)
  return nil if @protocol.field_count.nil? || @protocol.field_count == 0
  @fields = @protocol.retr_fields
  opts = @opts.merge(opts)
  @result = Result.new(@fields, @protocol, **opts)
end

#thread_id ⇒ Integer

Returns Thread ID.

Returns:

  • (Integer) —

    Thread ID



413
414
415
416
 
# File 'lib/mysql.rb', line 413

def thread_id
  check_connection
  @protocol.thread_id
end

#warning_count ⇒ Integer

Returns number of warnings for previous query.

Returns:

  • (Integer) —

    number of warnings for previous query



354
355
356
 
# File 'lib/mysql.rb', line 354

def warning_count
  @protocol ? @protocol.warning_count : 0
end