$Id: README,v 1.17 2002/01/16 18:10:10 jt Exp $

Abstract:

This is the README for the Cygwin PostgreSQL distribution.

Requirements:

The following packages or later are required to build and/or execute
Cygwin PostgreSQL:

    crypt 1.0-1
    cygipc 1.11-1
    readline 4.2a-1
    libreadline5 4.2a-1
    zlib 1.1.3-6
    cygwin 1.3.6-6

Install:

There are two types of Cygwin PostgreSQL installations -- basic and NT
services.  The basic installation is good for casual use on any version of
Windows, but required on Windows 9x/Me.  The NT services installation is
good for a more production environment, but is only available on Windows
NT/2000.  Note that this installation type is very similar to the normal
Unix installation with just some Cygwin/Windows variations.  You should
choose the type which best meets your needs and/or is constrained by your
platform.

Regardless of the installation type, the first step is to install the
latest cygipc from:

    http://www.neuro.gatech.edu/users/cwilson/cygutils/V1.1/cygipc/index.html

The following is the basic Cygwin PostgreSQL installation procedure:

1. Start the cygipc ipc-daemon:

    $ ipc-daemon &

2. Initialize PostgreSQL:

    $ initdb -D /usr/share/postgresql/data

3. Start the PostgreSQL postmaster:

    $ postmaster -D /usr/share/postgresql/data &

4. Connect to PostgreSQL:

    $ psql template1

The following is the NT services Cygwin PostgreSQL installation procedure:

1. Install the cygipc ipc-daemon as a NT service:

    # ipc-daemon --install-as-service

2. Create the "postgres" user account:

    # cmd /c lusrmgr.msc # [3]
    # mkpasswd -l -u postgres >>/etc/passwd

3. Grant the "postgres" user the "Log on as a service" user right:

    # cmd /c secpol.msc [4]

4. Install postmaster as a NT service:

    # cygrunsrv --install postmaster --path /usr/bin/postmaster --args "-D /usr/share/postgresql/data -i" --dep ipc-daemon --termsig INT --user postgres --shutdown # [5] [6]

5. Create the PostgreSQL data directory:

    # mkdir /usr/share/postgresql/data

6. Change ownership of the PostgreSQL data directory:

    # chown postgres /usr/share/postgresql/data

7. Initialize PostgreSQL (*when running under the "postgres" account*):

    $ initdb -D /usr/share/postgresql/data

5. Start the cygipc ipc-daemon:

    # net start ipc-daemon # [7]

6. Start postmaster:

    # net start postmaster # [7]

7. Connect to PostgreSQL:

    # psql -U postgres template1 [8] [9]

The following are the notes to the above:

[1] The "#" prompt indicates running as a user which is a member of the
    Local Administrators group.
[2] The "$" prompt indicates running as the "postgres" user.  Log in as
    "postgres" or use ssh to emulate Unix's "su" command.
[3] On Windows 2000, this starts the "Local Users and Groups" applet.
    On Windows NT 4.0, do the analogous operation.
[4] On Windows 2000, this starts the "Local Security Settings" applet.
    On Windows NT 4.0, do the analogous operation.
[5] Do not use rxvt for this step because the password exchange will not
    work properly.
[6] Clean postmaster shutdown will only work with a post Cygwin 1.3.2
    snapshot from 2001-Jul-28 or later.
[7] Cygwin's bin directory (e.g., C:\Cygwin\bin) must be added to the
    Windows NT/2000's system PATH and the machine rebooted for the SCM
    to find cygwin1.dll.
[8] Actually, psql can run under any user account.
[9] One can use PostgreSQL's createuser command or set PGUSER to obviate
    the need to specify "-U postgres" on the psql command line.

Source:

As configured, the PostgreSQL source builds OOTB under Cygwin with a few
Python, Java, and readline related caveats.  Hence, the source has been
patched to correct these issues.  I have submitted the following patches:

    http://fts.postgresql.org/db/mw/msg.html?mid=117271
    http://fts.postgresql.org/db/mw/msg.html?mid=119676 [*]
    http://fts.postgresql.org/db/mw/msg.html?mid=119660
    http://fts.postgresql.org/db/mw/msg.html?mid=121524 [*]

for consideration.  All of the above patches or functionally equivalent ones
(denoted by [*]) have been accepted in PostgreSQL CVS.  Hence, these minor
caveats will be resolved in PostgreSQL 7.2.

Additionally, a patch to fix the "Cannot rename init file" problem as
described in:

    http://archives.postgresql.org/pgsql-cygwin/2002-01/msg00018.php

has been applied too.  At the time is this writing, a functionally
equivalent patch is being accepted into PostgreSQL CVS to be included
in PostgreSQL 7.2.

I also added the following files to the source archive:

    CYGWIN-PATCHES/README
    CYGWIN-PATCHES/build.sh
    CYGWIN-PATCHES/postgresql.patch

and renamed the original source archive to match Cygwin's setup.exe
naming conventions.

To restore the PostgreSQL source to its original state, perform the
following:

    $ cd postgresql-7.1.3-2
    $ patch -R -p1 <CYGWIN-PATCHES/postgresql.patch
    $ autoconf
    $ rm -fr CYGWIN-PATCHES

Build:

This distribution has been configured as follows:

    configure --enable-multibyte --with-python --with-java --with-CXX --prefix=/usr --sysconfdir=/etc --docdir=/usr/doc/postgresql-$version

where $version is the PostgreSQL version (e.g., 7.1.3).

See CYGWIN-PATCHES/build.sh in the source archive for my exact build
recipe for configuring, making, and packaging this distribution.

Test:

On 9X/ME, it has been reported that Cygwin PostgreSQL hangs at random
places during the regression test.  Unfortunately, at the time of this
writing, no one has tracked down the root cause of these hangs.

Issues:

1. make check can generate spurious regression test failures due to overflowing
the the listen() backlog queue which generates connection refused errors.  Note
that make installcheck does not have this problem since it runs all tests
sequentially instead of in large concurrent groups.

2. Even though configured --with-python, plpython is not enabled.  If you need
this functionality, then you must build PostgreSQL CVS or wait for PostgreSQL
7.2.  Note that the following patch has already been accepted into PostgreSQL
CVS:

    http://fts.postgresql.org/db/mw/msg.html?mid=118071

3. It is recommended to delete all cygipc temporary files (/tmp/cygipc* and 
/tmp/MultiFile*) before starting postmaster under a different user account.
Otherwise, postmaster will fail to start due to IPC errors.

Homepage:

The primary PostgreSQL web site is:

    http://www.postgresql.org

Download:

The primary PostgreSQL ftp site is:

    ftp://ftp.postgresql.org

Mailing Lists:

Please report problems, suggestions, etc. dependent on their nature to one of
the following:

    pgsql-cygwin@postgresql.org
    cygwin@sources.redhat.com

Maintainer:

    Jason Tishler <jason@tishler.net>
