shows how the Postgres distribution is laid out when installed in the default way. For simplicity, we will assume that Postgres has been installed in the directory /usr/local/pgsql. Therefore, wherever you see the directory /usr/local/pgsql you should substitute the name of the directory where Postgres is actually installed. All Postgres commands are installed in the directory /usr/local/pgsql/bin. Therefore, you should add this directory to your shell command path. If you use a variant of the Berkeley C shell, such as csh or tcsh, you would add set path = ( /usr/local/pgsql/bin path ) in the .login file in your home directory. If you use a variant of the Bourne shell, such as sh, ksh, or bash, then you would add PATH=/usr/local/pgsql/bin PATH export PATH to the .profile file in your home directory. From now on, we will assume that you have added the Postgres bin directory to your path. In addition, we will make frequent reference to "setting a shell variable" or "setting an environment variable" throughout this document. If you did not fully understand the last paragraph on modifying your search path, you should consult the UNIX manual pages that describe your shell before going any further. If your site administrator has not set things up in the default way, you may have some more work to do. For example, if the database server machine is a remote machine, you will need to set the PGHOST environment variable to the name of the database server machine. The environment variable PGPORT may also have to be set. The bottom line is this: if you try to start an application program and it complains that it cannot connect to the postmaster, you should immediately consult your site administrator to make sure that your environment is properly set up. Written by Oleg Bartunov. See Oleg's web page for additional information on locale and Russian language support. While doing a project for a company in Moscow, Russia, I encountered the problem that postgresql had no support of national alphabets. After looking for possible workarounds I decided to develop support of locale myself. I'm not a C-programer but already had some experience with locale programming when I work with perl (debugging) and glimpse. After several days of digging through the Postgres source tree I made very minor corections to src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed! I did support only for LC_CTYPE and LC_COLLATE, but later LC_MONETARY was added by others. I got many messages from people about this patch so I decided to send it to developers and (to my surprise) it was incorporated into postgresql distribution. People often complain that locale doesn't work for them. There are several common mistakes: Didn't properly configure postgresql before compilation. You must run configure with --enable-locale option to enable locale support. Didn't setup environment correctly when starting postmaster. You must define environment variables $LC_CTYPE and $LC_COLLATE before running postmaster because backend gets information about locale from environment. I use following shell script (runpostgres): #!/bin/sh export LC_CTYPE=koi8-r export LC_COLLATE=koi8-r postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' and run it from rc.local as /bin/su - postgres -c "/home/postgres/runpostgres" Broken locale support in OS (for example, locale support in libc under Linux several times has changed and this caused a lot of problems). Latest perl has also support of locale and if locale is broken perl -v will complain something like: 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist 8:18[mira]:~/WWW/postgres>perl -v perl: warning: Setting locale failed. perl: warning: Please check that your locale settings: LC_ALL = (unset), LC_CTYPE = "not_exist", LANG = (unset) are supported and installed on your system. perl: warning: Falling back to the standard locale ("C"). Wrong location of locale files! Possible location: /usr/lib/locale (Linux, Solaris), /usr/share/locale (Linux), /usr/lib/nls/loc (DUX 4.0) Check man locale for right place. Under Linux I did a symbolical link between /usr/lib/locale and /usr/share/locale to be sure next libc will not break my locale. You can use ~* and order by operators for strings contain characters from national alphabets. Non-english users definitely need that. If you won't use locale stuff just undefine USE_LOCALE variable. There is one evident drawback of using locale - it's speed ! So, use locale only if you really need it. Nothing can happen to a database unless the postmaster process is running. As the site administrator, there are a number of things you should remember before starting the postmaster. These are discussed in the section of this manual titled, "Administering Postgres." However, if Postgres has been installed by following the installation instructions exactly as written, the following simple command is all you should need to start the postmaster: % postmaster The postmaster occasionally prints out messages which are often helpful during troubleshooting. If you wish to view debugging messages from the postmaster, you can start it with the -d option and redirect the output to the log file: % postmaster -d >& pm.log & If you do not wish to see these messages, you can type % postmaster -S and the postmaster will be "S"ilent. Notice that there is no ampersand ("&") at the end of the last example. createuser enables specific users to access Postgres. destroyuser removes users and prevents them from accessing Postgres. Note that these commands only affect users with respect to Postgres; they have no effect on users other privileges or status with regards to the underlying operating system. It is possible to create a database in a location other than the default location for the installation. Remember that all database access actually occurs through the database backend, so that any location specified must be accessible by the backend. Either an absolute path name or an environment variable may be specified as a location. Note that for security and integrity reasons, all paths and environment variables so specified have some additional path fields appended. The environment variable style of specification is to be preferred since it allows the site administrator more flexibility in managing disk storage. Remember that database creation is actually performed by the database backend. Therefore, any environment variable specifying an alternate location must have been defined before the backend was started. To define an alternate location PGDATA2 pointing to /home/postgres/data, type % setenv PGDATA2 /home/postgres/data Usually, you will want to define this variable in the Postgres superuser's .profile or .cshrc initialization file to ensure that it is defined upon system startup. To create a data storage area in /home/postgres/data, ensure that /home/postgres already exists and is writable. From the command line, type % initlocation $PGDATA2 Creating Postgres database system directory /home/postgres/data Creating Postgres database system directory /home/postgres/data/base To test the new location, create a database test by typing % createdb -D PGDATA2 test % destroydb test Assuming that your site administrator has properly started the postmaster process and authorized you to use the database, you (as a user) may begin to start up applications. As previously mentioned, you should add /usr/local/pgsql/bin to your shell search path. In most cases, this is all you should have to do in terms of preparation. If you get the following error message from a Postgres command (such as psql or createdb): connectDB() failed: Is the postmaster running at 'localhost' on port '4322'? it is usually because either the postmaster is not running, or you are attempting to connect to the wrong server host. If you get the following error message: FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) it means that the site administrator started the postmaster as the wrong user. Tell him to restart it as the Postgres superuser. Now that Postgres is up and running we can create some databases to experiment with. Here, we describe the basic commands for managing a database. Let's say you want to create a database named mydb. You can do this with the following command: % createdb mydb Postgres allows you to create any number of databases at a given site and you automatically become the database administrator of the database you just created. Database names must have an alphabetic first character and are limited to 16 characters in length. Not every user has authorization to become a database administrator. If Postgres refuses to create databases for you, then the site administrator needs to grant you permission to create databases. Consult your site administrator if this occurs. Once you have constructed a database, you can access it by: running the Postgres terminal monitor programs ( monitor or psql) which allows you to interactively enter, edit, and execute SQL commands. writing a C program using the LIBPQ subroutine library. This allows you to submit SQL commands from C and get answers and status messages back to your program. This interface is discussed further in section ??. You might want to start up psql, to try out the examples in this manual. It can be activated for the mydb database by typing the command: % psql mydb You will be greeted with the following message: Welcome to the Postgres interactive sql monitor: 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: mydb mydb=> This prompt indicates that the terminal monitor is listening to you and that you can type SQL queries into a workspace maintained by the terminal monitor. The psql program responds to escape codes that begin with the backslash character, "\". For example, you can get help on the syntax of various Postgres SQL commands by typing: mydb=> \h Once you have finished entering your queries into the workspace, you can pass the contents of the workspace to the Postgres server by typing: mydb=> \g This tells the server to process the query. If you terminate your query with a semicolon, the backslash-g is not necessary. psql will automatically process semicolon terminated queries. To read queries from a file, say myFile, instead of entering them interactively, type: mydb=> \i fileName To get out of psql and return to UNIX, type mydb=> \q and psql will quit and return you to your command shell. (For more escape codes, type backslash-h at the monitor prompt.) White space (i.e., spaces, tabs and newlines) may be used freely in SQL queries. Single-line comments are denoted by --. Everything after the dashes up to the end of the line is ignored. Multiple-line comments, and comments within a line, are denoted by /* ... */ If you are the database administrator for the database mydb, you can destroy it using the following UNIX command: % destroydb mydb This action physically removes all of the UNIX files associated with the database and cannot be undone, so this should only be done with a great deal of forethought.