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 5
This directory contains the source and documentation for PostgreSQL
(version 1.09) 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

	alpha		-	DEC Alpha AXP on OSF/1 2.0
	hpux		-	HP PA-RISC on HP-UX 9.0
	i386_solaris	-	i386 Solaris
	sparc_solaris	-	SUN SPARC on Solaris 2.4
	sparc		-	SUN SPARC on SunOS 4.1.3
	ultrix4		-	DEC MIPS on Ultrix 4.4
24
	linux		-	Intel x86 on Linux 1.2 (or above) ELF or a.out
Marc G. Fournier's avatar
Marc G. Fournier committed
25 26 27 28
	BSD44_derived	-	OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
        bsdi            -       BSD/OS 2.0 and 2.01
        bsdi_2_1        -       BSD/OS 2.1
	aix		-	IBM on AIX 3.2.5
29
	irix5		-	SGI MIPS on IRIX 5.3 
Marc G. Fournier's avatar
Marc G. Fournier committed
30 31 32 33 34 35
	dgux            -       DG/UX 5.4R3.10
  Some hooks are provided for
	svr4		-	Intel x86 on Intel SVR4
	next		-	Motorola MC68K or Intel x86 on NeXTSTEP 3.2
  but these are guaranteed not to work as of yet.

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

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.


Marc G. Fournier's avatar
Marc G. Fournier committed
43 44
MIGRATING FROM POSTGRES VERSION 1.0
-----------------------------------
45

46 47 48 49 50
Version 1.01 and 1.02 (and above) are mostly backward compatible with Version
1.0, but the database format is incompatible, so if you have databases that
you use with Version 1, you need to convert them before you can use them with
Version 1.02.  Once you do that, you won't be able to use them with Version 1
anymore.
Marc G. Fournier's avatar
Marc G. Fournier committed
51

52 53
For details on how to do this conversion, see the files doc/MIGRATION_1.0_to_1.01
and MIGRATION_to_1.02.1
54 55


Marc G. Fournier's avatar
Marc G. Fournier committed
56
INSTALLING POSTGRESQL
57 58
---------------------

Marc G. Fournier's avatar
Marc G. Fournier committed
59
Installing PostgreSQL encompasses only installing the software on your system
60 61 62 63
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.

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 67 68 69
1. Unpack the source distribution into a source directory.  We'll assume
   "/usr/src/postgres95" in this discussion.  This should be a new directory.
  
2. Set your current directory to the source directory:
Marc G. Fournier's avatar
Marc G. Fournier committed
70

71
   cd /usr/src/postgres95
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 88
   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) 

   Customization can be done by editing src/Makefile.global. You may change
Marc G. Fournier's avatar
Marc G. Fournier committed
89
   the various configuration options here, such as where the PostgreSQL
Marc G. Fournier's avatar
Marc G. Fournier committed
90 91 92 93
   executable files are installed and where postgres looks for the database
   directory.  The configuration switches are fairly self-explanatory, but we
   will go over some of the more commonly-changed options:

94 95
     - PORTNAME specifies the platform on which PostgreSQL is being built.
       This is set to UNDEFINED. You will need to change it to reflect
96
       your platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris
97
       2.4, ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0, etc.)
Marc G. Fournier's avatar
Marc G. Fournier committed
98

99 100
     - SRCDIR specifies where the source files are located. (defaults to
       $(POSTGRESDIR)/src.)
Marc G. Fournier's avatar
Marc G. Fournier committed
101

Marc G. Fournier's avatar
Marc G. Fournier committed
102
     - POSTGRESDIR specifies the top-level directory where PostgreSQL
103
       binaries, header files, libraries, and databases are installed.
Marc G. Fournier's avatar
Marc G. Fournier committed
104

105 106 107 108 109
     - NAMEDATALEN and OIDNAMELEN allows you to set the maximum length of
       system identifiers (table names, function names, etc.)  It
       defaults to 32.  You may alter this if you like, but be aware that
       databases created with different NAMEDATALEN's do not
       interoperate.
Marc G. Fournier's avatar
Marc G. Fournier committed
110

111 112
     - USE_READLINE specifies whether you want to use the GNU readline and
       history libraries for the psql interactive frontend program.  GNU
Marc G. Fournier's avatar
Marc G. Fournier committed
113
       readline is not supplied with PostgreSQL and can be found in the
114
       usual ftp sites for GNU software.
Marc G. Fournier's avatar
Marc G. Fournier committed
115

116
     - HBA specifies whether you wish to use host-based authentication
Marc G. Fournier's avatar
Marc G. Fournier committed
117
       for PostgreSQL.  See the section "How to Create a Database System"
118
       for how to set up the HBA permissions if you decide to use HBA.
Marc G. Fournier's avatar
Marc G. Fournier committed
119

Marc G. Fournier's avatar
Marc G. Fournier committed
120
   After editing src/Makefile.global, you are ready to compile PostgreSQL
121
   (it takes about 10 minutes on a 133Mhz Pentium running linux):
Marc G. Fournier's avatar
Marc G. Fournier committed
122 123 124 125

     % cd src
     % gmake 

126
   The gmake ultimately issues the message "All of Postgres95 is
Marc G. Fournier's avatar
Marc G. Fournier committed
127 128 129
   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
130
4. Install PostgreSQL
131 132 133 134 135 136 137 138 139 140 141

   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
142
   correct it before PostgreSQL will work.
143 144 145 146 147 148 149 150 151


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
152

153 154 155 156
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
157

Marc G. Fournier's avatar
Marc G. Fournier committed
158
WARNING: PostgreSQL is not secure.  Anyone who can connect to a database
159 160 161
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
162

163
The program initdb (part of Postgres) is what initializes (creates) a
Bruce Momjian's avatar
Bruce Momjian committed
164 165
database system.  Initdb uses the defaults specified in Makefile.global.
See the man page for initdb for more information.
Marc G. Fournier's avatar
Marc G. Fournier committed
166

167
  % initdb
Marc G. Fournier's avatar
Marc G. Fournier committed
168

169 170 171
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
172

173 174
Setting up Permissions
----------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
175

176 177 178 179
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 
file pg_hba in the data directory.  Initdb creates a sample version of
this file, which contains comments telling you how to set it up.
Marc G. Fournier's avatar
Marc G. Fournier committed
180

181 182
The Postmaster Daemon
---------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
183

184 185 186 187
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
188

189 190
So, for example, you can login as the Postgres superuser and issue the
command:
Marc G. Fournier's avatar
Marc G. Fournier committed
191

192
  % postmaster -S -D/usr/lib/postgres/postgres_data -p5432
193 194 195 196 197 198 199 200 201 202

This says to run the postmaster against the database system created above,
to accept connections from users on the conventional TCP port 5432, and
(-S) to run in the background without issuing messages about normal 
execution.

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
203
TESTING POSTGRESQL
204 205 206 207 208 209 210 211
------------------

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)

     % cd /usr/src/postgres95/src/test/regress
Marc G. Fournier's avatar
Marc G. Fournier committed
212 213
     % gmake all runtest

214 215 216 217 218
This will run a whole slew of regression tests and might take a long time
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
219 220 221

     % diff obj/regress.out sample.regress.out

222 223 224 225
The regression test takes about half an hour to run on a Sparc 10.  You
may want to use 'grep -v' to remove unsignificant differences.


Marc G. Fournier's avatar
Marc G. Fournier committed
226
PLAYING WITH POSTGRESQL
227
-----------------------
Marc G. Fournier's avatar
Marc G. Fournier committed
228

Marc G. Fournier's avatar
Marc G. Fournier committed
229
After PostgreSQL is installed, a database system is created, a postmaster
230
daemon is running, and the regression tests have passed, you'll want to 
Marc G. Fournier's avatar
Marc G. Fournier committed
231 232
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
233

234
  % psql -p 5432 template1
Marc G. Fournier's avatar
Marc G. Fournier committed
235

236 237 238
(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
239

240 241 242
Note that we have told psql to connect to Port 5432, which is what we told
the postmaster to listen on when we started it above.

243
The response from psql is:
Marc G. Fournier's avatar
Marc G. Fournier committed
244 245 246 247

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

250
template1=> 
Marc G. Fournier's avatar
Marc G. Fournier committed
251

252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278
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
279

280 281
First, please read the Frequently Asked Questions and answers in the file
called FAQ.
Marc G. Fournier's avatar
Marc G. Fournier committed
282 283

If you still have questions, please send them to
284
postgres95@postgres95.vnet.net.
Marc G. Fournier's avatar
Marc G. Fournier committed
285 286 287 288 289

If you have a bug report to make, please send a filled out version of
the file named "bug.template" to pg95-dev@ki.net.

If you would like to help out with the development and maintenance of
Marc G. Fournier's avatar
Marc G. Fournier committed
290
PostgreSQL, send subscribe to the developers mailing list.  See
Marc G. Fournier's avatar
Marc G. Fournier committed
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316
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
317
        Note, however, that flex v2.5.3 has a bug. See the FAQs.
Marc G. Fournier's avatar
Marc G. Fournier committed
318 319 320 321 322 323 324 325 326 327

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
328
        binary releases of PostgreSQL for NEXTSTEP will be made available to
Marc G. Fournier's avatar
Marc G. Fournier committed
329 330 331
        the general public.  Contact Info@RnA.nl for information.