Welcome to BiggerSQL Help

Help for Postgresql SQL Commands.

Help for each of the postgresql commands is located here.

Using the Program.

Using BiggerSQL is easy. When the program opens you will be asked to log into a postgresql database. After a successful login you will be able to use the main window to enter SQL commands to the postgresql database. The main window is divided into three panels. The top panel is where the SQL is entered.The next panel displays success and failure messages. The bottom window is used to show the results of a successful selection command.

The Info button on the bottom left of the main window will toggle open a drawer that will show an outline view of the names and properties of all of the tables that the logged in user owns.

Entering and Executing SQL Code

You may enter more than one SQL statement in the top pane (seperated by semicolons). The statements can span any number of lines. There are a number of options to execute the code.

Pressing command-r will cause the current selected text to be send to Postgres one statement at a time. If no text is selected then the entire contents of the window is executed.
Clicking the Run button at the bottom right of the main screen has the same effect as the command-r sequence.
Shift-Return or the Enter key will also cause any selected text to be executed. If there is no text selected, the line containing the cursor will be sent to the postgresql server.

IMPORTANT: The program splits the input on semicolons, then each part of the split is sent to the SQL processor. The algorithm for splitting the input is fairly simple minded. The input stream is examined and each time a single quote is found, the "state" of the analyzer changes from "being in a quoted string" to "not being in a quoted string" (or the reverse). Semicolons are deemed to be statement separators if they are found while the parser is in the "not in a quoted string" state. This means you should not use the construct: '....\'...' but rather '...''...' i.e. represent a quote by two consequtive quotes within a quoted string. Note that if you have a single SQL statement you do not need to terminate it with a semicolon.

Version 1.1 Additions March 4, 2004

This version adds "drag and drop" utility to BiggerSQL. The user can drag a text file ( no checks are made ) to the SQL edit window and the window will be set to the contents of the file. The program can also be started by dragging a text file onto the BiggerSQL icon. BiggerSQL will be started with the contents of the file visible in the SQL editor window but the user will still have to log in before any commands will be executed.

Version 1.2 Additions March 7, 2004

All Tables and Views are now available in the info drawer. Double clicking on a table/view item in the info drawer will cause the editor window to be cleared and the table/view to be displayed in the query results window. Two major memory leaks were discovered and fixed.

Version 1.2.1 Additions March 8, 2004

Added a "Show System Files" menu item to the File menu. Choosing this menu item toogles between showing the user created tables/views and all of the tables in the user catalog.

Version 1.2.2 Additions March 9, 2004

This version adds a script menu. During startup BiggerSQL looks for the directory ~/Library/BiggerSQL. If it is not present the directory is created. If the directory exists, it is scanned and any file ending with ".sql" will generate a menu item having the file's name in the Scripts menu. The user is encouraged t o save their favorite sql scripts in this folder. Selecting such an item will cause the editor window to be replaced with the contents of the file. The first item in the Scripts menu is "Open Script Folder". Choosing this item will cause the scripts folder located in the users Library directory to be opened by the Finder and made the front most window. The user could then drag files from this window onto the editor window.

Version 1.2.3 Additions March 16, 2004

I have added hooks to the PQprint function. The options dialog in the "Save Query Results..." menu now has three tab views. The first tab "CSV Format" will allow the user to specify a number of options for saving a file is the CSV format. The second table "Aligned Text" allows the user to generate a more nicely formatted output in which the text is neatly aligned in columns. The "Expanded Tables" option will print the result set in two columns, the first is the field name and the second is the field value. The third tab "HTML" generates an html table containing the result set. The user may specify a "Table Caption" and also specify html elements that will control the table tag. The latter two tags directly call the postgresql PQprint function, so what you see is what you get. The "Save Editor Window..." menu item allows the user to save the contents of the editor window.

Version 1.2.4 Additions June 12, 2004

I cleaned up a big memory leak in the outline view window. A bug in the relogin procedure that caused the script menu to be improperly rebuild was fixed. The File menu has a new item "Visually Display NULL fields". When checked, "<NULL>" is displayed in every field that is null in the results window, when unchecked the field is filled with the empty string. There are several changes with the Scripts menu. The Script menu will now will construct submenus matching the directory structure of the Script Folder. When an item is selected from the Scripts menu, the path name of the script will be inserted at the top of the editor panel as a sql comment. The Script menu now has an item "Update Script Menu". When selected, this item will cause the Script menu to be rebuilt. Execution time in milliseconds is now displayed in the Status window.

Version 1.2.5 Addition Jul 18, 2004

The last successful login information will now be saved ( but not the password). If the login is successful, a welcome message will appear in the status area. The user can choose to send the selected parts of the editor to the postgresql backend one statement at a time or the whole selection in one shot by selecting the "Send Single Statements" menu item in the File menu. If "Send Single Statements" is checked the program will attempt to split the selected sql into individual statements and send them one at a time, if unchecked the statements will be sent as a single transaction. The user can now select the font and size for both the editor window and the results window. The new choices will become the default choices until changed again by the user.

Version 1.3 Additions Jul 26, 2004

Version 1.3 released. This version offers and "Open Recent" menu. Files loaded with the open command, files that are dragged onto the editor window and files that are dragged onto the application icon will generate an entry into this menu. The Scripts menu has a new item "Add To Open Recent" , when checked items loaded from the script menu will also generate a menu entry in the Open Recent submenu.

Aliases are now (hopefully) properly resolved. The user can drag an alias onto the editor window and the actual file will be opened. An alias can also be dragged onto the Application icon and the original file will be opened. If an alias file or folder is dropped into the Scripts folder the actual files will be loaded when selected from the Script menu.

The history file is now capped at 50 entries and is remembered across invocations of the application. There is a new menu item "Clear Statement History mm (nn)" in the Edit menu that will clear the history list. The number in the parenthesis is the number of items in the history list. The other number is a pointer into the list for the previous/next menu items. Note clearly that selecting this menu item will clear the entire list.

Column titles are now centered. I attempt to right justify all numeric data in the displayed tables.

This release features an interface to the psql client. When BiggerSQL starts it searches for psql in ~/Library, /usr/local/bin, /usr/local/pgsql/bin in that order. If you have psql located in another location you can put a symbolic link into your personal Library directory.

There is a new menu item "Send To Psql" in the File menu. If there is a nonempty selection and psql was found then the menu item will be "active". Choosing this menu item will send the selected text to psql for processing. The status and error infomation will generally be shown in the status window and the results will be displayed in the editor window. No timing information will be shown in this case. The way this works is that when the menu item is picked, a new process is generated that executes the selection and returns the results to the program. The command is more or less displayed in the status window and will look like:

Launched: /usr/local/bin/psql -U <user> -d <database> -c <selection>

Note that this is a "one shot" action, the command executes, returns the results and then terminates. Each command should be thought of a single independent session. You need to read the man page documentation for psql for the limitations of this interface.

Notice that there is no password present in the launch command. If your Postgresql system uses passwords you will need to set up a ".pgpass" file in your home directory. See the Postgresql documentation for the format for this file.

You can have sql statements or "meta" commands in the selection, but not both. The editor window has been reconfigured so that instead of wrapping at the margin a horizontal scroll bar will appear and you can scroll all the way to the end of the table.

The main reason for this interface was to gain access the to the cool features of psql. Using this interface BiggerSQL can now easily deal with large objects, use the \copy command, retrieve PL/pgSQL function definitions and much more.

Meta commands, psql commands starting with a' \ ' , are now recognized on the fly in the edit window, so if you enter the command \d+ and execute the command as a sql command ( see above for the various ways to do this). The meta command will be diverted directly to psql and the results will appear in the edit window.

In this case the timing information will show but is not relevant. The psql command executes independently of BiggerSQL and the output is written to the window as it becomes available. It is probably the case that if you had several metacommands operating at the same time the output could be interleaved in the editor window.

Version 1.3.1 Additions Jul 26, 2004

Intercell spacing has been increased so numeric and text items do not appear to be jammed together.

Fixed the login failure message to specify the reason for the failure.

BiggerSQL now notes the completion of a psql task and displays the final command status in the status window. In addition the psql pid is displayed in each message and the lapsed time in milliseconds for the task is displayed in the task termination message. Note that if the user were to enter the "\c" connect meta command, the status window will show a request for a password. Since there is no way to send a password the process must be killed. This can be accomplished by entering the shell command "kill pid" as a meta command ie \! kill <pid of the process%gt;.

As noted earlier, a sql command can be processed by psql. It is interesting to see the overhead that passing information back and forth adds. I have a query that takes about 34 seconds when executed in the "normal" fashion. When passed to psql the time increases to about 54 seconds.

The main window title now shows some connection information.

The login window now has a "port" entry in case someone is not running on the standard postgresql port.

Version 1.3.3 Additions Aug 7, 2004

The most notable feature of this release is support for images and large objects embedded in the database.

The standard "Window" menu has been added to help manage the extra windows introduced in this version.

A new contextual menu has been added. If the user <command>-clicks on the display grid, a contextual menu will be displayed. The menu items that are currently available are "Show As Text", "Show As Bytea Text". "Show As Image", "View Oid As Text Object", and "View Oid As Image Object".

Each of the menu items act on the contents of the table at the location of the <command>-click.

The Show As Text action will display the contents of the specified field in a separate (scrollable) text window. Very large fields can easily be viewed in this window.

The Show As Bytea Text passes the contents of the selected field through PQunescapeBytea to replace strings that had been escaped when copied from the bytea field ( ie \012 is replaced by the newline character.

The Show As Image action will interpret the field as an image ( most of the common formats as supported) and display the image in a separate window. The Copy command in the Edit menu can be used to place a copy of the image on the clipboard. It is assumed that images are stored (unescaped) in bytea fields. Note that the fields will show in the grid as an escaped string. This string can easily be three times larger than the original file. SQL like "select * from myFavorite1000Pictures" will lead to unnecessary grief and pain.

The View Oid As Text Object will display the contents of the large object represented by the oid in a scrollable text window.

The View Oid As Image Object will display the contents of the large object represented by the oid in a scrollable image window. Again the image can be copied to the clipboard.

It is the users responsibility to choose the appropriate option from the contextual menu. (I have tried the "wrong" choices and have noticed no ill effects.)

Note that there are two new windows, one for displaying text and another for displaying images. The windows are reused as appropriate and closing the window only hides the window.

As noted earlier, storing images as bytea fields can slow the program down very quickly. Having a row element in the display grid with multi megabyte sizes is not very practical. To ease the pain a bit, there is a new menu item in the File menu "Suppress Long Fields".

When this item is checked, fields in the display grid will show <LoNg FiElD:nnn> when the field length is greater than 200 bytes. The number after the colon is the actual length of the field. The actual data is still available when the contextual menu is used. The state of this item is saved across invocations of BiggerSQL

Be aware that libpq is used to retrieve any selections from the database, so that the entire selection is stored in memory. If you have a large photo database make your selections with an eye toward how big the entire selection will be.

The imageView and textView windows have a small contextual menu. <command>-clicking on either of the windows will bring up a "Save As Text..." or "Save As Tiff..." menu. The user can then save the contents of the window.

Version 1.3.5 Additions Aug 18, 2004

This version uses a newer version of Andreas Mayer's Shell Wrapper. A message is now posted when starting if psql is found.

BiggerSQL is now multimedia aware. The contextual menu obtained by command clicking the results grid now has two new menu items.

   1) View Oid as QuickTime Asset
   2) View Bytea as QuickTime Asset

The "View Oid as QuickTime Asset" menu expects that you have a oid of a large object that contains a multimedia file that QuickTime can understand. QuickTime can interpret well over 100 different types of mutlimedia, but it needs a little help. A dialog will appear asking for a hint for the contents of the large object. The hint consists of naming a file extension that typically would be used if the data were stored in a file. So you might respond with:

     .mp3  if the media was the representation of an mp3 file or
     .mov  if the media was a QuickTime movie
     .jpg  if the media was a jpg picture.

Since QuickTime assets can be very large, when the Quicktime window is closed, the resources associated with the window are released. In any case the user has to be careful about memory usage.

By default, a NSMovieView scales the object to fill the view. Thanks to Douglas Welton, I have been able to scale the content proportionally. This might be useful for view large pictures.

Note that since the asset is scaled that a black bar will probably appear of the top or right side of the Quicktime window due to the mismatch of the proportions.

The "View Bytea as QuickTime Asset" menu item works in an identical fashion except the cursor needs to be over a bytea item when the contextual menu is invoked.

Version 1.3.7 Additions Sep 23, 2004

I finally got around to fixing the tooltips to show the datatypes of the columns.

I have added an experimental item to the File menu "Start A Copy Of BiggerSQL". The menu item does start a copy of BiggerSQL. Be careful how this is used, Both copies share the same preferences and of course a copy will cause twice as much memory to be used.

I fixed a problem where output from psql commands would dramatically slow down as the size of the output grew.

BiggerSQL now offers a File menu item "Do Live Scrolling of Psql Output". If checked, output from commands sent to psql will be displayed as received from the command. If not checked then the display will not scroll until the command has completed. For commands that generate large amounts of output suppressing the scrolling can cut the time to command completion by up to 75 percent.

Version 1.3.8 Additions Oct 15, 2004

Web browser technology has been embedded in BiggerSQL. The browser can be displayed by choosing "Show Web Browser" from the File menu.

There are two new items in the contextual popup menu that will also invoke the web browser. "View Bytea Field as HTML" and "View Text Field as HTML". Invoking either of these menu items when the cursor is over the appropriate field will bring the browser forward and attempt to display the contents of the field in the browser.

I have been using this feature to view html based email stored in one of my postgresql databases.

I have also used the embedded browser to interact with a database via cgi's without having to start a full blown browser.

There is also another new item in the contextual menu "Save Bytea Field..." . Choosing this item will allow the user to extract a bytea field into a user named file.

One caveat: This version was built against Version 8.0.0 Beta 3 of the Postgresql system. I did not have to make any changes in the source to accommodate this change. I do not think this should cause a problem...

Confessions.

BiggerSQL is nothing more than an enhanced version of BigSQL which was released by the good folks at BigNerdRanch. I have included the SQL html help files from the Postgresql 7.4 distribution.

This software comes with absolutely no warranty. Feedback,enhancement suggestions or error fixes can be send to my mail . I will try to keep the latest version in my Cocoa program section at my homepage.

Enjoy,

Jerry LeVan