Github user dyozie commented on a diff in the pull request:
https://github.com/apache/incubator-hawq-docs/pull/86#discussion_r96318754
--- Diff: markdown/ddl/ddl-database.html.md.erb ---
@@ -2,77 +2,75 @@
title: Creating and Managing Databases
---
-A HAWQ system is a single instance of HAWQ. There can be several separate
HAWQ systems installed, but usually just one is selected by environment
variable settings. See your HAWQ administrator for details.
-
-There can be multiple databases in a HAWQ system. This is different from
some database management systems \(such as Oracle\) where the database instance
*is* the database. Although you can create many databases in a HAWQ system,
client programs can connect to and access only one database at a time â you
cannot cross-query between databases.
+Your HAWQ deployment may have multiple databases. This is different from
some database management systems \(such as Oracle\) where the database instance
*is* the database. Although you can create many databases in a HAWQ system,
client programs can connect to and access only one database at a time â you
cannot cross-query between databases.
## <a id="topic3"></a>About Template Databases
-Each new database you create is based on a *template*. HAWQ provides a
default database, *template1*. Use *template1* to connect to HAWQ for the first
time. HAWQ uses *template1* to create databases unless you specify another
template. Do not create any objects in *template1* unless you want those
objects to be in every database you create.
+Each new database you create is based on a *template*. HAWQ provides a
default database, `template1`. HAWQ uses `template1` to create databases unless
you specify another template. Do not create any objects in `template1` unless
you want those objects to be in every database you create.
-HAWQ uses two other database templates, *template0* and *postgres*,
internally. Do not drop or modify *template0* or *postgres*. You can use
*template0* to create a completely clean database containing only the standard
objects predefined by HAWQ at initialization, especially if you modified
*template1*.
+HAWQ uses two other database templates internally, `template0` and
`postgres`. Do not drop or modify `template0` or `postgres`. You can use
`template0` to create a completely clean database containing only the standard
objects predefined by HAWQ at initialization, especially if you have modified
`template1`.
## <a id="topic4"></a>Creating a Database
-The `CREATE DATABASE` command creates a new database. For example:
+You must have appropriate privileges or be a HAWQ superuser to create a
database. If you do not have the correct privileges, you cannot create a
database. The HAWQ administrator must either grant you the necessary privileges
or create a database for you.
+
+The [CREATE DATABASE](../reference/sql/CREATE-DATABASE.html) command
creates a new database. For example:
``` sql
-=> CREATE DATABASE new_dbname;
+=# CREATE DATABASE <new_dbname>;
```
-To create a database, you must have privileges to create a database or be
a HAWQ superuser. If you do not have the correct privileges, you cannot create
a database. The HAWQ administrator must either give you the necessary
privileges or to create a database for you.
-
-You can also use the client program `createdb` to create a database. For
example, running the following command in a command line terminal connects to
HAWQ using the provided host name and port and creates a database named
*mydatabase*:
+You can also use the client program `createdb` to create a database. For
example, running the following command connects to HAWQ on the host named
`hmaster` at port `5432` and creates a database named `mydatabase`:
``` shell
-$ createdb -h masterhost -p 5432 mydatabase
+$ createdb -h hmaster -p 5432 mydatabase
```
-The host name and port must match the host name and port of the installed
HAWQ system.
+The host name and port must match the host name and port of the HAWQ
master node.
-Some objects, such as roles, are shared by all the databases in a HAWQ
system. Other objects, such as tables that you create, are known only in the
database in which you create them.
+Some objects, such as roles, are shared by all of the databases in a HAWQ
deployment. Other objects, such as tables that you create, are known only to
the database in which you create them.
### <a id="topic5"></a>Cloning a Database
-By default, a new database is created by cloning the standard system
database template, *template1*. Any database can be used as a template when
creating a new database, thereby providing the capability to 'clone' or copy an
existing database and all objects and data within that database. For example:
+By default, a new database is created by cloning the standard system
database template, `template1`. You may identify an alternate template to use
for database creation. As mentioned in the section above, you can specify
`template0` as the template:
--- End diff --
Also re: cloning, the CREATE DATABASE page has this wording, which seems to
suggest a regular db can be named as a template. Probably want to do some
editing here as well:
"When you copy a database by specifying its name as the template, no other
sessions can be connected to the template database while it is being copied.
New connections to the template database are locked out until CREATE DATABASE
completes."
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
