From ed19393326e19a36848a23fa53a806d843fc86c0 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 21 Oct 2006 23:12:57 +0000 Subject: [PATCH] Some marginal editorial improvements and updates in the tutorial. --- doc/src/sgml/advanced.sgml | 4 ++-- doc/src/sgml/query.sgml | 37 +++++++++++++++++++++++-------------- doc/src/sgml/start.sgml | 12 +++++------- 3 files changed, 30 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index 58b4adf6e9..f5929e4f79 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -1,4 +1,4 @@ - + Advanced Features @@ -384,7 +384,7 @@ CREATE TABLE capitals ( type of the column name is text, a native PostgreSQL type for variable length character strings. State capitals have - an extra column, state, that shows their state. In + an extra column, state, that shows their state. In PostgreSQL, a table can inherit from zero or more other tables. diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml index 1d44bdb0f0..d19c074529 100644 --- a/doc/src/sgml/query.sgml +++ b/doc/src/sgml/query.sgml @@ -1,4 +1,4 @@ - + The <acronym>SQL</acronym> Language @@ -20,7 +20,7 @@ In the examples that follow, we assume that you have created a database named mydb, as described in the previous - chapter, and have started psql. + chapter, and have been able to start psql. @@ -35,12 +35,15 @@ This creates the scripts and compiles the C files containing user-defined - functions and types. (You must use GNU make for this — it may be named - something different on your system, often gmake.) + functions and types. (If you installed a pre-packaged version of + PostgreSQL rather than building from source, + look for a directory named tutorial within the + PostgreSQL documentation. The make + part should already have been done for you.) Then, to start the tutorial, do the following: -$ cd ..../src/tutorial +$ cd ..../tutorial $ psql -s mydb ... @@ -416,7 +419,7 @@ SELECT DISTINCT city In some database systems, including older versions of PostgreSQL, the implementation of DISTINCT automatically orders the rows and - so ORDER BY is redundant. But this is not + so ORDER BY is unnecessary. But this is not required by the SQL standard, and current PostgreSQL doesn't guarantee that DISTINCT causes the rows to be ordered. @@ -518,8 +521,10 @@ SELECT city, temp_lo, temp_hi, prcp, date, location Since the columns all had different names, the parser - automatically found out which table they belong to, but it is good - style to fully qualify column names in join queries: + automatically found out which table they belong to. If there + were duplicate column names in the two tables you'd need to + qualify the column names to show which one you + meant, as in: SELECT weather.city, weather.temp_lo, weather.temp_hi, @@ -527,6 +532,10 @@ SELECT weather.city, weather.temp_lo, weather.temp_hi, FROM weather, cities WHERE cities.name = weather.city; + + It is widely considered good style to qualify all column names + in a join query, so that the query won't fail if a duplicate + column name is later added to one of the tables. @@ -548,7 +557,7 @@ SELECT * Now we will figure out how we can get the Hayward records back in. What we want the query to do is to scan the weather table and for each row to find the - matching cities row. If no matching row is + matching cities row(s). If no matching row is found we want some empty values to be substituted for the cities table's columns. This kind of query is called an outer join. (The @@ -681,11 +690,11 @@ SELECT city FROM weather WHERE temp_lo = max(temp_lo); WRONG but this will not work since the aggregate max cannot be used in the WHERE clause. (This restriction exists because - the WHERE clause determines the rows that will - go into the aggregation stage; so it has to be evaluated before - aggregate functions are computed.) + the WHERE clause determines which rows will be + included in the aggregate calculation; so obviously it has to be evaluated + before aggregate functions are computed.) However, as is often the case - the query can be restated to accomplish the intended result, here + the query can be restated to accomplish the desired result, here by using a subquery: @@ -808,7 +817,7 @@ SELECT city, max(temp_lo) You can update existing rows using the UPDATE command. Suppose you discover the temperature readings are - all off by 2 degrees as of November 28. You may update the + all off by 2 degrees after November 28. You may correct the data as follows: diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml index ecdcc28078..0b4d8cf0cf 100644 --- a/doc/src/sgml/start.sgml +++ b/doc/src/sgml/start.sgml @@ -1,4 +1,4 @@ - + Getting Started @@ -181,8 +181,7 @@ createdb: command not found Another response could be this: -createdb: could not connect to database postgres: could not connect to server: -No such file or directory +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"? @@ -194,8 +193,7 @@ No such file or directory Another response could be this: -createdb: could not connect to database postgres: FATAL: user "joe" does not -exist +createdb: could not connect to database postgres: FATAL: role "joe" does not exist where your own login name is mentioned. This will happen if the administrator has not created a PostgreSQL user account @@ -229,7 +227,7 @@ createdb: database creation failed: ERROR: permission denied to create database As an explanation for why this works: PostgreSQL user names are separate - from operating system user accounts. If you connect to a + from operating system user accounts. When you connect to a database, you can choose what PostgreSQL user name to connect as; if you don't, it will default to the same name as your current @@ -353,7 +351,7 @@ mydb=# That would mean you are a database superuser, which is most likely the case if you installed PostgreSQL yourself. Being a superuser means that you are not subject to - access controls. For the purpose of this tutorial this is not of + access controls. For the purposes of this tutorial that is not of importance. -- GitLab