Postgres on My Mac

Some quick facts & tips for new Postgres users, especially on the Mac…

Postgres installs a folder in your /Applications folder. Those are gui front-ends to the underlying command line tools. You regularly use two of those: 

• "pgAdmin" app
  You create and manage databases here, including defining tables, columns, users & roles. You can also type in SQL statements interactively.
• "PostgreSQL documentation" app.
  Actually this is just leads to the docs stored locally in HTML format, and opens them in a web browser.

GUI Apps

The underlying Postgres is installed in /Library/PostgreSQL/ folder. Note that this is not the "Library" folder in your own user's home folder. This is the root "Library" folder.

Underlying Postgres Installation

The funky thing about Postgres is that it creates a new Unix user on your computer, named 'postgres'. The installer prompts you for your system password to gain admin rights to create this new user and a password. It also creates a default database by the same name. Apparently there is an old tradition in databases to assume that every system user will want to automatically login to their own private database. Seems silly to me, but remember that in those old days IBM considered SQL to be an end-user self-service tool. 

Anyways, note that the 'data' folder has a red stop sign on its icon. This means you cannot open that folder. The idea is extra security; if the regular user account is compromised, the bad guys will not have direct access to the database and its files. So choose a good long strange password for that 'postgres' user account, and write it down somewhere safe. The tools such as 'pgAdmin' app require that password to gain access as the 'postgres' user to perform actions such as creating a new database. 

You can begin learning Postgres using that 'postgres' user. But soon you should create at least one new Postgres user & password, to access each database without full admin rights, for regular use such as when developing end-user apps that connect but should only be allowed to add and drop records as opposed to deleting all databases. The 'postgres' user can wipe out all databases and do other dangerous acts not allowed 

How do your backup your database if you cannot reach its files in the Finder? Use the "pgDump" tool to pour out the data and scheme definitions as plain SQL text. Postgres and its MVCC implementation are built to do a pgDump run without shutting down the server. (Amazing to me!)

If you want to run the command line tools directly in a Terminal window, switch to that folder. Type the 'cd' (Change Directory) command, followed by a space, and then drag and drop the 'bin' folder from the Postgres folder. Press Return. To see verify, run this in the Terminal run the command to list all files: 

ls -a

To verify the version of Postgres currently running, run this in the Terminal:

./pg_ctl --version

Or in the SQL pane of pgAdmin, execute this SQL:

SELECT version();

My first Postgres Function (PL/pgSQL)

After reading this O'Reilly article and the Postgres doc, I made my first function to run inside the Postgres server. This code is serves no real purpose, but is simple and harmless, so it makes a good example and first experiment.

CREATE OR REPLACE FUNCTION some_number() RETURNS integer AS $$

DECLARE
    quantity integer := 30;
BEGIN
    quantity := 42;
    RETURN quantity;
END;
$$ LANGUAGE plpgsql;


You can try it. Copy that text, paste it into the ‘Query Tool’ of pgAdmin, and execute it. If it works, you'll get a response like this:
Query returned successfully with no result in 230 ms.

To call the function, execute this line:
SELECT some_number();

You should get a result set of one row and one column, with the number "42".

NOTES

Notice that the example above is a single line of SQL. From the SQL interpreter's perspective there is a single line, with 4 key words ("CREATE…", "RETURNS", "AS", "LANGUAGE") and a semicolon at the end. The DECLARE-BEGIN-END, our function's source code, is the content of a single value delimited by the double dollar signs "$$".

You can call "CREATE FUNCTION" or "CREATE OR REPLACE FUNCTION". The first is safer, so you don't unintentionally replace a pre-existing funtion. After re-writing your code, use the second command to replace existing code on you Postgres server.

Be careful in naming your function, to avoid using reserved labels.

The beginning and end of the function is defined by the "$$". The beginning before the dollar signs declares the signature of the function (name, arguments, and return type). The ending after the question declares the language used to write the function. Together, that beginning and ending make up a single statement as perceived by the SQL interpreter, with a semicolon at the end. The middle part, the source code of the function, is delimited by the "$$" to prevent execution by the SQL interpreter. Instead of execution, the middle block is handed over to the PL/pgSQL module.

There's a lengthy tutorial to read.

This function is written in Postgres' own scripting language, PL/pgSQL. You can write server-side code in several other languages such as Java, Ruby, Python, Perl, and more.

Roll your own "datetime" command line tool in Mac OS X

Sometimes you need the current date and time as a string. Perhaps to copy paste, or label something.

Mac OS X does have a command line tool to generate such a string, called: date

Unfortunately, the date string returned by default is the old-fashioned style:

Tue Oct 26 17:25:19 PDT 2010

All the cool kids nowadays are using ISO 8601, in a style such as YYYY-MM-DD HH:MM:SS
You can temporarily get your Terminal window to do this by pasting: alias datetime='date "+%Y-%m-%d %H:%M:%S"' and then typing: datetime


When you close that Terminal window, your Mac will forget all about this alias. To make it remember, create a text file named exactly, saved to your home folder: .bash_profile


'bash' is the name of the Unix shell used by default in later versions of Mac OS X. The period in front makes this file disappear, that is, the Finder will ignore it. There are other places to save this "alias" command, other files and folders, both traditional Unix/bash ways and Mac-specific ways. This way works for me.

The Terminal is built to look for and open a file with that exact name every time you open a Terminal window. Windows already open will not be updated, so try your new "datetime" command in a new window. You should see something like this:
2010-10-26 17:34:01

You can vary that alias, or create others, if you like. 

• If you want to use this datetime as part of the name for a file in the Mac's HFS+ file system, then you must avoid the colons.
  alias datetime_mac='date "+%Y-%m-%d %H-%M-%S"'


• A strict ISO 8601 datetime should have a "T" rather than a space in the middle, and represents the time zone as an offset from UTC time.
  alias datetime_iso='date "+%Y-%m-%dT%H:%M:%S%z"'


• You may want to use UTC time (formerly known as GMT or Greenwich Mean Time), where 'Z' means Zulu time.
  alias datetime_utc='date -u "+%Y-%m-%d %H-%M-%SZ"'


• Perhaps UTC time in ISO format:
  alias datetime_utc_iso='date -u "+%Y-%m-%dT%H:%M:%SZ"'

For your convenience, here is all 5 ready for cut-and-paste:


alias datetime='date "+%Y-%m-%d %H:%M:%S"'
alias datetime_mac='date "+%Y-%m-%d %H-%M-%S"'
alias datetime_iso='date "+%Y-%m-%dT%H:%M:%S%z"'
alias datetime_utc='date -u "+%Y-%m-%d %H:%M:%SZ"'
alias datetime_utc_iso='date -u "+%Y-%m-%dT%H:%M:%SZ"'


Results:

$ datetime
2010-10-26 18:11:59

$ datetime_mac
2010-10-26 18-12-03

$ datetime_iso
2010-10-26T18:12:06-0700

$ datetime_utc
2010-10-27 01:12:13Z

$ datetime_utc_iso
2010-10-27T01:12:19Z




Get DateTime in one line, in REALbasic

In REALbasic syntax, it is not legal to call a method on an instance created with "New". So you have to capture the new object on one line of code, and then on successive lines use that object. This is particularly inconvenient when briefly needing the current datetime instance or string. Grabbing the datetime is common when logging, debugging, or recording the moment in database records.

For example, using getting a datetime as a string requires two lines of code:

dim now as new Date
MsgBox( "At the tone the time will be: " + now.SQLDateTime )


For convenience, to collapse those multiple lines of code, add these two little methods to your App class, or some other utility class.

Function now() As Date
  dim thisMoment as new Date
  return thisMoment
End Function


and

Function nowSQLDateTime() As String
  dim thisMoment as new Date
  return thisMoment.SQLDateTime
End Function


Now you can make get the datetime mid-line:

MsgBox( "At the tone the time will be: " + app.nowSQLDateTime )





Postgres Companies and Resources

Just a list of links related to Postgres. I'm not necessarily recommending any.

Where it all starts

• Postgres community web site
• Conferences (United States) 
• Conferences (Europe)

Support, Training, Consulting

• Command Prompt
• EnterpriseDB
• 2ndQuadrant
• PGX
• Credativ

Add-Ons

• JasperSoft (JasperReports, reporting tool)
• REAL Software (REAL Studio, software development tools)

SQL Prepared Statement comes to REALbasic

In REAL Studio 2010 Release 4, the REALbasic language gains new interfaces and classes to support SQL Prepared Statement. This feature is called Database Parameter Binding.

A prepared statement is a SQL thing, where the query is pre-processed on the database server before it is actually used. The parsing of the SQL statement's text and verifying the table/column names is done ahead of time. The query planner in the database server figures out how to solve the query without actually executing one. Then you can execute the same query many times, passing arguments. Each successive use of that query saves you the overhead of parsing, processing, and planning by the database server. Not much difference for a low use database, but this is an easy way to greatly improve performance on a busy server. 

Another advantage is simplification of your programming code. It is easier to read calls to a prepared statement where you are passing the arguments for various column values rather than reading the entire text of a full SQL statement.

Besides performance on the server, and convenience in your code, there is another big advantage of the prepared statement: Security. This approach fights against “SQL Injection” attacks, where the bad guys put partial SQL statements in the fields of your form. With a regular SQL call, you’ll be unwittingly altering your SQL statement on-the-fly at runtime when those field values are interpreted as SQL commands. With a prepared statement, the SQL statement is already built and the query planner has already done its work before the form's data is incorporated. So any partial SQL in the form's fields will be treated as plain text rather than interpreted as SQL.

For more info on SQL Injection:

• Give me parameterized SQL, or give me death
• SQL Injection Attacks by Example

Here's an example of the prepared statement in action in REAL Studio.

dim db as new PostgreSQLDatabase
// Set db.xxx properties. IP address, db name, user name, user password, etc.

dim stmt as PostgreSQLPreparedStatement = PostgreSQLPreparedStatement(db.Prepare("SELECT * FROM cats WHERE name = $1"))

// 1 query, used 3 times.
// "Sebastian" is fed into the "$1" in line above.
Dim rsGoodKitty As RecordSet = stmt.SQLSelect("Sebastian")
Dim rsBadKitty As RecordSet = stmt.SQLSelect("George")
Dim rsCartoonKitty As RecordSet = stmt.SQLSelect("Sylvester")



The "$1" syntax above is specific to Postgres. Other databases may use a different symbol, typically "?" question mark. Furthermore, other database may require additional syntax to specify the data types of passed arguments.

The prepared statement is new to REAL Studio, but not to SQL or other programming languages such as Java. So don't be afraid to start using it if you upgrade to this new release. In at least Postgres, a prepared statement can be used on the SELECT, INSERT, UPDATE, DELETE, or VALUES commands.

Preliminary doc is here. The online wiki-based docs are not yet updated.

And some Postgres docs about prepared statements and its PREPARE command.

pgWest 2010 conference topics for beginners

I'm new to Postgres by way of programming in REAL Studio and its bundled database driver. Postgres keeps looking better and better. So my interest was piqued when I heard about the annual conferences where both the creators and users of Postgres congregate, alternating east and west coasts of the US.

Nov 2-4, 2010 is the west coast conference, called ‘pgWest’. This time around it’s located in downtown San Francisco. Even as a newbie, I found a useful topic in all the time slots. Here's a list of my picks among the busy agenda:

• GUCs: a Three-Hour Tour - Josh Berkus
• Securing your web application - Dave Page
• Survey of PostgreSQL Monitoring Tools - Gabrielle Roth
  or
  PostgreSQL Reporting with BIRT - MBennett
• PostgreSQL Backup and Recovery Methods - Kevin Kempter
• The PostgreSQL Community: an introductory tour - Josh Berkus
• Achieve PCI Compliance with PostgreSQL - Denish Patel
• MVCC Unmasked - Bruce Momjian
• Scaling PostgreSQL with Hot Standby - Greg Smith
• Rapid Upgrades With Pg_Upgrade - Bruce Momjian
• Postgres 9, the other stuff - Robert Treat
• Building and Distributing PostgreSQL Extensions Without Learning C- David Wheeler

There is also a mention but no information about a full day training session on Nov 5 by Bruce Momjian.

Standard delimiters

After decades of programming experience, I only now learn that the ASCII spec defined delimiters. As an extension of ASCII, Unicode adopted these too.

• Character 31 is for separating fields of data.
  – ASCII "unit separator" (US for short)
  – Unicode "INFORMATION SEPARATOR ONE"
• Character 30 is for separating records of data.
  – ASCII "record separator" (RS)
  – Unicode "INFORMATION SEPARATOR TWO" 

If you need higher levels of hierarchy or grouping:

• Character 29 is for separating groups of records.
  – ASCII "group separator" (GS)
  – Unicode "INFORMATION SEPARATOR THREE"
• Character 28 is for separating groups of groups, that is, a document or file.
  – ASCII "file separator" (FS)
  – Unicode "INFORMATION SEPARATOR FOUR"

This blog and this Wikipedia page explain. Correctly using these delimiters is properly called ASCII Delimited Text.

These delimiters were defined way back in the 1960s! So why on earth has common practice been the perversion of Tab, Linefeed, Carriage Return, Comma, etc. for delimiting data? Perhaps because text editors are built as stripped-down word-processors for visualizing text on screen, yet are often used for viewing and editing data streams. Tab, Linefeed, Carriage Return, Comma, etc. characters where meant to control presentation of text, but delimiters are meant to identify chunks of data in a stream. Since Tab, Linefeed, Carriage Return, Comma, etc. can very well be present inside a valid text stream, it is silly to use these as delimiters.

There are two distinct purposes being served by these code points:

• Text white-space
  Presentation of text characters on screen or on paper for display to humans, controlling placement of text in column position and lines, spreadsheet cells, and so on.
• Information separators
  Identify meaningful chunks of information inside a data stream, and show a hierarchical relationship of those chunks.

Mixing up the two (text white-space vs. information separators) is like serving the plastic green frilly stuff found between butchers' trays inside your hamburger.

As for white-space, carriage return, linefeed, tab, form feed, and such were originally intended to control presentation of data in a printer. Unfortunately, their purpose has been bent into indicating end-of-line and end-of-paragraph. Unicode had the bright idea of defining two new characters just for those purposes, to eliminate the ambiguities. Unfortunately, I've never seen them used.

• U+2028  (decimal 8,232) = SEPARATOR, LINE
• U+2029  (decimal 8,233) = SEPARATOR, PARAGRAPH

Postgres User Groups

I'm liking Postgres more and more. If you are interested in learning more about Postgres, you may find a user group meeting in your area.

In the Seattle and Bellevue area, there is SeaPug. If I could  draw, I'd make a logo: a Pug dog drinking Starbucks.

To find others groups, check this page.

Colo and hosting

If you want to pay someone to host your server on the internet, there are 3 ways to go.

• "Colo"
  Short for Co-located, where you own a computer, send it to a service company, and they install it in their racks. You own the computer box, they plug it into fast internet connections, uninterruptible power supplies with generator backup, and possibly behind firewall hardware. Some will sell you a computer from their inventory as well, new and/or used.
• Rent-a-server
  Same as above but you rent their computer rather than provide your own. With today's low costs for computing hardware, this may not make financial sense.
• Virtual Server
  You pay rent for a certain speed and number of processor cores, certain amount of disk space, and bandwidth and/or traffic. But it's all imaginary. You don't actually control a specific computer box, processor, or hard drive. Your virtual server is one of many others operating across a server farm, large arrays of computers. Some services let you shut down your virtual server but store your disk space while reducing the bulk of your cost. This is handy for test machines, or trial runs before launching your full-time servers.

In the first two categories, my professional contacts, previous research, and word-of-mouth leads me suggest the following companies to someone looking for a vendor:

• Mac mini Colo
• Mac Mini World
• NetRiver
• Digital Forest

Do your own research and shopping, but those vendors may be a good place to start.

Zipping beyond the Mac

I distribute my cross-platfrom app to the world as simply a zipped file. That seems to be working well, except for two problems:

• Older versions of Windows, even Windows XP, may not ship with a Zip tool. 
• When creating the zip on my Mac using the Finder command File > Compress*, extra files or folders are included for Mac-savvy features. 

The first problem, I have no answer for. Except to say I've gotten no complaints from the public yet. So perhaps the problem is not widespread today.

The second problem is a problem only for the non-Mac crowd. On a Mac, the extra file/folders are invisible. But on Linux and Windows computers, the users see this extra crud and are likely to get confused. I have found 2 easy fixes.

• Path Finder
  This excellent app from CocoaTech is a Swiss Knife full of diverse tools, handy for a range of geeks and programmers. It costs about forty bucks, and so worth it. Relevant here is the ability to create zips. By default it creates zips in the same Mac-savvy way. To strip that extra stuff in future zips, in Path Finder preferences, turn ON the two "Ignore" checkboxes.
  ☑ Ignore invisible file when compressing
  
  ☑ Ignore resource forks when compressing
  
  
• YemuZip
  This free app from Yellow Mug does one simple thing: Create zips. Drag-and drop easy. With the option of stripping away the Mac-specific stuff. Perfect. Even includes a feature to check for updates.

* Older versions of Mac OS X: File > Make Archive

Running Apache Tomcat on your Mac

  

Apache Tomcat is Apache's other web server. Also runs Java Servlets and JSPs. I prefer running Tomcat as a web server much better that Apache's more famous (and finicky) "httpd".

Tomcat is pure Java, so it runs very well on your Mac OS X computer. Apple builds Java into every Mac.

• The current version 6 runs on many older generations of Macs as well as new ones. 
• The still-beta version 7 will run only on Java 6, which requires an Intel Mac running Snow Leopard.

There is one big catch to running Tomcat on your Mac: By default, the permissions are set incorrectly on the downloaded files. When you try launching Tomcat you will get errors, complaining that you do not have permission to complete certain operations. The fix is so easy: just a drag-and-drop and a few mouse clicks. Here's how.

Download the free app (donations accepted) BatChmod. It has the best icon, by the way. This app is a very convenient gui wrapper around an otherwise very difficult arcane set of command-line instructions. You will be entrusting your system password to them, and do so at your own risk. They've been in business for years with no issues I've heard of. Tip: To detect any software phoning home without your permission, get the Mac app Little Snitch.

Download Tomcat. Version 6.0.29 is current nowadays. Grab the zipped one, as the tarred files may not work with Mac OS X' tar tools. You'll end up with a folder named something like "apache-tomcat-6.0.29". If you’re paranoid, hit the MD5 link, read the number, then drag and drop the downloaded zip file to a Terminal window after typing "md5 ", and compare your number to theirs. If no difference, you downloaded without corruption.

You can place the Tomcat folder anywhere you like. I avoid nesting too many folders because extremely long path names can cause problems. I suggest the top level of your home folder.

1. Drag and drop your unzipped Tomcat folder to the BadChmod app. 
2. Check all the checkboxes except "Clear xattrs".
3. Click Apply.
4. Enter your system password.
5. Quit.

CAVEAT: I am not expert at these Unix permissions and related issues. Do all this at your own risk, and after your own research. I'm just sharing what works for me, but taking no responsibility for you.

This problem of Unix file permissions often occurs on downloaded files, but the effects are more obvious in Tomcat. I usually run BatChmod on anything I download, unless packaged as a .DMG file. 

Now you're ready to launch Tomcat.

1. Open a window in Terminal app, found in Applications > Utilities folder.
2. In the Finder, locate inside the "bin" folder inside the Tomcat folder.
3. In "bin" folder, locate the file named "startup.sh".
   (Ignore the .bat files; those are for MS Windows)
4. Drag and drop that "startup.sh" to your Terminal window.
5. Press Return to run that shell script.
   (".sh" means "shell")
6. See several lines of text appear in the Terminal window.
   (If you see about 5 lines of "Using " this-or-that, you are in good shape.)

Now test your web server.

1. Launch a web browser, such as Safari, Camino, Firefox, Opera, Chrome, etc.
2. In the URL address bar, type:
   localhost:8080
   Or if that seems to fail, type:
   127.0.0.1:8080
3. Press Return to make the web browser hit your web site.
   If successful, you should see a web page displayed with the cute tiger Tomcat logo and the Apache feather logo.

To get rid of the need to add the ":8080" see my other blog post on port-forwarding.

To shutdown the web server, in that same Terminal window, drag and drop the "shutdown.sh" file. Press Return to execute, of course.

Tip: Press the Up-Arrow key to re-enter previously used lines in that Terminal window. Press Return to execute one of them. This is a handy way to easily repeatedly start and stop Tomcat.

If you got this far, lastly you replace Tomcat's default web site with your own. Replace the contents of:
Tomcat folder > webapps > ROOT

Note that we did not do any configuration settings in Tomcat whatsoever. I like that about Tomcat: For a single web site, Tomcat is ready to go out-of-the-box. You can do much more configuration if you wish as Tomcat is relatively flexible and full-featured as web servers go. You can change the port number. You can turn on logging to record who hits your web site and when. You can enable virtual hosting to serve multiple web sites. You can set up security restrictions controlling access to portions of your web site.

In passing, I'll mention another popular Java-based alternative to Tomcat: Jetty. If you want a bunch of additional functionality, beyond just web serving and Java servlets, for a big application server consider Glassfish. But for me and most folks I know, Tomcat or Jetty are the way to go.

Hope that works for you. Happy serving!

Use Google to search REAL Studio docs

I really miss the PDF version of docs for REAL Studio 2010. With PDFs, I can use Apple Preview or Adobe Reader to search through an entire manual to find occurrences not listed in the TOC or Index.

The REAL Studio team has chosen to move from PDFs to online wiki-based docs, for the noble reason of keeping the docs always up to date. Unfortunately, the price we paid is awkward search capability. Unless you are searching for an exact class name, the search utility at docs.realsoftware.com leads to frustration.

Then I remembered the wise man who taught me this nifty trick in using Google: Constrain a Google search to a single domain (web site). Simply add the word "site:" (with a colon) and the domain name. Then add on your usual search criteria.

For example, instead of googling this:

Shared Property

Put this into your Google bar and smoke it:

site:docs.realsoftware.com Shared Property

 

Add a Version Number to Your Classes

When creating classes to be shared with others, add a property to represent the version.

Programmatic access to the version number is good for at least 2 reasons:

• Review what version is currently installed in an app.
• Calling code can work around bugs or changes in behavior if it knows the version number.*

At the very least, add a simple string to store something like "2.4".

Make the property a "static" or "class" field with one value shared among all instances. The number will not vary across instances, so there is no need to make it a regular member. In REALbasic, make it a Shared Property.

Tracking a field's value in REALbasic

Oddly enough, REAL Studio 2010 through Release 3 does not offer an event meaning the user (or code) changed the value in a TextField. On every keystroke, both "KeyUp" and "TextChange" fire. But that is too often. In boring database-backed business apps, we usually don't care about the user's edit as it happens. We only care after the edit, when the change is complete.

Hopefully the REAL Software team will add such an event in the future. In the meantime, I am giving away a single file, a subclass of TextField named "TextField_ValueTracking". I have an example project to demonstrate how it works. See here.

Moving files securely between Macs

How do you move files across a network or Internet to a secure Mac server?

---

iDisk

As a faithful Apple customer with a MobileMe account, my first thought was to use my iDisk to transfer files. I put files into my "Public" folder, then on the server in the Finder I choose Go > iDisk > Other User's Public Folder. The Finder mounts the public folder as a drive. Works well. Until it doesn't.

---

Problem

Twice now I've been burned in Mac OS X 10.6.4 and .5 where the Finder gets confused about the mounted iDisk folder. One symptom of this Finder bug is refusing to dismount. The Finder complains that a file is in use, but that's not true. The list of files in the mounted iDisk no longer updates its display to show current contents. "Force ejecting" the mounted iDisk fails. Your only option left is to force-quit the Finder. But that hoses your Mac, requiring a restart of your secure server. That's a drag.

I don't expect a fix soon. The Finder has always been lousy with bugs related to iDisk and its WebDAV protocol. With Snow Leopard, the Finder got a re-write in Cocoa from Carbon, which means new hiding places for bugs.

---

Workaround

One dead-simple workaround:

Rather than mount the iDisk in the Finder, use a web browser. 

Apple has been greatly improving the web access to MobileMe features. That includes iDisk file access. A nice multi-columned view of the file system appears in your web browser when you access the iDisk icon.

To log in to your MobileMe account with full access:

http://www.me.com/

To access somebody's iDisk public folder, point your web browser to:

http://public.me.com/TheirUserNameGoesHere

By the way, there are some other handy such URLs for accessing a MobileMe account's picture gallery, calendars, and web site.

You may be able to use Safari or other web browsers such as Camino, Firefox, Chrome, or Opera. I've some of those successfully, but don't recall which. You may get a warning message, but I've ignored it with no penalty.