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. ^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 compose-character 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 (sinisa@grmec.com) - Programming Natalija Milivojevic - GUI Design Michael Widenius (monty@analytikerna.se) - Concept, ideas, debugging, support and everything else Bill Spitzak (spitzak@d2.com) - for fltk library Paul DuBois = for fixing a badly written manual Many others, including Allan Larsson, David Axberg, Jani and others for support and ideas.