1.1 installation
Needless to say, you need to install it before using PostgreSQL. If PostgreSQL is pre-installed in your operating system or the system administrator has installed it, you need to get information on how to access PostgreSQL from the operating system's documentation or the system administrator.
If you are not sure whether PostgreSQL is already installed, or whether the installed PostgreSQL is available, then you can install it yourself. The installation of PostgreSQL is not difficult, and the installation itself is a good exercise opportunity. PostgreSQL can be installed by unprivileged users and does not require super user (root) access rights.
If you want to install PostgreSQL by yourself, please refer to the installation instructions in Chapter 15, and return to this instruction after the installation is complete. Be sure to set the relevant environment variables.
If your server's administrator installs PostgreSQL not in the default way, you need to do some extra work. For example, if the database server is on a remote computer, you need to set the PGHOST environment variable to the computer name of the database server, and the environment variable PGPORT may also need to be set. The most common is that if you start the application, but it cannot connect to the database, you should contact your system administrator immediately; if you are an administrator, then you should refer to the documentation to ensure that your environment variables are set correctly . If you are still unclear about the content mentioned above, please read the next section first.
1.2 Basic concepts of the system
First of all, you need to understand the basic architecture of the PostgreSQL system. Understanding the interrelationships between the various parts of the PostgreSQL system will make this chapter clearer.
PostgreSQL uses the client/server (C/S) model to provide services. A PostgreSQL session consists of the following related processes (programs):
(1) A server-side process. This process manages database files, accepts client connections to the database, and performs operations on the database on behalf of the client. The program name of this process is called postgres.
(2) Front-end applications, that is, client applications that require database operations. Client applications may themselves be diverse: they can be a character interface tool, a graphical interface application, or a web server that displays web pages by accessing a database, or a special database management tool . Some client applications are provided with the PostgreSQL release, but most of them are developed by users.
Like a typical client/server application (C/S application), the client and server can be on different hosts. At this point, they are connected via TCP/IP. You should keep this in mind, because the files that can be accessed on the client may not be accessible on the database server machine (or can only be accessed with a different file name).
The PostgreSQL server can handle multiple concurrent requests from clients. In order to be able to do this, it will start ("forks") a new process for each request, and then the client and the new server process will not communicate directly through the original postgres process. Therefore, the main process on the server side is always running, waiting for a connection from the client; and the client and the associated server-side process will only run when needed. (Of course, these are transparent to users, and I talk about them here for the sake of completeness.)
1.3 Create a database
The first example to test whether you can access the database server is to try to create a database, a PostgreSQL server can manage multiple databases, usually we will use a separate database for each project and each user.
Your system administrator may have created the database for you and has given you the name of the database. If this is the case, you can skip this step and skip to the next section
To create a new database named mydb (mydb in our example), you can use the following command:
$ createdb mydb
If no special information is displayed after the command is run, the command is successful, and you can skip the rest of this section.
If you see a message like the following
createdb: command not found
Then PostgreSQL is not installed properly. Either it is not installed at all, or your shell search path setting does not include it. Try calling the command with an absolute path:
$ /usr/local/pgsql/bin/createdb mydb
The path on your node may be different. Contact your administrator or see the installation instructions for the correct location.
Another response might look like this:
createdb: could not connect to database postgres: could not connect to server:
No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
This means that the server did not start, or did not start where createdb expected. Similarly, you should also check the installation instructions or find an administrator.
Another response might look like this:
createdb: could not connect to database postgres: FATAL: role "joe" does not exist
Your login account is mentioned here. If the administrator does not create a PostgreSQL user account for you, these phenomena will occur. (PostgreSQL user accounts are different from operating system user accounts.) If you are an administrator, refer to Chapter 20 for help in creating user accounts. You need to switch to the identity of the operating system user who installed PostgreSQL (usually postgres) to create the first user account. It is also possible that the PostgreSQL user name given to you is different from your operating system user name; in this case, you need to use the -U switch or use the PGUSER environment variable to declare your PostgreSQL user name.
If you have a database user account, but do not have the permissions required to create a database, then you will see the following prompt:
createdb: database creation failed: ERROR: permission denied to create database
Not all users are authorized to create new databases. If PostgreSQL refuses you to create a database, then you need to ask the node administrator to grant you the permission to create a database. When this happens, please consult your node administrator. If you have installed PostgreSQL yourself, you should log in as the user who started the database server and refer to the manual to complete the authorization work. [1]
You can also create databases with other names. PostgreSQL allows you to create any number of databases on a given node. The database name must start with a letter and be less than 63 characters long. A convenient way is to create a database with the same name as your current user name. Many tools will assume that the database name is the default database name, so you can save your keystrokes. To create such a database, just type
$ createdb
If you no longer want to use your database, then you can delete it. For example, if you are the owner (creator) of the database mydb, then you can delete it with the following command:
$ dropdb mydb
(For this command, the database name is not the default user name. So you must declare it.) This action physically deletes all files related to the database and cannot be cancelled, so be sure to do this before doing this Think clearly.
Information about createdb and dropdb can be found in separate sections of createdb and dropdb, respectively.
Note:
[1] Regarding the reason for this: the PostgreSQL user name is separate from the operating system user account. When you connect to a database, you can choose which PostgreSQL user name to connect with; if you do not choose, then the default is your current operating system account. If so, there is always a PostgreSQL user account with the same name as the operating system user to start the server, and usually this user has the permission to create a database. If you do not want to log in as this user, you can also specify a -U option anywhere to choose a PostgreSQL user name to connect to.
1.4 Access to the database
Once you have created a database, you can access it in the following ways;
- Run the PostgreSQL interactive terminal program psql, which allows you to enter, edit and execute SQL commands interactively.
- Use existing graphical front-end tools, such as Pgadmin or office suites with ODBC or JDBC support to create and manage databases. This method is not covered in this tutorial.
- Write a client application that uses one of multiple language bindings. These possibilities are discussed in more depth in Part IV.
You may want to start psql to try out the examples in this tutorial. You can enter the following command to start the mydb database:
$ psql mydb
If you do not provide a database name, it will default to your user account name. You already know how to use createdb in the previous section.
In psql, you will see the following information:
psql (9.1)
Type "help" for help.
mydb=>
The last line may also be
mydb=#
This prompt means that you are a database superuser, and the most likely cause of this situation is your own installation of PostgreSQL. Being a super user means you are not restricted by access control. For the purposes of this tutorial, it does not matter whether you are a super user.
If you encounter problems when starting psql, please go back to the previous section. The method of diagnosing createdb is very similar to the method of diagnosing psql. If the former works, the latter should also work.
The last line printed by psql is a prompt, which means that psql is listening to you. At this time, you can enter SQL query statements into a work area maintained by psql. Try the following command:
mydb=> SELECT version();
version
-----------------------------------------------------------------------
PostgreSQL 9.1 on i586-pc-linux-gnu, compiled by GCC 2.96, 32-bit
(1 row)
mydb=> SELECT current_date;
date
------------
2002-08-31
(1 row)
mydb=> SELECT 2 + 2;
?column?
----------
4
(1 row)
The psql program has some internal commands that are not SQL commands. They start with a backslash, "\". For example, you can use the following command to get the help syntax of various PostgreSQL SQL commands:
mydb=> \h
To exit psql, type
mydb=> \q
Then psql will exit and return you to the shell command line. (To get more information about internal commands, you can type \? at the psql prompt). The complete functionality of psql is documented in the psql documentation. If PostgreSQL is installed correctly, you can also type man psql at the shell prompt of the operating system to read the document. In this document, we will not explicitly use these features, but you can use them when appropriate.