neysx 06/03/14 12:30:33 Modified: metadoc.xml Added: postgres-howto.xml Log: #125892 new postgres howto
Revision Changes Path 1.146 xml/htdocs/doc/en/metadoc.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/metadoc.xml?rev=1.146&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/metadoc.xml?rev=1.146&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/metadoc.xml.diff?r1=1.145&r2=1.146&cvsroot=gentoo Index: metadoc.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v retrieving revision 1.145 retrieving revision 1.146 diff -u -r1.145 -r1.146 --- metadoc.xml 11 Mar 2006 21:25:49 -0000 1.145 +++ metadoc.xml 14 Mar 2006 12:30:33 -0000 1.146 @@ -1,9 +1,9 @@ <?xml version='1.0' encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.145 2006/03/11 21:25:49 neysx Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.146 2006/03/14 12:30:33 neysx Exp $ --> <!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd"> <metadoc lang="en"> -<version>1.73</version> +<version>1.74</version> <members> <lead>neysx</lead> <member>fox2mike</member> @@ -103,6 +103,7 @@ <file id="autotools-practices">/doc/en/articles/autotools-practices.xml</file> <file id="bugzie-howto">/doc/en/bugzilla-howto.xml</file> <file id="mysql-howto">/doc/en/mysql-howto.xml</file> + <file id="postgres-howto">/doc/en/postgres-howto.xml</file> <file id="bt-guide">/doc/en/bluetooth-guide.xml</file> <file id="utf-8">/doc/en/utf-8.xml</file> <file id="cron-guide">/doc/en/cron-guide.xml</file> @@ -586,6 +587,10 @@ <memberof>sysadmin_specific</memberof> <fileid>mysql-howto</fileid> </doc> + <doc id="postgres-howto"> + <memberof>sysadmin_specific</memberof> + <fileid>postgres-howto</fileid> + </doc> <doc id="bluetooth-guide"> <memberof>install_other</memberof> <fileid>bt-guide</fileid> 1.1 xml/htdocs/doc/en/postgres-howto.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/postgres-howto.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/postgres-howto.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: postgres-howto.xml =================================================================== <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/postgres-howto.xml,v 1.1 2006/03/14 12:30:33 neysx Exp $ --> <guide link="/doc/en/postgres-howto.xml" lang="en"> <title>PostgreSQL Guide</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">Chris White</mail> </author> <author title="Editor"> <mail link="[EMAIL PROTECTED]">Xavier Neys</mail> </author> <abstract> This guide is meant to show the basic setup of PostgreSQL. The setup described here should be sufficient enough to use for basic web appplications, and any other program that provides PostgreSQL support. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1.0</version> <date>2006-03-14</date> <chapter> <title>Introduction</title> <section> <title>PostgreSQL introduction</title> <body> <p> When talking to most developers about the different database solutions to use, two major databases will usually form the answer. One would be <c>MySQL</c>, and the other is what this document will refer to, <c>PostgreSQL</c>. The advantages of one over the other is a somewhat long winded debate, however it is just to say that PostgreSQL has had a more firm grasp on true relational database structure than MySQL. Most of the standard features such as <b>FOREIGN KEY</b> was only just added in MySQL 5. However, whatever the case may be, this document assumes that you have selected PostgreSQL as the database to use. The first place to start is the <c>emerge</c> process. In the next section, the installation process through emerge will be described, as well as the basic configuration. </p> </body> </section> <section> <title>PostgreSQL installation</title> <body> <p> To begin, we must first <c>emerge</c> the PostgreSQL package. To do so, run the following code to first ensure that the options for it are properly set: </p> <pre caption="Checking the PostgreSQL build options"> # <i>emerge -pv postgresql</i> These are the packages that I would merge, in order: Calculating dependencies ...done! [ebuild N ] dev-db/postgresql-8.0.4 -doc -kerberos +libg++ +nls +pam +perl -pg-hier -pg-intdatetime +python +readline (-selinux) +ssl -tcltk +xml2 +zlib 0 kB </pre> <p> Here's a list of what the different build options indicate: </p> <table> <tr> <th>USE Flag</th> <th>Meaning</th> </tr> <tr> <ti>doc</ti> <ti> This USE flag enables or disables the installation of documentation outside of the standard man pages. The one good time to disable this option is if you are low on space, or you have alternate methods of getting a hold of the documentation (online, etc.) </ti> </tr> <tr> <ti>kerberos</ti> <ti> When connecting to the database, with this option enabled, the admin has the option of using <c>kerberos</c> to authenticate their users/services to the database. </ti> </tr> <tr> <ti>libg++</ti> <ti> If this option is enabled, C++ bindings for PostgreSQL will be built. This will build libpq++ for use by C++ programs to link against. </ti> </tr> <tr> <ti>nls</ti> <ti> If this option is enabled, PostgreSQL can utilized translated strings for non-English speaking users. </ti> </tr> <tr> <ti>pam</ti> <ti> If this option is enabled, and the admin configures the PostgreSQL configuration file properly, users/services will be able to login to a PostgreSQL database using <c>PAM</c> (Pluggable Authentication Module). </ti> </tr> <tr> <ti>perl</ti> <ti> If this option is enabled, <c>perl</c> bindings for PostgreSQL will be built. </ti> </tr> <tr> <ti>pg-hier</ti> <ti> If this option is enabled, a patch is applied to enable hierarchical queries, such as those seen by the <c>CONNECT</c> statement in <c>Oracle</c> database servers. More information on hierarchical queries can be found in the <uri link="http://www.lc.leidenuniv.nl/awcourse/oracle/server.920/a96540/ queries4a. htm">Oracle Reference Guide</uri>. </ti> </tr> <tr> <ti>pg-intdatetime</ti> <ti> If this option is enabled, PostgreSQL will support 64 bit integer date types. </ti> </tr> <tr> <ti>python</ti> <ti> If this option is enabled, PostgreSQL will be built with <c>python</c> bindings. </ti> </tr> <tr> <ti>readline</ti> <ti> If this option is enabled, PostgreSQL will support <c>readline</c> style command line editing. This includes command history and isearch. </ti> </tr> <tr> <ti>selinux</ti> <ti> If this option is enabled, an <c>selinux</c> policy for PostgreSQL will be installed. </ti> </tr> <tr> <ti>ssl</ti> <ti> If this option is enabled, PostgreSQL will utilize the <c>OpenSSL</c> library to encrypt traffic between PostgreSQL clients and servers. </ti> </tr> <tr> <ti>tcltk</ti> <ti> If this option is enabled, PostgreSQL will build <c>tcl/tk</c> bindings. </ti> </tr> <tr> <ti>xml2</ti> <ti> If this option is enabled, <c>XPATH</c> style xml support will be built. More information on using xml support with PostgreSQL can be found on: <uri link="http://www.throwingbeans.org/tech/postgresql_and_xml.html";> PostgreSQL and XML</uri>. </ti> </tr> <tr> <ti>zlib</ti> <ti> This isn't really used by PostgreSQL itself, but by <c>pg_dump</c> to compress the dumps it produces. </ti> </tr> </table> <note> The <c>pg-hier</c> patch author has stopped working on the patch, and it will most likely be removed in later versions. </note> <p> Once you've customized PostgreSQL to meet your specific needs, go ahead and start the <c>emerge</c>: </p> <pre caption="Emerge-ing PostgreSQL"> # <i>emerge postgresql</i> <comment>(Output shortened)</comment> >>> /usr/lib/libecpg.so.5 -> libecpg.so.5.0 >>> /usr/bin/postmaster -> postgres * Make sure the postgres user in /etc/passwd has an account setup with /bin/bash as the shell * * Execute the following command * emerge --config =postgresql-8.0.4 * to setup the initial database environment. * >>> Regenerating /etc/ld.so.cache... >>> dev-db/postgresql-8.0.4 merged. </pre> <p> As shown by the einfo output, there is some post setup that must be done. The next chapter will look at the actual configuration of PostgreSQL. </p> </body> </section> </chapter> <chapter> <title>PostgreSQL configuration</title> <section> <title>Setting up the initial database environment</title> <body> <p> As noted in the earlier <c>emerge</c> output, the initial database environment must be setup. However, before this is done, one thing needs to be considered. Unlike, say MySQL, PostgreSQL's "root" password is the password of the actual user. However, only the user is created by the ebuild <e>not</e> the password. So before we can begin, the password must be set for the postgres user: </p> <pre caption="Setting the password"> # <i>passwd postgres</i> New UNIX password: Retype new UNIX password: passwd: password updated successfully </pre> <p> Now that this is setup, the creation of the initial database environment can occur: </p> <pre caption="Configuring the database environment with emerge --config"> # <i>emerge --config =postgresql-8.0.4</i> Configuring pkg... * Creating the data directory ... * Initializing the database ... The files belonging to this database system will be owned by user "postgres". This user must also own the server process. The database cluster will be initialized with locale C. fixing permissions on existing directory /var/lib/postgresql/data ... ok creating directory /var/lib/postgresql/data/global ... ok creating directory /var/lib/postgresql/data/pg_xlog ... ok creating directory /var/lib/postgresql/data/pg_xlog/archive_status ... ok creating directory /var/lib/postgresql/data/pg_clog ... ok creating directory /var/lib/postgresql/data/pg_subtrans ... ok creating directory /var/lib/postgresql/data/base ... ok creating directory /var/lib/postgresql/data/base/1 ... ok creating directory /var/lib/postgresql/data/pg_tblspc ... ok selecting default max_connections ... 100 selecting default shared_buffers ... 1000 creating configuration files ... ok creating template1 database in /var/lib/postgresql/data/base/1 ... ok initializing pg_shadow ... ok enabling unlimited row size for system tables ... ok initializing pg_depend ... ok creating system views ... ok loading pg_description ... ok creating conversions ... ok setting privileges on built-in objects ... ok creating information schema ... ok vacuuming database template1 ... ok copying template1 to template0 ... ok WARNING: enabling "trust" authentication for local connections You can change this by editing pg_hba.conf or using the -A option the next time you run initdb. Success. You can now start the database server using: /usr/bin/postmaster -D /var/lib/postgresql/data or /usr/bin/pg_ctl -D /var/lib/postgresql/data -l logfile start * * You can use /etc/init.d/postgresql script to run PostgreSQL instead of pg_ctl. * </pre> <p> Now the initial database environment is setup. The next section will look at verifying the install and setting up users to access the database. </p> </body> </section> <section> <title>PostgreSQL database setup</title> <body> <p> Now that PostgreSQL is setup, it's a good idea at this point to verify the installation. First, make sure the service starts up ok: </p> <pre caption="Starting up the PostgreSQL service"> # <i>/etc/init.d/postgresql start</i> * Starting PostgreSQL ... [ ok ] </pre> <p> Once this is verified working, it's also a good idea to add it to the default runlevel so it starts at boot: </p> <pre caption="Adding to the default runlevel"> # <i>rc-update add postgresql default</i> * postgresql added to runlevel default </pre> <p> Now that the service has started, it's time to try setting up a test database. To start out, let's create a test database by using the <c>createdb</c> command. We'll also pass along the <c>-U</c> option to set the user (it defaults to the current user name if you don't), and the <c>-W</c> option to request the password we created earlier. Finally we give it the name of the database we want to create: </p> <pre caption="Creating a database with createdb"> $ <i>createdb -U postgres -W test</i> Password: CREATE DATABASE </pre> <p> The database was successfully created, and we can confirm that the database can run basic tasks. We'll go ahead and drop this database (remove it) with the <c>dropdb</c> command, creating a new one for usage later on: </p> <pre caption="Droping a database with dropdb"> $ <i>dropdb -U postgres -W test</i> Password: DROP DATABASE </pre> <p> Right now, only the postgres user can run commands. Obviously this is not the sort of setup one would like in a multi-user environment. The next section will look at working with user accounts. </p> </body> </section> <section> <title>Setting up database user accounts</title> <body> <p> As mentioned earlier, having to login as the postgres user is somewhat undesirable in a mult-user environment. In most cases there will be various users and services accessing the server, and each have different permission requirements. So, to handle this, the <c>createuser</c> command can be used. This command is an alternative to running a few SQL queries, and is a lot more flexible from an admin standpoint. We'll go ahead and create two users, a 'superuser' that can add other users and administer the db, and a standard user: </p> <pre caption="Setting up the superuser"> <comment>(replace chris with the username you'd like to use)</comment> $ <i>createuser -a -d -P -E -U postgres -W chris</i> Enter password for new user: Enter it again: Password: CREATE USER </pre> <p> There, we've created the superuser. The command line option <c>-a</c> specifies that this user can add other users. <c>-d</c> means that this user can create databases. <c>-P</c> let's you enter a password for the user and <c>-E</c> will encrypt it for security purposes. Now then, we'll test this new user's permissions out by setting up our standard user: </p> <pre caption="Setting up the standard user"> <comment>(replace chris with the username you've just created)</comment> $ <i>createuser -A -D -P -E -U chris -W testuser</i> Enter password for new user: Enter it again: Password: CREATE USER </pre> <p> Success! Our new user was created using the previously created superuser. The <c>-A</c> and <c>-D</c> options do the opposite of <c>-a</c> and <c>-d</c>, and instead deny the user the ability to create other users and databases. Now that there are users to work with, and a new database created, the next chapter will look at using the new database. </p> </body> </section> </chapter> <chapter> <title>Using PostgreSQL</title> <section> <title>Setting up permissions</title> <body> <p> With the new database created, there is a user that can create databases and add other users, and the main postgres user that can do anything. The user created earlier can currently login to the server, and that's about it. In general, users need to be able to insert data and retrieve data, and sometimes any other number of tasks. So, for this new user to be able to do anything, they must be setup with the proper permissions. This can easily be done by passing the <c>-O</c> parameter to <c>createdb</c>. We'll start by making a new database, <b>MyDB</b> with our superuser that will be owned by the previous testuser: </p> <pre caption="Creating the MyDB database"> $ <i>createdb -O testuser -U chris -W MyDB</i> Password: CREATE DATABASE </pre> <p> Alright, now we have a new MyDB database, and a testuser that can access it. To test this out, we'll login as the testuser to the new MyDB database. We'll do this with the <c>psql</c> program. This program is what's used to connect to the PostgreSQL database from command line. So connect to the new database like so: </p> <pre caption="Logging into the MyDB database as the testuser"> $ <i>psql -U testuser -W MyDB</i> Password: Welcome to psql 8.0.4, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help with psql commands \g or terminate with semicolon to execute query \q to quit MyDB=> </pre> <p> So, the testuser is now logged into the database, and can begin to initiate some commands. To get a feel for using PostgreSQL, the next section will take a look at some of the basic commands in navigating the <c>psql</c> client. </p> </body> </section> <section> <title>Basic PostgreSQL commands and creating a table</title> <body> <p> For those who are used to MySQL, this is somewhat of a definite read. This is where PostgreSQL may get somewhat unique with regards to running commands. To start, here is a list of some commands that will be discussed: </p> <table> <tr> <th>Command</th> <th>Usage</th> <th>MySQL Equivalent</th> </tr> <tr> <ti>\c[onnect] [DBNAME|- [USER]]</ti> <ti>Connects to another database</ti> <ti>USE DATABASE</ti> </tr> <tr> <ti>\q</ti> <ti>Quit the <c>psql</c> client</ti> <ti>quit</ti> </tr> <tr> <ti>\i FILE</ti> <ti>Run commands from <c>FILE</c></ti> <ti>source FILE</ti> </tr> <tr> <ti>\o [FILE]</ti> <ti>Send query results to <c>FILE</c></ti> <ti>INTO OUTFILE, but outputs everything (not just SELECTS)</ti> </tr> <tr> <ti>\d [NAME]</ti> <ti>Describe a database or table (as well as other items)</ti> <ti>DESC(RIBE)</ti> </tr> <tr> <ti>\db [PATTERN]</ti> <ti> List available tables that match <c>PATTERN</c> (all if no pattern is given) </ti> <ti>SHOW TABLES</ti> </tr> </table> <p> With the exception of <c>\c[onnect]</c>, all the commands shown will be used later on in the section. So right now the database is empty. That said, we need to insert some data. The first step to inserting data, however, is to put it in a table. Right now there are no tables in the database, so we need to create one. This is done with the <c>CREATE TABLE</c> command. We'll make a table of items. They will contain a Product ID, Description, and price: </p> <pre caption="Creating the products table"> MyDB=> CREATE TABLE products ( MyDB(> product_id SERIAL, MyDB(> description TEXT, MyDB(> price DECIMAL MyDB(> ); NOTICE: CREATE TABLE will create implicit sequence "products_product_id_seq" for serial column "products.product_id" CREATE TABLE </pre> <p> You can ignore the NOTICE, it's perfectly harmless. Looking at the last line of the function, <c>CREATE TABLE</c> seems to indicate that the command has succeeded. However, let's go ahead and verify that the table was indeed successfully created with the <c>\d</c> command: </p> <pre caption="Looking at the newly created table"> MyDB=> <i>\d products</i> Table "public.products" Column | Type | Modifiers -------------+---------+------------------------------------------------------------------ product_id | integer | not null default nextval('public.products_product_id_seq'::text) description | text | price | numeric | </pre> <p> Indeed the table was successfully created. Now that the table is created, it needs to be populated with data. The next section will look at populating the database with data. </p> </body> </section> <section> <title>Inserting data into the database</title> <body> <p> This section will look at the two ways of populating the newly created table with data. First let's look at the most basic command, <c>INSERT</c>: </p> <pre caption="INSERT syntax"> INSERT INTO [tablename] (column1,column2,column3) VALUES(value1,value2,value3) </pre> <p> <c>tablename</c> contains the name of the table to insert the data into. (column1,column2,column3) lets you specify the specific columns to insert the values into. VALUES(value1,value2,value3) is the listing of values. The values are inserted into the same order as the columns (column1 gets value1, column2 gets value2, column3 gets value3). These counts <e>must</e> be the same. So let's go ahead and insert an item into the table: </p> <impo> >From working with databases for a long time, I personally recommend specifying <c>INSERT</c> statements exactly as above. Developers often make the mistake of using <c>INSERT INTO</c> without specifying columns. This is unproductive, as if a new column gets added to the database, it will cause in error if the value to column count is not the same. You should <e>always</e> specify the columns unless you're 300% sure you'll never add a column. </impo> <pre caption="Inserting data into the table"> MyDB=> <i>INSERT INTO products (description,price) VALUES('A test product', 12.00);</i> INSERT 17273 1 </pre> <p> The last line needs a bit of explaining. The return of an insert command is an OID (Object Identifier) and the number of rows inserted. OID's are a bit beyond the scope of this guide, and the <uri link="http://www.postgresql.org/docs/8.1/static/datatype-oid.html";>PostgreSQL manual</uri> has some good information on it. Now, for a situation where you have 20,000 products, these insert statements can be a little tedious. However, not all is lost. The <c>COPY</c> command can be used to insert data into a table from a file or stdin. In this example, let's assume that you have a csv (comma separated values) file, which contains the product id, description, and price. The file looks like this: </p> <pre caption="products.csv"> 2,meat,6.79 3,soup,0.69 4,soda,1.79 </pre> <p> Now we'll use the <c>COPY</c> command to populate our data: </p> <impo> The <c>COPY FROM STDIN</c> command is used because only the postgres user can insert data from a file (for obvious security reasons). </impo> <pre caption="Using COPY to populate the products table"> MyDB=> <i>COPY products FROM STDIN WITH DELIMITER AS ',';</i> Enter data to be copied followed by a newline. End with a backslash and a period on a line by itself. >> <i>2,meat,6.79</i> >> <i>3,soup,0.69</i> >> <i>4,soda,1.79</i> >> <i>\.</i> </pre> <p> Unfortunately, this line doesn't return the same status information as the <c>INSERT INTO</c> statement. How do we know the data was inserted? The next section will look at running queries to check our data. </p> </body> </section> <section> <title>Using PostgreSQL queries</title> <body> <p> This section will look at using the <c>SELECT</c> statement to view data in our tables. The basic <c>SELECT</c> format looks like this: </p> <pre caption="SELECT syntax"> SELECT (column1,column2|*) FROM (table) [WHERE (conditionals)] </pre> <p> There are two ways to select columns. The first is using <c>*</c> to select all columns, and the second is to specify a list of specific columns you wish to see. The second is quite handy when you want to find a specific column in a rather large list of them. Let's start out with using <c>SELECT</c> with <c>*</c> to specify all columns: </p> <pre caption="Viewing the products table"> MyDB=> <i>SELECT * FROM products;</i> product_id | description | price ------------+----------------+------- 1 | A test product | 12.00 2 | meat | 6.79 3 | soup | 0.69 4 | soda | 1.79 (4 rows) </pre> <p> As shown here, all the data we inserted earlier is indeed in the table. Now let's say we only want to see the description and the price, and don't care about the product id. In this case we'll use the column specific SELECT form: </p> <pre caption="Viewing specific columns from the products table"> MyDB=> <i>SELECT description,price FROM products;</i> description | price ----------------+------- A test product | 12.00 meat | 6.79 soup | 0.69 soda | 1.79 (4 rows) </pre> <p> Now only the product and price is shown, letting us focus on only the important data. Now let's say that we want to see only the items that are greater than $2.00. Here's where the <c>WHERE</c> clause comes in handy: </p> <pre caption="Viewing specific rows from the products table"> MyDB=> <i>SELECT description,price FROM products WHERE price > 2.00;</i> description | price ----------------+------- A test product | 12.00 meat | 6.79 (2 rows) </pre> <p> Now a listing of products over $2.00 is displayed, focusing the data even more. These forms of querying for information are very powerful, and can help create extremely useful reports. </p> </body> </section> <section> <title>Conclusion</title> <body> <p> This concludes the PostgreSQL Guide. A big thanks goes to Masatomo Nakano, the Gentoo PostgreSQL maintainer for his help in answering my questions. Any suggestions on this guide should be sent to <mail>[EMAIL PROTECTED]</mail>. For more extensive documentation, see the <uri link="http://www.postgresql.org";>PostgreSQL website</uri>. </p> </body> </section> </chapter> </guide> -- [email protected] mailing list
