← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/start.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/start.sgml
 
1
<!-- doc/src/sgml/start.sgml -->
 
2
 
 
3
 <chapter id="tutorial-start">
 
4
  <title>Getting Started</title>
 
5
 
 
6
  <sect1 id="tutorial-install">
 
7
   <title>Installation</title>
 
8
 
 
9
   <para>
 
10
    Before you can use <productname>PostgreSQL</productname> you need
 
11
    to install it, of course.  It is possible that
 
12
    <productname>PostgreSQL</productname> is already installed at your
 
13
    site, either because it was included in your operating system
 
14
    distribution or because the system administrator already installed
 
15
    it.  If that is the case, you should obtain information from the
 
16
    operating system documentation or your system administrator about
 
17
    how to access <productname>PostgreSQL</productname>.
 
18
   </para>
 
19
 
 
20
   <para>
 
21
    If you are not sure whether <productname>PostgreSQL</productname>
 
22
    is already available or whether you can use it for your
 
23
    experimentation then you can install it yourself.  Doing so is not
 
24
    hard and it can be a good exercise.
 
25
    <productname>PostgreSQL</productname> can be installed by any
 
26
    unprivileged user; no superuser (<systemitem>root</systemitem>)
 
27
    access is required.
 
28
   </para>
 
29
 
 
30
   <para>
 
31
    If you are installing <productname>PostgreSQL</productname>
 
32
    yourself, then refer to <xref linkend="installation">
 
33
    for instructions on installation, and return to
 
34
    this guide when the installation is complete.  Be sure to follow
 
35
    closely the section about setting up the appropriate environment
 
36
    variables.
 
37
   </para>
 
38
 
 
39
   <para>
 
40
    If your site administrator has not set things up in the default
 
41
    way, you might have some more work to do.  For example, if the
 
42
    database server machine is a remote machine, you will need to set
 
43
    the <envar>PGHOST</envar> environment variable to the name of the
 
44
    database server machine.  The environment variable
 
45
    <envar>PGPORT</envar> might also have to be set.  The bottom line is
 
46
    this: if you try to start an application program and it complains
 
47
    that it cannot connect to the database, you should consult your
 
48
    site administrator or, if that is you, the documentation to make
 
49
    sure that your environment is properly set up.  If you did not
 
50
    understand the preceding paragraph then read the next section.
 
51
   </para>
 
52
  </sect1>
 
53
 
 
54
 
 
55
  <sect1 id="tutorial-arch">
 
56
   <title>Architectural Fundamentals</title>
 
57
 
 
58
   <para>
 
59
    Before we proceed, you should understand the basic
 
60
    <productname>PostgreSQL</productname> system architecture.
 
61
    Understanding how the parts of
 
62
    <productname>PostgreSQL</productname> interact will make this
 
63
    chapter somewhat clearer.
 
64
   </para>
 
65
 
 
66
   <para>
 
67
    In database jargon, <productname>PostgreSQL</productname> uses a
 
68
    client/server model.  A <productname>PostgreSQL</productname>
 
69
    session consists of the following cooperating processes
 
70
    (programs):
 
71
 
 
72
    <itemizedlist>
 
73
     <listitem>
 
74
      <para>
 
75
       A server process, which manages the database files, accepts
 
76
       connections to the database from client applications, and
 
77
       performs database actions on behalf of the clients.  The
 
78
       database server program is called
 
79
       <filename>postgres</filename>.
 
80
       <indexterm><primary>postgres</primary></indexterm>
 
81
      </para>
 
82
     </listitem>
 
83
 
 
84
     <listitem>
 
85
      <para>
 
86
       The user's client (frontend) application that wants to perform
 
87
       database operations.  Client applications can be very diverse
 
88
       in nature:  a client could be a text-oriented tool, a graphical
 
89
       application, a web server that accesses the database to
 
90
       display web pages, or a specialized database maintenance tool.
 
91
       Some client applications are supplied with the
 
92
       <productname>PostgreSQL</productname> distribution; most are
 
93
       developed by users.
 
94
      </para>
 
95
     </listitem>
 
96
 
 
97
    </itemizedlist>
 
98
   </para>
 
99
 
 
100
   <para>
 
101
    As is typical of client/server applications, the client and the
 
102
    server can be on different hosts.  In that case they communicate
 
103
    over a TCP/IP network connection.  You should keep this in mind,
 
104
    because the files that can be accessed on a client machine might
 
105
    not be accessible (or might only be accessible using a different
 
106
    file name) on the database server machine.
 
107
   </para>
 
108
 
 
109
   <para>
 
110
    The <productname>PostgreSQL</productname> server can handle
 
111
    multiple concurrent connections from clients.  To achieve this it
 
112
    starts (<quote>forks</quote>) a new process for each connection.
 
113
    From that point on, the client and the new server process
 
114
    communicate without intervention by the original
 
115
    <filename>postgres</filename> process.  Thus, the
 
116
    master server process is always running, waiting for
 
117
    client connections, whereas client and associated server processes
 
118
    come and go.  (All of this is of course invisible to the user.  We
 
119
    only mention it here for completeness.)
 
120
   </para>
 
121
  </sect1>
 
122
 
 
123
 
 
124
  <sect1 id="tutorial-createdb">
 
125
   <title>Creating a Database</title>
 
126
 
 
127
   <indexterm zone="tutorial-createdb">
 
128
    <primary>database</primary>
 
129
    <secondary>creating</secondary>
 
130
   </indexterm>
 
131
 
 
132
   <indexterm zone="tutorial-createdb">
 
133
    <primary>createdb</primary>
 
134
   </indexterm>
 
135
 
 
136
   <para>
 
137
    The first test to see whether you can access the database server
 
138
    is to try to create a database.  A running
 
139
    <productname>PostgreSQL</productname> server can manage many
 
140
    databases.  Typically, a separate database is used for each
 
141
    project or for each user.
 
142
   </para>
 
143
 
 
144
   <para>
 
145
    Possibly, your site administrator has already created a database
 
146
    for your use.  He should have told you what the name of your
 
147
    database is.  In that case you can omit this step and skip ahead
 
148
    to the next section.
 
149
   </para>
 
150
 
 
151
   <para>
 
152
    To create a new database, in this example named
 
153
    <literal>mydb</literal>, you use the following command:
 
154
<screen>
 
155
<prompt>$</prompt> <userinput>createdb mydb</userinput>
 
156
</screen>
 
157
    If this produces no response then this step was successful and you can skip over the
 
158
    remainder of this section.
 
159
   </para>
 
160
 
 
161
   <para>
 
162
    If you see a message similar to:
 
163
<screen>
 
164
createdb: command not found
 
165
</screen>
 
166
    then <productname>PostgreSQL</> was not installed properly.  Either it was not
 
167
    installed at all or your shell's search path was not set to include it.
 
168
    Try calling the command with an absolute path instead:
 
169
<screen>
 
170
<prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb mydb</userinput>
 
171
</screen>
 
172
    The path at your site might be different.  Contact your site
 
173
    administrator or check the installation instructions to
 
174
    correct the situation.
 
175
   </para>
 
176
 
 
177
   <para>
 
178
    Another response could be this:
 
179
<screen>
 
180
createdb: could not connect to database postgres: could not connect to server: No such file or directory
 
181
        Is the server running locally and accepting
 
182
        connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
 
183
</screen>
 
184
    This means that the server was not started, or it was not started
 
185
    where <command>createdb</command> expected it.  Again, check the
 
186
    installation instructions or consult the administrator.
 
187
   </para>
 
188
 
 
189
   <para>
 
190
    Another response could be this:
 
191
<screen>
 
192
createdb: could not connect to database postgres: FATAL:  role "joe" does not exist
 
193
</screen>
 
194
    where your own login name is mentioned.  This will happen if the
 
195
    administrator has not created a <productname>PostgreSQL</> user account
 
196
    for you.  (<productname>PostgreSQL</> user accounts are distinct from
 
197
    operating system user accounts.)  If you are the administrator, see
 
198
    <xref linkend="user-manag"> for help creating accounts.  You will need to
 
199
    become the operating system user under which <productname>PostgreSQL</>
 
200
    was installed (usually <literal>postgres</>) to create the first user
 
201
    account.  It could also be that you were assigned a
 
202
    <productname>PostgreSQL</> user name that is different from your
 
203
    operating system user name; in that case you need to use the <option>-U</>
 
204
    switch or set the <envar>PGUSER</> environment variable to specify your
 
205
    <productname>PostgreSQL</> user name.
 
206
   </para>
 
207
 
 
208
   <para>
 
209
    If you have a user account but it does not have the privileges required to
 
210
    create a database, you will see the following:
 
211
<screen>
 
212
createdb: database creation failed: ERROR:  permission denied to create database
 
213
</screen>
 
214
    Not every user has authorization to create new databases.  If
 
215
    <productname>PostgreSQL</productname> refuses to create databases
 
216
    for you then the site administrator needs to grant you permission
 
217
    to create databases.  Consult your site administrator if this
 
218
    occurs.  If you installed <productname>PostgreSQL</productname>
 
219
    yourself then you should log in for the purposes of this tutorial
 
220
    under the user account that you started the server as.
 
221
 
 
222
    <footnote>
 
223
     <para>
 
224
      As an explanation for why this works:
 
225
      <productname>PostgreSQL</productname> user names are separate
 
226
      from operating system user accounts.  When you connect to a
 
227
      database, you can choose what
 
228
      <productname>PostgreSQL</productname> user name to connect as;
 
229
      if you don't, it will default to the same name as your current
 
230
      operating system account.  As it happens, there will always be a
 
231
      <productname>PostgreSQL</productname> user account that has the
 
232
      same name as the operating system user that started the server,
 
233
      and it also happens that that user always has permission to
 
234
      create databases.  Instead of logging in as that user you can
 
235
      also specify the <option>-U</option> option everywhere to select
 
236
      a <productname>PostgreSQL</productname> user name to connect as.
 
237
     </para>
 
238
    </footnote>
 
239
   </para>
 
240
 
 
241
   <para>
 
242
    You can also create databases with other names.
 
243
    <productname>PostgreSQL</productname> allows you to create any
 
244
    number of databases at a given site.  Database names must have an
 
245
    alphabetic first character and are limited to 63 bytes in
 
246
    length.  A convenient choice is to create a database with the same
 
247
    name as your current user name.  Many tools assume that database
 
248
    name as the default, so it can save you some typing.  To create
 
249
    that database, simply type:
 
250
<screen>
 
251
<prompt>$</prompt> <userinput>createdb</userinput>
 
252
</screen>
 
253
   </para>
 
254
 
 
255
   <para>
 
256
    If you do not want to use your database anymore you can remove it.
 
257
    For example, if you are the owner (creator) of the database
 
258
    <literal>mydb</literal>, you can destroy it using the following
 
259
    command:
 
260
<screen>
 
261
<prompt>$</prompt> <userinput>dropdb mydb</userinput>
 
262
</screen>
 
263
    (For this command, the database name does not default to the user
 
264
    account name.  You always need to specify it.)  This action
 
265
    physically removes all files associated with the database and
 
266
    cannot be undone, so this should only be done with a great deal of
 
267
    forethought.
 
268
   </para>
 
269
 
 
270
   <para>
 
271
    More about <command>createdb</command> and <command>dropdb</command> can
 
272
    be found in <xref linkend="APP-CREATEDB"> and <xref linkend="APP-DROPDB">
 
273
    respectively.
 
274
   </para>
 
275
  </sect1>
 
276
 
 
277
 
 
278
  <sect1 id="tutorial-accessdb">
 
279
   <title>Accessing a Database</title>
 
280
 
 
281
   <indexterm zone="tutorial-accessdb">
 
282
    <primary>psql</primary>
 
283
   </indexterm>
 
284
 
 
285
   <para>
 
286
    Once you have created a database, you can access it by:
 
287
 
 
288
    <itemizedlist spacing="compact" mark="bullet">
 
289
     <listitem>
 
290
      <para>
 
291
       Running the <productname>PostgreSQL</productname> interactive
 
292
       terminal program, called <application><firstterm>psql</></application>, which allows you
 
293
       to interactively enter, edit, and execute
 
294
       <acronym>SQL</acronym> commands.
 
295
      </para>
 
296
     </listitem>
 
297
 
 
298
     <listitem>
 
299
      <para>
 
300
       Using an existing graphical frontend tool like
 
301
       <application>pgAdmin</application> or an office suite with
 
302
       <acronym>ODBC</> or <acronym>JDBC</> support to create and manipulate a
 
303
       database.  These possibilities are not covered in this
 
304
       tutorial.
 
305
      </para>
 
306
     </listitem>
 
307
 
 
308
     <listitem>
 
309
      <para>
 
310
       Writing a custom application, using one of the several
 
311
       available language bindings.  These possibilities are discussed
 
312
       further in <xref linkend="client-interfaces">.
 
313
      </para>
 
314
     </listitem>
 
315
    </itemizedlist>
 
316
 
 
317
    You probably want to start up <command>psql</command> to try
 
318
    the examples in this tutorial.  It can be activated for the
 
319
    <literal>mydb</literal> database by typing the command:
 
320
<screen>
 
321
<prompt>$</prompt> <userinput>psql mydb</userinput>
 
322
</screen>
 
323
    If you do not supply the database name then it will default to your
 
324
    user account name.  You already discovered this scheme in the
 
325
    previous section using <command>createdb</command>.
 
326
   </para>
 
327
 
 
328
   <para>
 
329
    In <command>psql</command>, you will be greeted with the following
 
330
    message:
 
331
<screen>
 
332
psql (&version;)
 
333
Type "help" for help.
 
334
 
 
335
mydb=&gt;
 
336
</screen>
 
337
    <indexterm><primary>superuser</primary></indexterm>
 
338
    The last line could also be:
 
339
<screen>
 
340
mydb=#
 
341
</screen>
 
342
    That would mean you are a database superuser, which is most likely
 
343
    the case if you installed <productname>PostgreSQL</productname>
 
344
    yourself.  Being a superuser means that you are not subject to
 
345
    access controls.  For the purposes of this tutorial that is not
 
346
    important.
 
347
   </para>
 
348
 
 
349
   <para>
 
350
    If you encounter problems starting <command>psql</command>
 
351
    then go back to the previous section.  The diagnostics of
 
352
    <command>createdb</command> and <command>psql</command> are
 
353
    similar, and if the former worked the latter should work as well.
 
354
   </para>
 
355
 
 
356
   <para>
 
357
    The last line printed out by <command>psql</command> is the
 
358
    prompt, and it indicates that <command>psql</command> is listening
 
359
    to you and that you can type <acronym>SQL</acronym> queries into a
 
360
    work space maintained by <command>psql</command>.  Try out these
 
361
    commands:
 
362
    <indexterm><primary>version</primary></indexterm>
 
363
<screen>
 
364
<prompt>mydb=&gt;</prompt> <userinput>SELECT version();</userinput>
 
365
                               version
 
366
 -----------------------------------------------------------------------
 
367
 PostgreSQL &version; on i586-pc-linux-gnu, compiled by GCC 2.96, 32-bit
 
368
(1 row)
 
369
 
 
370
<prompt>mydb=&gt;</prompt> <userinput>SELECT current_date;</userinput>
 
371
    date
 
372
------------
 
373
 2002-08-31
 
374
(1 row)
 
375
 
 
376
<prompt>mydb=&gt;</prompt> <userinput>SELECT 2 + 2;</userinput>
 
377
 ?column?
 
378
----------
 
379
        4
 
380
(1 row)
 
381
</screen>
 
382
   </para>
 
383
 
 
384
   <para>
 
385
    The <command>psql</command> program has a number of internal
 
386
    commands that are not SQL commands.  They begin with the backslash
 
387
    character, <quote><literal>\</literal></quote>.
 
388
    For example,
 
389
    you can get help on the syntax of various
 
390
    <productname>PostgreSQL</productname> <acronym>SQL</acronym>
 
391
    commands by typing:
 
392
<screen>
 
393
<prompt>mydb=&gt;</prompt> <userinput>\h</userinput>
 
394
</screen>
 
395
   </para>
 
396
 
 
397
   <para>
 
398
    To get out of <command>psql</command>, type:
 
399
<screen>
 
400
<prompt>mydb=&gt;</prompt> <userinput>\q</userinput>
 
401
</screen>
 
402
    and <command>psql</command> will quit and return you to your
 
403
    command shell. (For more internal commands, type
 
404
    <literal>\?</literal> at the <command>psql</command> prompt.)  The
 
405
    full capabilities of <command>psql</command> are documented in
 
406
    <xref linkend="app-psql">.  In this tutorial we will not use these
 
407
    features explicitly, but you can use them yourself when it is helpful.
 
408
   </para>
 
409
 
 
410
  </sect1>
 
411
 </chapter>