Installing PostgreSQL On Mac OS X
 

Psyex

Mac OS X

PostgreSQL

Ant

Unix newbie

 

Downloads:
Makefile.shlib
ipc.c
Makefile.darwin
JDBC Driver Jar
JDBC Class
JDBC Source
 

 

 

So, you want a high-powered database for your nice Mac OS X machine, but don't have a spare $90,000 in the back of your sock drawer for an Oracle database . . .

--By Russ McBride of Psyex inc.

[Note: This document is now out of date now, given releases of OS X and PostgreSQL, but is left here for archiving purposes.]

Think PostgreSQL (no, I don't try to pronounce it, just think it). PostgreSQL is a powerful relational database management system (RDBMS) born in the ivory towers of U.C. Berkeley, yet it's fulfilling the liberal yearnings of it's ancestory as a free alternative to the likes of rich neighbors like Oracle, to the South, and Sybase a few miles to the East. At $30 per MHz ($45 for a RISC processor), the last I checked, running Oracle on a 1.5GHz machine will cost you $45,000 right off the bat, before you start thinking about multi-processors or annual fees. You've got a dual processor box? That will be $90,000 please. Add an extra 6 machines with PostgreSQL, say 6 Sun E10000s, each with 64 processors and PostgreSQL will cost you, well, exactly what you first paid for it . . . nada, that's $0. You just saved $6.5M thanks to it's open source heritage and those Berkeley liberals--you know the same University of California folks that provided much of the brain power for the Department of Justice's battle against Microsoft (Oracle's neighbor, Stanford, on the other hand, provided much of the brain power for Microsoft's defense).

What follows are detailed instructions for getting PostgreSQL up and running on your Mac OS X machine, including optional steps for installing java JDBC access. There's other online documentation that can help you in your installation woes, the most helpful, in my opinion, being the book written by Command Prompt, which specializes in PostgreSQL database installation and administration, available online here, the Administrator's Guide that's part of the standard documentation, and Marc Liyanage's OS X instructions for using his installer package that will have you up and running quickly. But none are super helpful for the future administrator who wants to begin to understand the PostgreSQL system as it's setup on OS X, nor for your average OS X Unix newbie who didn't successfully execute the terse instructions, or who perhaps did, but didn't know why they worked. A useful collection of resources can be found here. The goal of this document is to provide more thorough installation instructions specific to the OS X operating system, provide a bit of knowledge along the way, and hopefully end those seemingly endless hacking efforts that all too often accompany what should have been a quick installation. Born of my own pain, I hope to save others the same grief and wasted time. This means that the instructions here are a bit longer than you might expect but, as has been said about Kant's Critique of Pure Reason, "If it were 3 times the length, it would have taken 1/10th the time to read." So, I will consider this document successful if someone new to Unix is able to get PostgreSQL up and running on their first try. Impossible you say? Well, let's give it a shot . . . .


PREREQUISITES:

  • You need to understand pathnames, so that if you download a file, onto your desktop for example, you can find it in a terminal window by going to:
    /Users/me/Desktop/<some_file>

    Generally, I'll put names that you have to figure out by yourself in between these angle brackets:

    <you_enter_it_here>

    Don't type the angle brackets.

  • You need an internet connection.

  • And you need a modicum of patience. The test? You throw temper tantrums while waiting at red lights no more than 20% of the time.


PREPARING TO INSTALL:

  • Download the latest version of PostgreSQL from the PostgreSQL site (or buy a PostgreSQL CD). Choosing a mirror site, then the "software" link and then the "Download" link should take you to the right page. You want the "postgresql-7.1.x.tar.gz" file. After downloading, it should unstuff automatically under OS X.

  • Load the correct version of Apple's developer tools, if you haven't already since you will need the compilers to compile PostgreSQL source code. You must be registered as a developer with Apple to get these, but you can sign up for free here as an "online" developer. Make sure that the developer tools you use are in synch with your operating system (the 10.0.x developer tools won't work with OS 10.1). If you're using, e.g. WebObjects, (WebObjects + PostgreSQL is an awesome combination!), then you've already got the developer tools installed. If you have to load them from scratch, reboot afterwards.

  • [10.1 or later users only] download the first three download files listed on the "downloads" section of this page, to the left. They should decompress automatically. You'll soon need them. Note that the additional steps included for 10.1.x users should only be necessary until PostgreSQL version 7.2 comes out of beta, since 7.2 (and upward) will compile successfully on Mac OS 10.1 (and up) without the additional work that we will do here.

  • If you want to set up JDBC access, download the three JDBC files as well. Confirm the jar download if your browser ask you to.

  • Throw away the compressed files and put all the decompressed files into /Users/Shared so they'll be easy to locate as you switch between different users, each of whom has a different desktop folder.

  • Enable root access. Go to Applications-->Utilities-->NetInfo Manager and select Domain-->Security-->Authenticate. This allows you to make serious changes to your system. Now choose Domain-->Security-->Enable Root User. It will ask you to create a password after generating a purported error message (at least in pre-10.1 systems). Create one and verify it when asked.

  • [10.1 or later users only] go to Applications-->System Preferences-->Log in, click the "Login Window" tab, and set "Display Login Window as:" to "Name and Password entry fields" so that it asks you for both a username and a password. Make sure that Auto login is not checked.

  • Log out using the command under the apple menu and log back in, entering "root" (without the quotes) as the user, and entering the password you just chose for root. Warning: you now have the power to seriously screw up your operating system. Did you backup your important data?

  • For convenience, drag a couple of applications to the dock right now: the terminal from Applications-->Utilites-->Terminal, and the Process Viewer also from Utilities.

  • Choose System Preferences-->Users, hit "new user", name the faceless beast "postgres" , shortname "postgres", and choose a the password, "postgres", which you should change after this installation.

  • Open a new terminal window using the Terminal application (and should you know how to do it, don't switch your shell from tcsh to something else).


ANT [for JDBC users only]:

Think of Ant as a java-based tool for properly handling the compiling of java source files:

  • Download the latest Ant Binary, which as of this writing was version 1.4.   A "binary" file is just a pre-compiled application, like your favorite word processor. In the Unix world you often have the choice of downloading the source code and compiling it on your machine to make sure that it works specifically for your configuration, or downloading a pre-compiled binary file and hoping that it runs. The Ant binary works fine under OS X, so I'm not going to discuss how to compile the source code version. Look for a file named, "jakarta-ant-1.4-bin.tar.gz"

  • Open up a terminal window and make a new directory called "ant" and put it in /usr/local so that you have: /usr/local/ant by typing in the terminal:

    mkdir   /usr/local/ant

  • Locate the "bin" and "lib" folders that are inside the ant folder and stick them in the ant directory so that you have: /usr/local/ant/bin and /usr/local/ant/lib, by typing the following, remembering to replace the text below with the actual file path to the ant folder (and don't forget to hit enter after each command).

    cp   -R   <file.path.to.ant.folder>/bin   /usr/local/ant

    cp   -R   <file.path.to.ant.folder>/lib   /usr/local/ant

  • Set a couple of environment variables. You can think of these as variables you make available to your shell so that scripts and programs started by the shell can utilize the values of those variables. Many of those values are search paths so that when you or an application execute a command, the system can find the code for that command by traversing those search paths. Type (note the capitalization):

    setenv   JAVA_HOME   /Library/Java/Home

    setenv   ANT_HOME   /usr/local/ant

    (Note that the "export" command that's referenced in most of the installation doc's for this step is equivalent to the "setenv" command that we have to use in the tcsh shell.)

  • Add a couple of file paths to the end of your PATH environment variable. This is the main set of search paths. Each path is separated by a colon. Type (note the capitals):

    printenv PATH

    This will show you the contents of your PATH variable.

  • Add two ant paths to the end of the current settings, by hilighting the existing path very carefully (starting just after "PATH" and going all the way to the end, but not including the line break, and then selecting "copy" from the edit menu). Then type "setenv PATH ", leave a space, and then paste in what you just copied. Note that there's a space between "setenv" and "PATH" and between "PATH" and the full set of search paths, but no spaces anywhere in that long set of search paths. DON'T HIT "ENTER" YET. Now tack onto the end of the path (note the beginning colon): :/local/ant:/usr/local/ant/bin. So the full command looks like this:
    setenv   PATH   <your_old_PATH_pasted_here>/usr/local/ant:/usr/local/ant/bin

    Although the the text may wrap around on your screen there's no space in the full PATH setting.

    Now that you understand that you're adding two paths to the end of your existing path settings, it's nifty to know that you could accomplish the same thing another way by utilizing the path variable, $PATH, where your existing path info is stored:

    setenv PATH {$PATH}:/usr/local/ant:/usr/local/ant/bin
  • Now hit "enter"

    On my system the starting PATH before modification looked like this (note again that this path list is just one long line being wrapped by limits on screen width):

    ~/bin/powerpc-apple-macos:/var/root/bin:/usr/local/bin:/usr/bin
    :/bin:/usr/local/sbin:/usr/sbin:/sbin

    After modifying PATH, it looked like this (which I verified with the "printenv PATH" command):

    ~/bin/powerpc-apple-macos:/var/root/bin:/usr/local/bin:/usr/bin
    :/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/local/ant:/usr/local/ant/bin

  • If you screw up just log out and log back in (as root). The original PATH setting will be reloaded as it was. This of course means that if you log out for any reason, you'll have to reset all the environment variables we've modified so far (PATH, as well as JAVA_HOME and ANT_HOME if you've set those).


PATCHING THE SOURCE CODE [10.1 AND LATER USERS ONLY] PostgreSQL won't work on Mac OS 10.1 due to changes in the linker and other improvements. So we need to replace 3 of the files that come with the postgreSQL download: Makefile.shlib, ipc.c, and Makefile.darwin. You 10.1 users should have already downloaded these files from the "download" links to the left. These are files made from their originals using a patch by David Gatwood and Andreas Monitzer I originally got here. (Thanks to Hunter Hillegas for the link.)

  • Drill down into postgresql-7.1.3/src, and you'll see "Makefile.shlib". Throw it away and replace it with the file of the same name that you downloaded.

  • Drill down into postgresql-7.1.3/src/Makefiles, and in that directory you'll see "Makefile.darwin". Replace it.

  • Drill down into postgresql-7.1.3/src/backend/storage/ipc, and replace the "ipc.c" file.


COMPILING AND INSTALLING POSTGRESQL:

  • Using the terminal, navigate into the PostgreSQL folder that you downloaded. You should have downloaded the folder onto your desktop and then stuck it in "Shared", in which case you would type:
    cd   /Users/Shared/postgresql-7.1.3
    In general, with Unix you use three commands a lot: the "cd" (change directory) command, the "ls" command (which lists the contents of the current directory), and the "pwd" command (which tells you where your are). So, to get to any given directory you're often going to be cd'ing, pwd'ing, and ls'ing before you get to where you want to be.

  • Now that you are actually inside the postgreSQL directory, you're ready to "lock 'n load". If you want JDBC access (and you followed the necessary JDBC steps above) type:
    ./configure   --with-java

    Otherwise, for non-JDBC configuration, leave off the optional argument and instead type:

    ./configure  

    If you get the message, "error: no acceptable cc found in $PATH" you probably don't have the necessary developer tools. Become an "online" ADC member with Apple and go get 'em. If you are trying to configure with JDBC and you get the eror message: "configure: error: Ant is required to build Java components", then you probably need to reset your environment variables--ANT_HOME, JAVA_HOME, and PATH.

    Note: This isn't, of course, an advanced installation guide, just a careful one for either a basic conguration or a basic configuration plus JDBC. There are an amazing number of configurations possbilities that allow you to set up PostgreSQL with just about any language you want--o.k., well not ADA--but almost any language. I'm not going to even try and discuss any of these other options here.

  • Wait until it's finished and ready, as evidenced by a command prompt. Then type:
    gnumake
    (confirm with a 'y' for each of the gnumake comands),

  • This will last exactly "awhile". Wait until it's finished, as evidenced by the text: "All of PostgreSQL successfully made. Ready to install". Then type:
    gnumake check
    (some tests will fail; this is usually o.k. and no reason to re-write your will.)

  • Now type:
    gnumake install

    After a few minutes, if all goes well, it will read: "Thank your for choosing PostgreSQL, the most advanced open source database". If it doesn't go well, try again, then try backtracking on your steps.


CONFIGURATION, START-UP, AND SHUT-DOWN:

  • Because we had to install postgres as root, root is now the owner of all the installed files. But root can't start-up the PostgreSQL server because that would be a security risk (PostgreSQL won't even let root start it up). So we make postgres user the owner of the files by typing:
    sudo   chown   -R   postgres   /usr/local/pgsql/

  • Now switch over to act as the postgres user:
    su   postgres

  • Move into postgres' directory where we know you will have permission to write into a log that you're going to create:
    cd   /Users/postgres/

  • Initialize a database:
    /usr/local/pgsql/bin/initdb   -D   /usr/local/pgsql/data

    This creates all the necessary files for a database cluster and puts them in the "data" directory

  • Now it's time to fire up the database server, "postmaster". If you're going to be connecting via TCP/IP, which JDBC needs, you have to put an "-i" into the following command, like this:
    sh   -c   '/usr/local/pgsql/bin/postmaster   -D   /usr/local/pgsql/data   -i   >   /usr/local/pgsql/logfile   2>&1   &'

    Otherwise, if you don't need TCP/IP access leave out the -i:

    sh   -c   '/usr/local/pgsql/bin/postmaster   -D   /usr/local/pgsql/data   >   /usr/local/pgsql/logfile   2>&1   &'

    You've got to be careful entering the above command. The apostrophes are important as are the spaces. You might want to expand your browser window so that you can see the full command on one line and note exactly where the spaces are, then mark them on the printed copy you're reading from right now.

  • If you had trouble starting postmaster with the above command, try this one:
    /usr/local/pgsql/bin/postmaster   -D   /usr/local/pgsql/data   -i

    Leave off the -i at the end if you don't want TCP/IP connectivity.

  • To (finally!) create a datbase, named "testdb", type:
    /usr/local/pgsql/bin/createdb   testdb

  • The easiest way of accessing the new database is with the "psql" application:
    /usr/local/pgsql/bin/psql   testdb

    You can control the application with the commands that begin with a backslash (type: "\h" for a list of them), otherwise you can enter regular SQL commands. I'd recommend going through the postgreSQL tutorial that's in the standard documentation.

Congratulations! You're up and running!

It's important to shut down the server gracefully when you're done so that any outstanding data gets written to the database and memory resources are released:

/usr/local/pgsql/bin/pg_ctl   -D   /usr/local/pgsql/data stop


JDBC:

If you want to use postgreSQL through a jdbc connection, you've got a little more work ahead of you:

  • The regular documentation recommends that you go into the postgreSQL folder, drill into ./src/interfaces/jdbc and type "gnumake", which will build two jar files: postgresql.jar and postgresql-examples.jar. There are known problems with the standard postgreSQL jar file so we're going to use the one downloadable here, "JDBC Driver Jar" (under the "downloads" section). I originally got this from http://www.optc.com/~btoback/postgresql.jar Take this file, which will download as "postgresql.jar", and place it in /Library/Java/Home/lib/ext

  • Using the terminal su into root and enter root's password when asked:
    su   root

  • We didn't save our environment variables in the login file for the shell so you may have to re-enter the setenv commands for JAVA_HOME and ANT_HOME (or modify the login file):
    setenv   JAVA_HOME   /Library/Java/Home

    setenv   ANT_HOME   /usr/local/ant


  • Now we're ready to load up the JDBC driver and try and make a connection. To facilitate this process Command Prompt has a java program written that I copied and included above in the downloads, "PGjdbc.class". I've modified the program so that is uses a username of "postgres", a password of "postgres", a database name of "testdb", and the localhost address of "127.0.0.1". If you don't have these settings you'll have to copy the source file, "PGjdbc.java", make the needed modifications, and then re-compile. Now, drill down so that you're in the same directory as the PGjdbc.class file and type in the terminal:
    java   PGjdbc

    Here's the description of the program code from the Command Prompt book, beginning with the "Class.forName" call: "Class.forName" is a method that finds a class by name. In this case, it looks for the Driver. This causes the class loader to search through the CLASSPATH and find a class by that name. If it finds it, the class loader will then read in the binary description of the class. If it does not find it, it will throw a "ClassNotFoundException", in which case we print out an error message. If you reach this state, you either haven't built the driver correctly, or the built jar file is not in your classpath. If you don't get the error message that means the driver is built correctly and the jar files must have been in the proper classpath. Once we've registered this class, we need to request a connection to a PostgreSQL database.

    If you got a "Hooray! We connected to the database!", you're golden.

  • If you're using Apple's WebObjects, you can start up EOModeler and start a new JDBC connection with the following information:
    user: postgres

    password: postgres

    url: jdbc:postgresql://127.0.0.1/testdb

    driver name: org.postgresql.Driver


  • Note that an error came up repeatedly for at least some people where 'localhost' would not resolve correctly, so that's why I've stipulated in both the connection program and the EOModeler information the universally standard localhost address (127.0.0.1) rather than using the standard word, "localhost".


    If you made it this far, congratulations. If you had trouble along the way, you might want to go to the PostgreSQL site and subscribe to some of the mailing lists to see if that childish charm of yours can't be used to garner some help from an altruistic sole or two.

    You can send comments and suggestions to me at Russ@psyex.com. Especially welcome are reports of any errors or typos and additional material that would be relevant to include to make this a more educational document for the Unix beginner.


    This Page was last update: February 4, 2002 at 12:41:35 PM
    This page was originally posted: October 3, 2001; 11:26:07 AM.
    Copyright 2001 Psyex-- Read, copy it, use it.

    A Psyex Inc. site