diff options
Diffstat (limited to '')
| -rw-r--r-- | debian/README.Debian | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/debian/README.Debian b/debian/README.Debian new file mode 100644 index 0000000..f8966a9 --- /dev/null +++ b/debian/README.Debian @@ -0,0 +1,160 @@ +PostgreSQL for Debian +===================== + +PostgreSQL is a fully featured object-relational database management system. It +supports a large part of the SQL standard and is designed to be extensible by +users in many aspects. Its features include ACID transactions, foreign keys, +views, sequences, subqueries, triggers, outer joins, multiversion concurrency +control, and user-defined types and functions. + +Since the on-disk data format of all major PostgreSQL versions (like 9.6, +11, etc.) is incompatible to each other, Debian's PostgreSQL packaging +architecture is designed to maintain clusters of different major versions in +parallel. + +This postgresql-common package provides the common infrastructure and all +frontend programs that users and administrators use. The version specific +server and client programs are shipped in postgresql-*-<version> packages. + +For a detailed description of the architecture, please see + + /usr/share/doc/postgresql-common/architecture.html + +First steps for the impatient +----------------------------- +Eventually you will not get around reading at least some parts of the manual, +but if you want to get straight into playing SQL, here are the steps to create +a database user and a database for the Unix user 'joe': + +1. Install a database server with the major version of your choice + ('postgresql-XY', e. g. 'postgresql-11'). Preferably the latest + version, which you can get by installing the metapackage + 'postgresql'. This will automatically create a default cluster + 'main' with the database superuser 'postgres'. + +2. Get a shell for the database superuser 'postgres'. If your system + has an active root user, use su: + + # su -s /bin/bash postgres + + If your system uses sudo to get administrative rights, use sudo instead: + + joe$ sudo -u postgres bash + +3. In this postgres shell, create a database user with the same name as your + Unix login: + + $ createuser -DRS joe + + For details about the options, see createuser(1). + +4. Create a database "joework" which is owned by "joe": + + $ createdb -O joe joework + + For details about the options, see createdb(1). + +5. Exit the postgres shell. + +6. As user joe, you should now be able to connect to your database with + + $ psql joework + +Cluster management +------------------ +For managing clusters, the following commands are provided (each with its own +manual page): + + pg_createcluster - Create a new cluster or integrate an existing one into + the postgresql-common architecture. + pg_dropcluster - Completely remove a cluster. + pg_ctlcluster - Control the server process of a cluster (start, stop, + restart). + pg_lsclusters - Show a list of all existing clusters and their status. + pg_upgradecluster - Migrate a cluster from one major version to another one. + pg_renamecluster - Rename a cluster. + +Please note that you can of course also use the upstream tools for +creating clusters, such as initdb(1). However, please note that in +this case you cannot expect *any* of above pg_* tools to work, since +they use different configuration settings (SSL, data directories, +etc.) and file locations (e. g. +/etc/postgresql/11/main/postgresql.conf). If in doubt, then do *not* +use initdb, but only pg_createcluster. Since merely installing +postgresql-NN will already set up a default cluster which is ready to +work, most people do not need to bother about initdb or +pg_createcluster at all. + +Port assignment +--------------- +Please note that the pg_* tools automatically manage the server ports +unless you specify them manually. The first cluster which is ever +created (by any major version) will run on the default port 5432, and +each new cluster will use the next higher free one. + +E. g. if you first install "postgresql-11" on a clean system, the +default 11/main cluster will run on port 5432. If you then create +another 11 cluster, or install the "postgresql-12" package, that new +one will run on 5433. + +Please use "pg_lsclusters" for displaying the cluster <-> port +mapping, and please have a look at the pg_createcluster manpage (the +--port option) for details. + +Default clusters and upgrading +------------------------------ +When installing a postgresql-NN package from scratch, a default +cluster 'main' will automatically be created. This operation is +equivalent to doing 'pg_createcluster NN main --start'. + +Due to this default cluster, an immediate attempt to upgrade an +earlier 'main' cluster to a new version will fail and you need to +remove the newer default cluster first. E. g., if you have +postgresql-9.6 installed and want to upgrade to 11, you first install +postgresql-11: + + apt-get install postgresql-11 + +Then drop the default 11 cluster that was just created: + + pg_dropcluster 11 main --stop + +And then upgrade the 9.6 cluster to the latest installed version (e. g. 11): + + pg_upgradecluster 9.6 main + +SSL +--- +The PostgreSQL server packages support SSL, which provides encrypted and +authenticated network communication. SSL should be used if you have an +untrusted network between a database server and a client and these exchange +security sensitive data like passwords or confidential database contents. + +When a cluster is created with pg_createcluster, SSL support will automatically +be enabled. postgresql-common makes use of the 'snakeoil' SSL certificate that +is generated by the ssl-cert package, so that SSL works out of the box +(ssl_cert_file, ssl_key_file). In addition, if /etc/postgresql-common/root.crt +exists, it will be used as CA certificate file (ssl_ca_file). + +/etc/postgresql-common/root.crt is a dummy file by default, so that +client-side authentication is not performed. To enable it, you should +add some root certificates to it. A reasonable choice is to just +symlink the file to /etc/ssl/certs/ssl-cert-snakeoil.pem; in this +case, client certificates need to be signed by the snakeoil +certificate, which might be desirable in many cases. See + + /usr/share/doc/postgresql-doc-11/html/ssl-tcp.html + +for details (in package postgresql-doc). + +Further documentation +--------------------- +All commands shipped by postgresql-common have detailed manpages. See +postgresql-common(7) for the documentation of the database client program +wrapping, and user_clusters(5) and postgresqlrc(5) for the cluster +configuration. + +The documentation of the database server and client functions, SQL commands, +modules, etc. documented is shipped in the per-version packages +postgresql-doc-<version>. + |