PC World 2002 July & August/PCWorld_2002-07-08_cd.bin/Komunik/MySQL/mysqlgui/MySQL.help

Text File | 2001-09-08 | 18KB | 437 lines

                                                     MySQLGUI client

Introduction


This is the help file for mysqlgui, the MySQL graphical client. This
client is designed to run on all contemporary GUI-enabled operating
systems, including all Unix and Windows variants. Availability of this
client on Macintosh platforms (with Mac OS) depends on the availability
of the egcs/gnu compilers and on the fltk library being ported to Mac OS,
an effort which is in the works.  This client is designed to cover basic
functionality for SQL client, including the following functions:

   - Connecting to and disconnecting from the MySQL server
   - Setting / saving options for connecting to the MYSQL server
     and for the overall functionality of the client
   - Using the standard scheme for setting options with MySQL,
     that can be shared by other MySQL compliant applications
   - Selecting a database for operations, by clicking or from an option
     file
   - Remembering the last database used for immediate loading upon
     client startup
   - Saving and remembering the client's window position
   - Choice of presenting query results to the screen, to a text file,
     or just displaying a count of rows
   - Remembering positions of other windows during run time
   - Maintaining a history of all successful queries issued during a
     session, ready    for re-use, in an intuitive manner
   - Loading and saving history of queries in MySQL standard
     fashion, that can be shared by other MySQL monitor, including
     immediate execution of queries in browser widget. This also includes
     automatic maintenance of query histories on a per-database basis
   - This help file
   - Command editor of high quality, with word-wrap, undo, cut/paste
     and more
   - Executing queries and providing full error and information reporting
     or giving the number of rows returned
   - Providing saving query output to a compliant with mysqlimport and
     LOAD DATA commands
   - Providing full graphical query result browser with many nice
     features, including versatile navigation, sorting on multiple
     columns, saving to text file, changing column widths, row heights,
     etc.
   - Automatic generation of join queries, which are optimized for
     speed, based on client's chosing a sequence of tables in 1 to N
     relationship
   - 3D database / table /column view with easy expanding / imploding
     views of entities, and automatic placement of chosen entry to
     edit widget
   - Automatic insertion of all available MySQL commands, operators
     and functions in a hierarchical manner
   - Generating a menu with table fields based on tables that the user
     has chosen
   - Parametrized queries, where the user can put any number of  ?var?
     strings and getting a dialog with all vars specified, so that
     inputed values replace ?var?'s before execution
   - Showing indexes of the chosen table
   - Defining a hierarchy of queries, based on any classifications that
     user finds suitable. Below defined directory, a tree of sub-dirs
     are converted to suitable hierarchical menus on the main
     window. For that purpose saving of queries and making of
     directories is enabled from the client
   - Server and client information is displayed in the About window
   - An advanced file dialog is provided with various searching and
     filtering options and create / append options for saving files
   - Optional limit slider is provided in order to enable users to
     automatically limit query output to certain number of rows
   - Automatic sending query results to screen, file or number of rows
     irrespective of the current settings of  radio buttons
   - Output widget at the bottom of the main window for the display of
     the last message or error
   - Left of it is a cross button which, when hold, displays a window
     with history of   messages and erros
   - Administrative panel with all administrative functions, which are
     available from main menu too. This panel also displays some of
     the most necessary status info, which are updated automatically,
     without user intervention at the frequency defined in options
     This panel also contains exact server time, and output widget and
     cross button for displaying of the history of administrative
     errors and messages only
   - Database drop and create dialogs
   - Refresh function
   - Shutdown function
   - Ping function
   - Several flush dialogs
   - Display of the current server variables
   - Status window with automatic updating with manual override
     - An option to send query results to a full fledged text editor,
     instead to a spreadsheat widget. This can be usefull for searching,
     cuting, copying etc.
     - As from version 1.7, mysqlgui can accomodate result sets / table of any
     size, limited by MySQL server, operating and file system only. This is
     enabled with `memory save' option. However , if result set is large,
     this option is enabled automatically by mysqlgui. In that mode,
     mysqlgui can accomodate result sets of any size, while waisting
     relatively modest amount of virtual memory.  As  mysqlgui can open many
     windows, dialogues and spreadsheets, so user can view simultaneously as
     many result sets as necessary.
     - Process dialogue which enables sorting of processes by any of the
     attributes by simple clicking on column header. First click sorts
     processes in descending and second in ascending order. Third click
     reverts to unsorted sequencing. As from version 1.7, if mysqlgui
     detects server version 3.23.07 or above, full processlist is run, to
     enable viewing of entire query


Options

     MySQLGUI client follows closely MySQL standards regarding setting
up and reading options. It will read options from both global files (
on Unix it is /etc/my.cnf and on Windows c:\my.cnf) and local files
(.my.cnf).

     When fired up, MySQLGUI client reads all options pertaining to
client, found under [client] group. Thus, data on user, host, port,
password etc are read and honored. Beside those data, MySQLGUI client
reads it's own config data, found under [client_fltk} group. It should
be noted that this client will read password data (if found) and will
try to log on the server with this user/password combination. The
authors of this client would like to stress out that it is not wise to
put password data in a text file.

     As an example, this is how typical config file looks like:
--------------------------------------------------------------------
# mysql config file.
# You can copy this to one of:
# @sysconfdir@/my.cnf to set global options,
# mysql-data-dir/my.cnf to set server-specific options (in this
# installation this directory is @localstatedir@) or
# ~/.my.cnf to set user-specific options.
#
# One can use all long options that the program supports.
# Run the program with --help to get a list of available options

# This will be passed to all mysql clients
[client]
port        = 3306
host    = localhost
user    = Sinisa


# This will be passed to MySQLGUI GUI client only
[client_fltk]
help_file=~/guiclient/MySQL.help
client_file=~/.ee/MySQL.options
queries_file=~/.mysql/.mysql_history
history_length=100
database=telcent
--------------------------------------------------------------------

     Options pertaining to this client only deserve explanation.

     "help_file" indicates a location of the help file, which is
distributed with client. It is wise to put it in the directory
accessible for browsing and reading to all. This option should contain
the entire path of this file, which enables the user of changing its
name, for whatever the purpose. This client also supports, as it can
be depicted from the example, home dir character '`', for Unix users.

     "client_file" indicates a location for the special options file
generated by this client. Namely, on the main dialog, there is a
button for Options, which when pressed offers a dialog for the highly
controlled data entry. With this dialog, you can enter data on:

     - User
     - Host
     - Port
     - Number of queries to be kept in history list box and in history
       file
     - Compress option
     - Password option - i.e. should client ask for password on
       startup or should it try to log user with password=NU
     - Connection timeout

     It is recommendable for Unix users to setup client_file on user
basis, i.e. related to home directory. This dialog enables user
friendly options settings. This dialog also enables saving options to
a "client_file". If there is not such file, this button is
deactivated. There is also a button for applying options, which
enables user to switch to another host or server, or to use another
user rights, or to enable compression, only as much as this session lasts.

     "queries_file" contains a location for the file containing
history of all SUCCESFULL queries. If this file is not specified, a
default path of "~/.mysql_history" is used. Therefore, Windoze users
are HIGHLY recommended to set this option. This file is also shared
with mysql monitor program. In order to to follow up the entire
philosophy, only lines with ';' at the end are loaded into client and
listbox. These chars are stripped off, because in this client, there
is no need for ending characters. When the client is exited, all
queries are automatically saved in history file, with ';' at the end,
so that they can be used with mysql monitor or other utilities.

     "history_length" defines how many successfull queries will be
kept in history listbox and in the history file. It must be noted that
this option also enables maintenance of the history file, because
the set number of queries determines both number of lines in the
listbox and in the history file.

     "database" signals a client which database user wants to log in
immediately upon firing a client, and client tries to do so. If
database is not specified or if logins is unsuccesfull, client logs to
the first available database.


     Main dialog


     When a client starts, first dialog which shows up is the main
dialog. In the upper left corner of this dialog a light button is
located. When (green) light is present in the button, it indicates
that connection with server has been established. When this portion of
the button is dim and grey, this indicates that connection with server
is broken or that server is down. Repetitive pressing on this button
connects / disconnects this client from server. If connection is not
successfull, this is indicated by the light bulb in the button. It
should be also noted that if password is entered on startup, it is
remembered in memory, as long as options are not  changed.

    This button is always active, while others may not be active,
depending on the status. Below connect button is Options dialog
button, which starts Options dialog. This button is also always
active.


    On the right of these buttons is a menu containing a list of the
available databases, which menu always displays the current
database. This menu is inactive when connection is not
established. Clicking on another item on the menu automatically
switches to that database.


    Below MySQL logo and right of database menu, help button is
present, which invokes this help screen. This button is deactivated if
the location of help file is incorrect. Exit button is also active all
of the time.

   In the center of the main dialog is a multiline editor, based on
the input widget which enables multiline input of queris. This editor,
beside allowing the standard navigation keys, accepts the following
ones, to further accelerate entry and editing of queries.

  Keybindings for the input fields

    Mouse button 1

    Moves the cursor to this point.  Drag selects
    characters.  Double click selects words.  Triple click selects all
    text.  Shift+click extends the selection.

    Mouse button 2

    Insert the current X selection at the cursor (unlike Motif this does
    not move the insertion point to the mouse).  If the widget does not
    have the input focus (and thus no cursor) it puts the cursor where
    clicked and inserts the selection there.

    Backspace

    Deletes one character to the left, or deletes the selected region.

    ^A or Home
    Go to start of line.

    ^B or Left
    Move left

    ^C
    Copy the selection to the X selection

    ^D or Delete

    Deletes one character to the right or deletes the
    selected region.  Due to silly historical X problems, the Delete key
    will act like Backspace until you type a "real" backspace.</i>

    ^E or End
    Go to the end of line.

    ^F or Right
    Move right

    ^K

    Delete to the end of line (next \n character) or deletes a single \n
    character.  These deletions are all concatenated into the X
    selection.

    ^N or Down

    Move down (for Fl_Multiline_Input only, otherwise it moves to the
    next input field).

    ^P or Up

    Move up (for Fl_Multiline_Input only, otherwise it moves to the
    previous input field).

    ^Q or  RightCtrl or  Compose

    Start a <a href=compose.html>compose-character</a> sequence.  The
    next one or two keys typed define the character to insert.  This
    also can be used to "quote" control characters.

    ^U
    Delete everything.

    ^V or ^Y
    Paste the selection

    ^X or ^W
    Copy the region to the selection and delete it.

    ^Z or ^_

    Undo.  This is a single-level undo mechanism, but all adjacent
    deletions and insertions are concatenated into a single "undo".
    Often this will undo a lot more than you expected.

    Shift+move
    Move the cursor but also extend the selection.

       Listbox with a history of query commands is located below input
editor, and it is active when a connection is established and when
there is a single query in the history. When the limit of number of
queries is reached (see above), queries are rearranged according to
LIFO principle.

     A single click on any of the queries in the listbox copies a
command to the editor.

     Right of the multiline editor is a clear button, which clears all
contents of the editor and a button which executes commands. If the
error is returned, a full error message is displayed. If it is an
error in syntax, cursor in editor is positioned immediately before a
word which caused the parse error.

    When the executed query produces results which contains rows, an
interim dialog is created, presenting a number of rows in the result
set and offering to either display results on the screen (query
results dialog) or to store results in a file.

    Main dialog and query dialog are the only two dialogs whose size
can be increased. Increse in the size of main dialog increases
multiline editor only.


    Query results dialog

    This dialog contains a box with info on the number of rows, below
which a 'spreadsheet' is displayed. First row of cells, coloured in
red, displayes field names. First oolumn of cells , also coloured in
red, is used to display current cursor position, and it is used for
navigation. This spreadsheet is held within scrollbars, when the width
or length are greater then the window itself. Changing the size of
this dialog changes the size of 'spreadsheet' only.

    Navigation withing spreadsheet can be done with normal
navigational keys, by clicking on the scrollbars (when present) and by
clicking (once) on the first (red) cell in the row. This clicking
changes a position of the cursor, which is displayed in the first cell
(red) in the row and in the input field (see below). Between
scrollbars and red cells are cells with field values. All field values
are presented except BLOB and TEXT (for the time being). All other
fields are presented within the preset limits of the maximum width of
cells, which is 25 chars. However, each field can contain data up to
4096 bytes. If the user desires to see entire content of the field, he
(she) should click or double click on that field. This will change the
current row (both in cursor and input field), and will enable user to
scroll horizontally through the contents. WHEN USER WISHES TO END
VIEWING, ENTER (CARRIAGE RETURN) KEY SHOULD BE PRESSED !!! All binary
data found in char and varchar fields are escaped.

    Below the spreadsheet a special navigational group is located in
the lower left corner. It consists of 4 boxes  and an input
field. Clicking on the first box brings cursor to the first row. Nex
box is used to scroll rows up. Next is the input field, where user can
enter directly row number to go to. Right of the input field is a box
which scrolls rows down and last box displays a last row.

    To the right of this group is a button which enables saving of
data to a file. To the right of it is exit button and a clock.


    File dialog


    This dialog offers a file choosing button which invokes a stndard
file dialog. This is a way the user can pick a (new) file for saving
data.

    Below this button is a menu offering a variety of field delimiters
and a group of radio buttons, offering a choice of quotes. When the
data are saved in a file, fields are escaped, wherever necessary,
terminated by a chosen char. All char types are escaped. Lines are
always terminated by a new line character.


    Shortcuts

    In the entire client, all OK buttons can be activated by Enter
key. Every window (including main) can be closed by Escape char, which
key is used for cancellation. In the options dialog, saving can be
initiated by Enter key, applying by Alt+a key and canceling by Escape
key.

    In the main dialog, queries can be executed by F5 button, a help
screen can be invoked by F1 button, Clear button is shortcuted with
Alt + Backspace key. Connection button is shortcuted with Alt+c key
and options dialog can be activated by Alt+o key.


    Credits

    First of all, this program is available under GPL and LGPL
licenses.


    Authors and contributors:


    Sinisa Milivojevic ([e-mail]) - Programming

    Natalija Milivojevic  -  GUI Design and inspiration

    Michael Widenius  ([e-mail]) - Concept, ideas

    Bill Spitzak ([e-mail]) - for fltk library

    Paul DuBois = for fixing a badly written  manual

    Many others, including Allan Larsson,  Jani andothers for
        support and ideas.