332 lines
12 KiB
Plaintext
332 lines
12 KiB
Plaintext
POSTGRESQL INSTALLATION INSTRUCTIONS
|
|
Copyright (c) 1996 Regents of the University of California
|
|
|
|
This directory contains the source and documentation for PostgreSQL
|
|
(version 1.09) PostgreSQL is a derivative of POSTGRES 4.2 (the last
|
|
release of the UC Berkeley research project). For copyright terms for
|
|
PostgreSQL, please see the file named COPYRIGHT. This version was
|
|
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.
|
|
|
|
|
|
REQUIREMENTS TO RUN POSTGRESQL
|
|
------------------------------
|
|
|
|
PostgreSQL has been tested on the following platforms:
|
|
|
|
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
|
|
linux - Intel x86 on Linux 1.2 (or above) ELF or a.out
|
|
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
|
|
irix5 - SGI MIPS on IRIX 5.3
|
|
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.
|
|
|
|
PostgreSQL is also known to work on a number of other platforms that the
|
|
authors have not personally tested.
|
|
|
|
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.
|
|
|
|
|
|
MIGRATING FROM POSTGRES VERSION 1.0
|
|
-----------------------------------
|
|
|
|
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.
|
|
|
|
For details on how to do this conversion, see the files doc/MIGRATION_1.0_to_1.01
|
|
and MIGRATION_to_1.02.1
|
|
|
|
|
|
INSTALLING POSTGRESQL
|
|
---------------------
|
|
|
|
Installing PostgreSQL encompasses only installing the software on your system
|
|
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.
|
|
|
|
To install PostgreSQL on UNIX platforms:
|
|
|
|
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:
|
|
|
|
cd /usr/src/postgres95
|
|
|
|
3. Build PostgreSQL:
|
|
|
|
If you're installing PostgreSQL on Ultrix 4.x or Linux, see the
|
|
porting notes at the end for additional packages that you need to install
|
|
before installing PostgreSQL.
|
|
|
|
If using Linux or Irix, you should also read the machine-specific FAQs.
|
|
|
|
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
|
|
the various configuration options here, such as where the PostgreSQL
|
|
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:
|
|
|
|
- PORTNAME specifies the platform on which PostgreSQL is being built.
|
|
This is set to UNDEFINED. You will need to change it to reflect
|
|
your platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris
|
|
2.4, ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0, etc.)
|
|
|
|
- SRCDIR specifies where the source files are located. (defaults to
|
|
$(POSTGRESDIR)/src.)
|
|
|
|
- POSTGRESDIR specifies the top-level directory where PostgreSQL
|
|
binaries, header files, libraries, and databases are installed.
|
|
|
|
- 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.
|
|
|
|
- USE_READLINE specifies whether you want to use the GNU readline and
|
|
history libraries for the psql interactive frontend program. GNU
|
|
readline is not supplied with PostgreSQL and can be found in the
|
|
usual ftp sites for GNU software.
|
|
|
|
- HBA specifies whether you wish to use host-based authentication
|
|
for PostgreSQL. See the section "How to Create a Database System"
|
|
for how to set up the HBA permissions if you decide to use HBA.
|
|
|
|
After editing src/Makefile.global, you are ready to compile PostgreSQL
|
|
(it takes about 10 minutes on a 133Mhz Pentium running linux):
|
|
|
|
% cd src
|
|
% gmake
|
|
|
|
The gmake ultimately issues the message "All of Postgres95 is
|
|
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.
|
|
|
|
4. Install PostgreSQL
|
|
|
|
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
|
|
correct it before PostgreSQL will work.
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
WARNING: PostgreSQL is not secure. Anyone who can connect to a database
|
|
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.
|
|
|
|
The program initdb (part of Postgres) is what initializes (creates) a
|
|
database system. Initdb uses the defaults specified in Makefile.global.
|
|
See the man page for initdb for more information.
|
|
|
|
% initdb
|
|
|
|
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.
|
|
|
|
Setting up Permissions
|
|
----------------------
|
|
|
|
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.
|
|
|
|
The Postmaster Daemon
|
|
---------------------
|
|
|
|
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.
|
|
|
|
So, for example, you can login as the Postgres superuser and issue the
|
|
command:
|
|
|
|
% postmaster -S -D/usr/lib/postgres/postgres_data -p5432
|
|
|
|
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).
|
|
|
|
|
|
TESTING POSTGRESQL
|
|
------------------
|
|
|
|
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
|
|
% gmake all runtest
|
|
|
|
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.)
|
|
|
|
% diff obj/regress.out sample.regress.out
|
|
|
|
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.
|
|
|
|
|
|
PLAYING WITH POSTGRESQL
|
|
-----------------------
|
|
|
|
After PostgreSQL is installed, a database system is created, a postmaster
|
|
daemon is running, and the regression tests have passed, you'll want to
|
|
see PostgreSQL do something. That's easy. Invoke the interactive interface
|
|
to PostgreSQL, psql, and start typing SQL:
|
|
|
|
% psql -p 5432 template1
|
|
|
|
(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).
|
|
|
|
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.
|
|
|
|
The response from psql is:
|
|
|
|
type \? for help on slash commands
|
|
type \q to quit
|
|
type \g or terminate with semicolon to execute query
|
|
You are currently connected to the database: template1
|
|
|
|
template1=>
|
|
|
|
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?
|
|
--------------------------
|
|
|
|
First, please read the Frequently Asked Questions and answers in the file
|
|
called FAQ.
|
|
|
|
If you still have questions, please send them to
|
|
postgres95@postgres95.vnet.net.
|
|
|
|
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
|
|
PostgreSQL, send subscribe to the developers mailing list. See
|
|
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.
|
|
Note, however, that flex v2.5.3 has a bug. See the FAQs.
|
|
|
|
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
|
|
binary releases of PostgreSQL for NEXTSTEP will be made available to
|
|
the general public. Contact Info@RnA.nl for information.
|
|
|
|
|