+ linkend="postmaster-start">).
+
+
Databases are created with the query language command
CREATE DATABASE:
linkend="user-attributes"> for how to grant permission.
-
-
Bootstrapping:
- Since you need to be connected to the database server in order to
- execute the CREATE DATABASE command, the
- question remains how the first database at any given
- site can be created. The first database is always created by the
- initdb command when the data storage area is
- initialized. (See .) By convention
- this database is called template1. So
- to create the first real database you can connect to
- template1.
-
-
+ Since you need to be connected to the database server in order to
+ execute the CREATE DATABASE command, the
+ question remains how the first database at any given
+ site can be created. The first database is always created by the
+ initdb command when the data storage area is
+ initialized. (See .) By convention
+ this database is called template1. So to create the
+ first real database you can connect to
+ template1.
+
The name template1
is no accident: When a new
This means that any changes you make in template1 are
propagated to all subsequently created databases. This implies that
you should not use the template database for real work, but when
- used judiciously this feature can be convenient. More details appear
- below.
+ used judiciously this feature can be convenient. More details
+ appear in .
As an extra convenience, there is also a program that you can
execute from the shell to create new databases,
- <filename>createdb.
+ <command>createdb.
createdb dbname
you want.
-
-
Template Databases
+
+ contains information about
+ how to restrict who can connect to a given database.
+
+
+
+ Sometimes you want to create a database for someone else. That
+ user should become the owner of the new database, so he can
+ configure and manage it himself. To achieve that, use one of the
+ following commands:
+CREATE DATABASE dbname OWNER username;
+
+ from the SQL environment, or
+createdb -O username dbname
+
+ You must be a superuser to be allowed to create a database for
+ someone else.
+
+
+
+
+
Template Databases
CREATE DATABASE actually works by copying an existing
will be copied into subsequently created user databases. This
behavior allows site-local modifications to the standard set of
objects in databases. For example, if you install the procedural
- language <literal>plpgsql in template1, it will
+ language <application>PL/pgSQL in template1, it will
automatically be available in user databases without any extra action
being taken when those databases are made.
additions that may now be present in template1.
+ To create a database by copying template0, use
+CREATE DATABASE dbname TEMPLATE template0;
+
+ from the SQL environment, or
+createdb -T template0 dbname
+
+ from the shell.
+
+
It is possible to create additional template databases, and indeed
one might copy any database in an installation by specifying its name
as the template for CREATE DATABASE. It is important to
understand, however, that this is not (yet) intended as
- a general-purpose COPY DATABASE
facility. In particular, it is
+ a general-purpose COPY DATABASE
facility. In particular, it is
essential that the source database be idle (no data-altering transactions
in progress)
for the duration of the copying operation. CREATE DATABASE
Two useful flags exist in pg_database for each
- database: datistemplate and
+ database: the columns datistemplate and
datallowconn. datistemplate
may be set to indicate that a database is intended as a template for
CREATE DATABASE. If this flag is set, the database may be
template1 and template0 do not have any special
status beyond the fact that the name template1 is the default
source database name for CREATE DATABASE and the default
- database-to-connect-to for various scripts such as >createdb.
+ database-to-connect-to for various programs such as >createdb.
For example, one could drop template1 and recreate it from
template0 without any ill effects. This course of action
might be advisable if one has carelessly added a bunch of junk in
template1.
+
+
+
+
Database Configuration
+
+ Recall from that the PostgreSQL
+ server provides a large number of run-time configuration variables.
+ You can set database-specific default values for many of these
+ settings.
+
-
+ For example, if for some reason you want to disable the
+
GEQO optimizer for a given database, you'd
+ ordinarily have to either disable it for all databases or make sure
+ that every connecting client is careful to issue SET geqo
+ TO off;. To make this setting the default you can
+ execute the command
+ALTER DATABASE mydb SET geqo TO off;
+
+ This will save the setting (but not set it immediately) and in
+ subsequent connections it will appear as though SET geqo
+ TO off; had been called right before the session started.
+ Note that users can still alter this setting during the session; it
+ will only be the default. To undo any such setting, use
+ ALTER DATABASE dbname RESET
+ varname;.
+
+
- id="manage-ag-alternate-locs">
-
Alternative Locations
+ id="manage-ag-alternate-locs">
+
Alternative Locations
It is possible to create a database in a location other than the
initialize the data area, and finally restart the server. (See
and
linkend="postmaster-start">.) To set an environment variable, type
-
PGDATA2=/home/postgres/data
export PGDATA2
-
in Bourne shells, or
-
setenv PGDATA2 /home/postgres/data
-
in
csh or tcsh. You have to make sure that this environment variable is always defined in the server environment, otherwise
you won't be able to access that database. Therefore you probably
already exists and is writable
by the user account that runs the server (see
linkend="postgres-user">). Then from the command line, type
-
initlocation PGDATA2
-
- Then you can restart the server.
+ (not initlocation
+ $PGDATA2). Then you can restart the server.
-
-
+++ /dev/null
-
-
-
-
Managing a Database
-
-
- This section is currently a thinly disguised copy of the
- Tutorial. Needs to be augmented.
- - thomas 1998-01-12
-
-
- Although the site administrator is responsible for overall management
- of the
PostgreSQL installation, some databases within the
- installation may be managed by another person,
- designated the database administrator.
- This assignment of responsibilities occurs when a database is created.
- A user may be assigned explicit privileges to create databases and/or to create new users.
- A user assigned both privileges can perform most administrative tasks
- within
PostgreSQL, but will
- not by default have the same operating system privileges as the site administrator.
-
-
- The Administrator's Guide covers these topics in
- more detail.
-
-
-
-
Database Creation
-
- Databases are created by the CREATE DATABASE
- command issued from within
- is a shell script provided to give the same functionality from the
- Unix command line.
-
-
- The
PostgreSQL backend must be running for either method
- to succeed, and the user issuing the command must be the
PostgreSQL- superuser or have been assigned database creation privileges by the
- superuser.
-
-
- To create a new database named mydb from the command line, type
-% createdb mydb
-
-
- and to do the same from within
psql type
-=> CREATE DATABASE mydb;
-
-
-
- If you do not have the privileges required to create a database, you will see
- the following:
-ERROR: CREATE DATABASE: Permission denied.
-
-
-
- You automatically become the
- database administrator of the database you just created.
- Database names must have an alphabetic first
- character and are limited to 63 characters in length.
-
PostgreSQL allows you to create any number of
- databases at a given site.
-
-
- The Administrator's Guide discusses database creation
- in more detail, including advanced options of the CREATE
- DATABASE command.
-
-
-
-
-
-
Accessing a Database
-
- Once you have constructed a database, you can access it
- by:
-
-
-
- Running the
PostgreSQL interactive
- terminal program, called
psql, which allows you
- to interactively enter, edit, and execute
-
-
-
-
- Using an existing graphical frontend tool like
-
ODBC) to create and manipulate a database.
- These possibilities are not covered in this tutorial.
-
-
-
-
- Writing a custom application, using one of the several
- available language bindings. These possibilities are discussed
- further in The PostgreSQL Programmer's
- Guide.
-
-
-
-
-You probably 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 psql &version;, the PostgreSQL interactive terminal.
-
-Type: \copyright for distribution terms
- \h for help with SQL commands
- \? for help on internal slash commands
- \g or terminate with semicolon to execute query
- \q to quit
-
-mydb=>
-
-
-
-This prompt indicates that psql is listening
- to you and that you can type
SQL queries into a
- work space maintained by the terminal monitor.
-The
psql program itself responds to special
-commands that begin
- with the backslash character, \. For example, you
- can get help on the syntax of various
-
PostgreSQL SQL commands by typing:
-mydb=> \h
-
-
- Once you have finished entering your queries into the
- work space, you can pass the contents of the work space
- to the
PostgreSQL server by typing:
-mydb=> \g
-
-
- This tells the server to process the query. If you
- terminate your query with a semicolon, the \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 myFile
-
-
- 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 \? at the psql
- 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 /* ... */.
-
-
-
-
-
-
Destroying a Database
-
- If you are the owner of the database
- mydb, you can destroy it using the SQL command
-=> DROP DATABASE mydb;
-
- or the Unix shell script
-% dropdb 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.
-
-
-
-
-
-
database cluster will contain a database named
template1. As the name suggests, this will be used
as a template for subsequently created databases; it should not be
- used for actual work.
+ used for actual work. (See for information
+ about creating databases.)
However, while the directory contents are secure, the default
- pg_hba.conf authentication method of
- trust allows any local user to connect to the
+ client authentication setup allows any local user to connect to the
database and even become the database superuser. If you don't trust
other local users, we recommend you use initdb's
or option to assign a
password to the database superuser. After initdb,
- modify pg_hba.conf to use md5 or
+ modify the pg_hba.conf file to use md5 or
password instead of trust authentication
before you start the server for the first time. (Other,
approaches include using ident authentication or
file system permissions to restrict connections. See
- linkend="client-authentication"> for more information.
+ linkend="client-authentication"> for more information.)
-
Database Users and P<span class="marked">ermission</span>s
+
Database Users and P<span class="marked">rivilege</span>s
- Managing database users and their privileges is in concept similar
- to managing the users of a Unix operating system, but the details
- are not identical.
+ Every database cluster contains a set of database users. Those
+ users are separate from the users managed by the operating system on
+ which the server runs. Users own database objects (for example,
+ tables) and can assign privileges on those objects to other users to
+ control who has access to which object.
+
+
+ This chapter describes how to create and manage users and introduces
+ the privilege system. More information about the various types of
+ database objects and the effects of privileges can be found in
+ &cite-user;.
name follows the rules for SQL
identifiers: either unadorned without special characters, or
double-quoted. To remove an existing user, use the analogous
- DROP USER command.
+ DROP USER command:
+
+DROP USER name
+
- For convenience, the shell scripts
createuser- and
dropuser are provided as wrappers around these SQL
- commands.
+ For convenience, the programs
createuser+ and
dropuser are provided as wrappers
+ around these SQL commands that can be called from the shell command
+ line:
+
+createuser name
+dropuser name
+
In order to bootstrap the database system, a freshly initialized
system always contains one predefined user. This user will have the
- fixed id 1, and by default (unless altered when running
+ fixed ID 1, and by default (unless altered when running
initdb) it will have the same name as
the operating system user that initialized the database
cluster. Customarily, this user will be named
- The user name to use for a particular database connection is
- indicated by the client that is initiating the connection request
- in an application-specific fashion. For example, the
-
psql program uses the
- command line option to indicate the user to connect as. The set of
- database users a given client connection may connect as is
- determined by the client authentication setup, as explained in
+ Exactly one user identity is active for a connection to the
+ database server. The user name to use for a particular database
+ connection is indicated by the client that is initiating the
+ connection request in an application-specific fashion. For example,
+ the
psql program uses the
+ command line option to indicate the user to
+ connect as. Many applications assume the name of the current
+ operating system user by default (including
+
createuser and psql). Therefore it+ is convenient to maintain a naming correspondence between the two
+ user sets.
+
+
+ The set of database users a given client connection may connect as
+ is determined by the client authentication setup, as explained in
. (Thus, a client is not
necessarily limited to connect as the user with the same name as
its operating system user, in the same way a person is not
- constrained in its login name by her real name.)
+ constrained in its login name by her real name.) Since the user
+ identity determines the set of privileges available to a connected
+ client, it is important to carefully configure this when setting up
+ a multiuser environment.
+
- id="user-attributes">
- User a</span>ttributes
+ id="user-attributes">
+ User A</span>ttributes
A database user may have a number of attributes that define its
See the reference pages for CREATE USER and
ALTER USER for details.
-
+
+ A user can also set personal defaults for many of the run-time
+ configuration settings described in
+ linkend="runtime-config">. For example, if for some reason you
+ want to disable index scans (hint: not a good idea) anytime you
+ connect, you can use
+ALTER USER myname SET enable_indexscan TO off;
+
+ This will save the setting (but not set it immediately) and in
+ subsequent connections it will appear as though SET geqo
+ TO off; had been called right before the session started.
+ You can still alter this setting during the session; it will only
+ be the default. To undo any such setting, use ALTER USER
+ username RESET varname;.
+
As in Unix, groups are a way of logically grouping users to ease
- management of permissions: permissions can be granted to, or revoked
+ management of privileges: privileges can be granted to, or revoked
from, a group as a whole. To create a group, use
CREATE GROUP name
server that other users may execute without knowing it. Hence, both
mechanisms permit users to Trojan horse
others with relative impunity. The only real protection is tight
- control over who can define functions (e.g., write to relations
- with SQL fields) and triggers. Audit trails and alerters on the
- system catalogs pg_class,
- pg_shadow and pg_group are also
- possible.
+ control over who can define functions.
system access controls. This is an inherent problem with
user-defined C functions.
-
&typeconv;
&indices;
&mvcc;
- &manage;
&perform;
projects / postgresql.git / commitdiff