INSTALL 12.3 KB
Newer Older
Marc G. Fournier's avatar
Marc G. Fournier committed
1
POSTGRESQL INSTALLATION INSTRUCTIONS
Marc G. Fournier's avatar
Marc G. Fournier committed
2 3
Copyright (c) 1996 Regents of the University of California

Marc G. Fournier's avatar
Marc G. Fournier committed
4
This directory contains the source and documentation for PostgreSQL
5
(version 6.1) PostgreSQL is a derivative of POSTGRES 4.2 (the last
6
release of the UC Berkeley research project).  For copyright terms for
Marc G. Fournier's avatar
Marc G. Fournier committed
7
PostgreSQL, please see the file named COPYRIGHT.  This version was
8 9 10 11 12
developed by a team of developers on the postgres developers mailing
list.  Version 1 (through 1.01) was developed by Jolly Chen and Andrew
Yu.


Marc G. Fournier's avatar
Marc G. Fournier committed
13
REQUIREMENTS TO RUN POSTGRESQL
14
------------------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
15

Marc G. Fournier's avatar
Marc G. Fournier committed
16
PostgreSQL has been tested on the following platforms:
Marc G. Fournier's avatar
Marc G. Fournier committed
17

18 19 20 21 22 23 24 25 26 27 28
   aix            IBM on AIX 3.2.5
   alpha          DEC Alpha AXP on OSF/1 2.0
   BSD44_derived  OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
   bsdi           BSD/OS 2.0, 2.01, 2.1
   dgux           DG/UX 5.4R3.10
   hpux           HP PA-RISC on HP-UX 9.0
   i386_solaris   i386 Solaris
   irix5          SGI MIPS on IRIX 5.3
   linux          Intel x86 on Linux 1.2 and Linux ELF
                  (For non-ELF Linux, see LINUX_ELF below).
   sparc_solaris  SUN SPARC on Solaris 2.4
29
   sunos4         SUN SPARC on SunOS 4.1.3
30 31
   svr4           Intel x86 on Intel SVR4
   ultrix4        DEC MIPS on Ultrix 4.4
Marc G. Fournier's avatar
Marc G. Fournier committed
32

33 34 35 36
PostgreSQL has known problems/bugs on the following platforms:

   nextstep       Motorola MC68K or Intel x86 on NeXTSTEP 3.2

Marc G. Fournier's avatar
Marc G. Fournier committed
37
PostgreSQL is also known to work on a number of other platforms that the
38
authors have not personally tested.
Marc G. Fournier's avatar
Marc G. Fournier committed
39 40 41 42 43

You should have at least 8 MB of memory and at least 30 MB of disk space to
hold the source, binaries, and user databases.


44
MIGRATING FROM POSTGRES VERSION 1.*
Marc G. Fournier's avatar
Marc G. Fournier committed
45
-----------------------------------
46

47
People migrating data from earlier releases must dump the data under
48
1.09 and reload them under 6.1.  The pg_dump utility is designed to do
49
this.  It is important you use 1.09 because earlier releases may not
50
have the proper copy format to load into the 6.1 database.
51

Marc G. Fournier's avatar
Marc G. Fournier committed
52
INSTALLING POSTGRESQL
53 54
---------------------

Marc G. Fournier's avatar
Marc G. Fournier committed
55
Installing PostgreSQL encompasses only installing the software on your system
56 57 58 59
so you can use it to access (or create or manipulate) databases.  This
step does not include actually creating any database or configuring your 
system to use it.

60 61 62 63
Before you start, if you are using GNU flex, you should ensure that you
are not using Version 2.5.3. If you have this version, you should either
change to 2.5.2 or 2.5.4 or apply the patch in doc/README.flex

Marc G. Fournier's avatar
Marc G. Fournier committed
64
To install PostgreSQL on UNIX platforms:
Marc G. Fournier's avatar
Marc G. Fournier committed
65

66
1. Unpack the source distribution into a source directory.  We'll assume
67
   "/usr/src/pgsql" in this discussion.  This should be a new directory.
68 69
  
2. Set your current directory to the source directory:
Marc G. Fournier's avatar
Marc G. Fournier committed
70

71
   cd /usr/src/pgsql
Marc G. Fournier's avatar
Marc G. Fournier committed
72

Marc G. Fournier's avatar
Marc G. Fournier committed
73
3. Build PostgreSQL:
Marc G. Fournier's avatar
Marc G. Fournier committed
74

Marc G. Fournier's avatar
Marc G. Fournier committed
75
   If you're installing PostgreSQL on Ultrix 4.x or Linux, see the 
Marc G. Fournier's avatar
Marc G. Fournier committed
76
   porting notes at the end for additional packages that you need to install
77
   before installing PostgreSQL.
Marc G. Fournier's avatar
Marc G. Fournier committed
78

79 80
   If using Linux or Irix, you should also read the machine-specific FAQs.

Marc G. Fournier's avatar
Marc G. Fournier committed
81 82 83 84 85 86 87
   Our Makefiles require GNU make (called gmake in this document) and
   also assume that "install" accepts BSD options. The INSTALL
   variable in the Makefiles is set to the BSD-compatible version of
   install. On some systems, you will have to find a BSD-compatible
   install to the location of this program. (eg. bsdinst, which comes
   with the MIT X Window System distribution) 

88
   In the simplest version, you can just do the following:
Marc G. Fournier's avatar
Marc G. Fournier committed
89 90

     % cd src
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
     % ./configure

   The configure program will list the template files available and ask
   you to choose one.  A lot of times, an appropriate template file is
   chosen for you, and you can just press Enter to accept the default.  If
   the default is not appropriate, then type in the appropriate template
   file and press Enter.  (If you do this, then send email to scrappy@hub.org
   stating the output of the program './config.guess' and what the template
   file should be.)

   Once you have entered the template file, you will be asked a number of
   questions about your particular configuration.  These can be skipped by
   adding parameters to the configure command above.  The following parameters
   can be tagged onto the end of the configure command:

     --prefix=BASEDIR	Selects a different base directory for the installation
			of the PostgreSQL configuration.  The default is
			/usr/local/pgsql

     --enable-hba	Enables Host Based Authentication

     --disable-hba	Disables Host Based Authentication

     --enable-locale	Enables USE_LOCALE

     --disable-locale	Disables USE_LOCALE
			
     --with-template=TEMPLATE
			Use template file TEMPLATE - the template files are
			assumed to be in the directory src/template, so look
			there for proper values. (If the configure script
			cannot find the specified template file, it will ask
			you for one).

     --with-pgport=PORT	Sets the port that the postmaster process listens
			for incoming connections on.  The default for this
			is port 5432.
			
   As an example, here is the configure script I use on a Sparc
   Solaris 2.5 system with /opt/postgres being the install base.

     % ./configure --prefix=/opt/postgres 
		--with-template=sparc_solaris-gcc --with-pgport=5432
		--enable-hba --disable-locale

   Of course, in a real shell, you would type these three lines all on the
   same line.

   After configure has completed running, you can make the binaries.  We use 
   'gmake' to mean GNU make.
    
Marc G. Fournier's avatar
Marc G. Fournier committed
142 143
     % gmake 

144
   The gmake ultimately issues the message "All of PostgreSQL is
Marc G. Fournier's avatar
Marc G. Fournier committed
145 146 147
   successfully made.  Ready to install."  If you don't get that, the make
   failed, and there should be error messages at the end detailing why.

Marc G. Fournier's avatar
Marc G. Fournier committed
148
4. Install PostgreSQL
149 150 151 152 153 154 155 156 157 158 159

   Installing just means placing all the files built in the previous step
   into their live locations on your system. 

     % gmake install

   This will narrate all the files being installed.  You should watch and 
   be sure the files are going to reasonable places and confirm for yourself
   that they ended up where they belong.

   Any error messages indicate something is wrong and you probably have to
Marc G. Fournier's avatar
Marc G. Fournier committed
160
   correct it before PostgreSQL will work.
161 162 163 164 165 166 167 168 169


HOW TO CREATE A DATABASE SYSTEM
-------------------------------

Once you have Postgres installed, you'll need at least one database system
on which to operate.  A database system is a collection of databases that
are used together and fall under a single authority.  You can have as many
database systems as you want on a single unix system.
Marc G. Fournier's avatar
Marc G. Fournier committed
170

171 172 173 174
You select a unix user to be the "postgres superuser" for a database
system and that user, for one thing, owns all the unix files that hold
all the data for that database system.  It is usually a good idea to create
a user for the sole purpose of being a postgres superuser.
Marc G. Fournier's avatar
Marc G. Fournier committed
175

Marc G. Fournier's avatar
Marc G. Fournier committed
176
WARNING: PostgreSQL is not secure.  Anyone who can connect to a database
177 178 179
system can easily assume all the unix privileges of its Postgres
superuser.  The simplest way is by creating and running a C language
function.  There are plans to remedy this in future developent.
Marc G. Fournier's avatar
Marc G. Fournier committed
180

181
The program initdb (part of Postgres) is what initializes (creates) a
182 183
database system.  Initdb uses the defaults specified in Makefile.global
or Makefile.custom. See the man page for initdb for more information.
Marc G. Fournier's avatar
Marc G. Fournier committed
184

185
  % initdb --pgdata=/usr/local/pgsql/data --pglib=/usr/local/pgsql/lib
Marc G. Fournier's avatar
Marc G. Fournier committed
186

187 188 189
By default, the user issuing the initdb command becomes the Postgres
superuser, and only the unix superuser can specify any other user as the
Postgres superuser.
Marc G. Fournier's avatar
Marc G. Fournier committed
190

191 192
Setting up Permissions
----------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
193

194 195
The first thing you should do after creating a database system is set up
the permissions for connecting to the database.  These are kept in the 
Bruce Momjian's avatar
Bruce Momjian committed
196
file pg_hba.conf in the lib directory.  Initdb creates a sample version of
197
this file, which contains comments telling you how to set it up.
Marc G. Fournier's avatar
Marc G. Fournier committed
198

199 200
The Postmaster Daemon
---------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
201

202 203 204 205
Finally, in order to use the database system, you'll need to have a
postmaster daemon running.  There is one postmaster process per database
system.  The postmaster runs the program "postgres" and must run as the
Postgres superuser.  See the postgres man page.
Marc G. Fournier's avatar
Marc G. Fournier committed
206

207 208
So, for example, you can login as the Postgres superuser and issue the
command:
Marc G. Fournier's avatar
Marc G. Fournier committed
209

210
  $ nohup postmaster -D/usr/local/pgsql/data >server.log 2>&1 &
211

212 213
This says to run the postmaster against the database system created
above.
214 215 216 217 218

This is a good daemon to start via system startup scripts, using su (be
careful NOT to run the postmaster as the unix superuser by mistake).


Marc G. Fournier's avatar
Marc G. Fournier committed
219
TESTING POSTGRESQL
220 221 222 223 224 225 226
------------------

We suggest you run the regression tests to make sure the release was
installed successfully and works as designed in your environment.  The
regression tests can be found in src/test/regress. (see
src/test/regress/README for more details)

227
     % cd /usr/src/pgsql/src/test/regress
Marc G. Fournier's avatar
Marc G. Fournier committed
228 229
     % gmake all runtest

230
This will run a whole slew of regression tests and might take an hour
231 232 233 234
to run.  When it's done, the output is in the file obj/regress.out.  You
can compare this to a sample run that we supply in the file
sample.regress.out. (You should get roughly the same output except for
some pathnames.)
Marc G. Fournier's avatar
Marc G. Fournier committed
235

236
     % diff expected.out regress.out
237

Marc G. Fournier's avatar
Marc G. Fournier committed
238
PLAYING WITH POSTGRESQL
239
-----------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
240

Marc G. Fournier's avatar
Marc G. Fournier committed
241
After PostgreSQL is installed, a database system is created, a postmaster
242
daemon is running, and the regression tests have passed, you'll want to 
Marc G. Fournier's avatar
Marc G. Fournier committed
243 244
see PostgreSQL do something.  That's easy.  Invoke the interactive interface
to PostgreSQL, psql, and start typing SQL:
Marc G. Fournier's avatar
Marc G. Fournier committed
245

246
  $ psql template1
Marc G. Fournier's avatar
Marc G. Fournier committed
247

248 249 250
(psql has to open a particular database, but at this point the only one
that exists is the template1 database, which always exists.  We will connect
to it only long enough to create another one and switch to it).
Marc G. Fournier's avatar
Marc G. Fournier committed
251

252
The response from psql is:
Marc G. Fournier's avatar
Marc G. Fournier committed
253 254 255 256

  type \? for help on slash commands
  type \q to quit
  type \g or terminate with semicolon to execute query
257
You are currently connected to the database: template1
Marc G. Fournier's avatar
Marc G. Fournier committed
258

259
template1=> 
Marc G. Fournier's avatar
Marc G. Fournier committed
260

261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287
Create the database foo:

template1=> CREATE DATABASE FOO;
INSERT 773248

(Don't ever forget those SQL semicolons.  Psql won't execute anything until it
sees the semicolon).

template1=> \c foo
closing connection to database: template1
connecting to new database: foo

(\ commands aren't SQL, so no semicolon.  Use \? to see all the \ commands).

template1=> CREATE TABLE bar (column1 int4, column2 char16);
CREATE

template1=> \d bar

...

You get the idea.



QUESTIONS? BUGS? FEEDBACK?
--------------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
288

289 290
First, please read the Frequently Asked Questions and answers in the file
called FAQ.
Marc G. Fournier's avatar
Marc G. Fournier committed
291

292 293
If you still have questions, please send them to:
questions@postgreSQL.org
Marc G. Fournier's avatar
Marc G. Fournier committed
294 295

If you have a bug report to make, please send a filled out version of
296
the file named "bug.template" to bugs@postgreSQL.org.
Marc G. Fournier's avatar
Marc G. Fournier committed
297 298

If you would like to help out with the development and maintenance of
Marc G. Fournier's avatar
Marc G. Fournier committed
299
PostgreSQL, send subscribe to the developers mailing list.  See
Marc G. Fournier's avatar
Marc G. Fournier committed
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325
README.support for more information

----------------------------------------------------------------------

Porting Notes:
-------------
Ultrix4.x:
	You need to install the libdl-1.1 package since Ultrix 4.x doesn't
	have a dynamic loader. It's available in
	   s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z

Linux:
	The linux port defaults to the ELF binary format. (Note that if you're
	using ELF, you don't need dld because you'll be using the dl library
	that comes with Linux ELF instead.)

	To compile on non-ELF Linux, comment out the LINUX_ELF line in
	src/mk/port/postgres.mk.linux. Also, the dld library MUST be obtained
	and installed on the system. It enables dynamic link loading capability
	to the postgres port. The dld library can be obtained from the sunsite
	linux distributions. The current name is dld-3.2.5.
				(Jalon Q. Zimmerman 
				<sneaker@powergrid.electriciti.com> 5/11/95)

	To compile with flex, you need a recent version (2.5.2 or
	later). Otherwise, you will get a 'yy_flush_buffer' undefined error.
Marc G. Fournier's avatar
Marc G. Fournier committed
326
        Note, however, that flex v2.5.3 has a bug. See the FAQs.
Marc G. Fournier's avatar
Marc G. Fournier committed
327 328 329 330 331 332 333 334 335 336

BSD/OS:
	For BSD/OS 2.0 and 2.01, you will need to get flex version 2.5.2
	as well as the GNU dld library.  Flex version 2.5.3 has a known bug.

NeXT: 
	The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
	It requires a SysV IPC emulation library and header files for 
        shared libary and semaphore stuff.   Tom just happens to sell such 
        a product so contact him for information.  He has also indicated that
Marc G. Fournier's avatar
Marc G. Fournier committed
337
        binary releases of PostgreSQL for NEXTSTEP will be made available to
Marc G. Fournier's avatar
Marc G. Fournier committed
338
        the general public.  Contact Info@RnA.nl for information.