← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/configuration/variables.rst

  • Committer: Mark Atwood
  • Date: 2011-12-15 23:13:18 UTC
  • mfrom: (2465.3.1 rf3)
  • Revision ID: me@mark.atwood.name-20111215231318-mt2y2q4s5ydp79q3
merge lp:~olafvdspek/drizzle/refactor14

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/configuration/variables.rst
 
1
.. program:: drizzled
 
2
 
 
3
.. _configuration_variables:
 
4
 
 
5
Variables
 
6
=========
 
7
 
 
8
Variables reflect the running configuration of Drizzle.
 
9
Variables allow you to configure (or reconfigure) certain values at runtime,
 
10
whereas :ref:`configuration_options` configure Drizzle at startup and cannot
 
11
be changed without restarting Drizzle.
 
12
 
 
13
To see which variables are avaiable, execute the following:
 
14
 
 
15
.. code-block:: mysql
 
16
 
 
17
   drizzle> SELECT * FROM DATA_DICTIONARY.GLOBAL_VARIABLES;
 
18
   +--------------------------------------------+--------------------+
 
19
   | Variable_name                              | Value              |
 
20
   +--------------------------------------------+--------------------+
 
21
   | auto_increment_increment                   | 1                  | 
 
22
   | auto_increment_offset                      | 1                  | 
 
23
   | autocommit                                 | ON                 | 
 
24
   | back_log                                   | 128                | 
 
25
   | basedir                                    | /opt/drizzle       |
 
26
   | bulk_insert_buffer_size                    | 8388608            | 
 
27
   | collation_server                           | utf8_general_ci    | 
 
28
   | completion_type                            | 0                  | 
 
29
   | datadir                                    | /opt/drizzle/data  |
 
30
   | div_precision_increment                    | 4                  | 
 
31
   | drizzle_protocol_bind_address              | localhost          | 
 
32
   | drizzle_protocol_buffer_length             | 16384              | 
 
33
   | drizzle_protocol_connect_timeout           | 10                 | 
 
34
   | drizzle_protocol_max_connections           | 1000               | 
 
35
   | drizzle_protocol_port                      | 290132299          | 
 
36
   | drizzle_protocol_read_timeout              | 30                 | 
 
37
   | drizzle_protocol_retry_count               | 10                 | 
 
38
   | drizzle_protocol_write_timeout             | 60                 | 
 
39
   | error_count                                | 0                  | 
 
40
   | foreign_key_checks                         | ON                 | 
 
41
   ...
 
42
 
 
43
The ``DATA_DICTIONARY.GLOBAL_VARIABLES`` and
 
44
``DATA_DICTIONARY.SESION_VARIABLES`` views only list the available variables
 
45
and their current values, but internally each variable has four attributes
 
46
which affect how, if, and when it can be set:
 
47
 
 
48
#. Creator
 
49
#. Option
 
50
#. Dynamic
 
51
#. Scope
 
52
 
 
53
Variable are created either by the Drizzle kernel or by a plugin.
 
54
Varaibles created by a plugin are prefixed with the plugin's name.
 
55
For example, ``drizzle_protocol_port`` is created by the
 
56
:doc:`/plugins/drizzle_protocol/index` plugin.  Else, the variable
 
57
is created by the Drizzle kernel.
 
58
 
 
59
Most variables have a corresponding
 
60
:ref:`command line option <command_line_options>` which
 
61
initializes the variable.  For example, :option:`--drizzle-protocol.port`
 
62
initializes ``drizzle_protocol_port``.  Command line options are
 
63
converted to variable names by stripping
 
64
the option's leading ``--`` and changing all ``-`` (hyphens) and ``.`` 
 
65
(periods) to ``_`` (underscores).  Variables without corresponding
 
66
command line options are are usually switches (to enable or disable
 
67
some feature) or counters (like ``error_count``), and these variables can
 
68
only be accessed or changed once Drizzle is running.
 
69
 
 
70
Dynamic variables can be changed at runtime, and the new value takes
 
71
affect immediately.  Documentation for each variables indicates if it is
 
72
dynamic or not.  Most variables, however, are static which means that
 
73
they only reflect the value of their corresponding option.  To change a static
 
74
variable, you must change its corresponding option, then restart Drizzle.
 
75
Certain variables are static and do not have a corresponding option because
 
76
they are purely informational, like ``version`` and ``version_comment``.
 
77
 
 
78
A variable's scope is either global, session, or both (global and session).
 
79
Global variables apply to all connections (each connection is a session).
 
80
Session variables apply to each connection and changes to a session in one
 
81
connection do not change or affect the same variable in another connection.
 
82
Changes to session variables are lost when the connection closes, but
 
83
changes to global variables remain in affect until changed again.
 
84
 
 
85
.. note::
 
86
 
 
87
   Configuration variables and :ref:`user_defined_variables` are
 
88
   different.  :ref:`user_defined_variables` do not affect the
 
89
   configuration of Drizzle, and they are always dynamic, session
 
90
   variables.
 
91
 
 
92
.. _setting_variables:
 
93
 
 
94
Setting Variables
 
95
-----------------
 
96
 
 
97
The ``SET`` command sets global and session variables:
 
98
 
 
99
.. code-block:: mysql
 
100
 
 
101
   -- Set global variable
 
102
   SET GLOBAL variable=value;
 
103
 
 
104
   -- Set sesion variable
 
105
   SET variable=value
 
106
   SET SESSION variable=value
 
107
 
 
108
If setting the variable succeeds, the command finishes silently like:
 
109
 
 
110
.. code-block:: mysql
 
111
 
 
112
   drizzle> SET SESSION max_allowed_packet=10485760;
 
113
   Query OK, 0 rows affected (0.001475 sec)
 
114
 
 
115
Else, an error occurs if the variable cannot be changed:
 
116
 
 
117
.. code-block:: mysql
 
118
 
 
119
   drizzle> SET tmpdir="/tmp";
 
120
   ERROR 1238 (HY000): Variable 'tmpdir' is a read only variable
 
121
 
 
122
.. _querying_variables:
 
123
 
 
124
Querying Variables
 
125
------------------
 
126
 
 
127
The ``DATA_DICTIONARY.GLOBAL_VARIABLES`` and
 
128
``DATA_DICTIONARY.SESSION_VARIABLES`` are views for querying 
 
129
global and session variables respectively.  For example, to see all
 
130
variables for the :doc:`/plugins/syslog/index` plugin:
 
131
 
 
132
.. code-block:: mysql
 
133
 
 
134
   drizzle> SELECT * FROM DATA_DICTIONARY.GLOBAL_VARIABLES WHERE VARIABLE_NAME LIKE 'syslog_%';
 
135
   +----------------------------------------+----------------+
 
136
   | VARIABLE_NAME                          | VARIABLE_VALUE |
 
137
   +----------------------------------------+----------------+
 
138
   | syslog_errmsg_enable                   | OFF            | 
 
139
   | syslog_errmsg_priority                 | warning        | 
 
140
   | syslog_facility                        | local0         | 
 
141
   | syslog_logging_enable                  | OFF            | 
 
142
   | syslog_logging_priority                | warning        | 
 
143
   | syslog_logging_threshold_big_examined  | 0              | 
 
144
   | syslog_logging_threshold_big_resultset | 0              | 
 
145
   | syslog_logging_threshold_slow          | 0              | 
 
146
   +----------------------------------------+----------------+
 
147