POSTGRESQL LOCATIONS DESIGN DOCUMENT
------------------------------------

Authors:
Christopher Kings-Lynne (chriskl@familyhealth.com.au)

Writtem:
30th June 2003

Version:
0.1

REQUIREMENTS

1. To be able to specify the physical location of tables and indexes 
   from within the PostgreSQL SQL environment.

2. Databases and schemas will be able to have a default table and 
   default index location specified.  Unless overridden at creation 
   time, a new object will inherit its location from, first, its 
   schema and second, its database. ** Is a default temporary 
   tablespace required?

3. At creation time of all tables and indexes, it should be possible 
   to specify a location.  This includes UNIQUE and PRIMARY KEY 
   declarations.

4. We should allow anonymous locations wherever we allow a <locname>.  
   This means that PsotgreSQL will create a new location on the fly, 
   with a generated name.  This could help with backward compatibility 
   with the CREATE DATABASE location clause.

5. If you don't like 'location', then s/location/storage/g.

CATALOG CHANGES
---------------

A new (global) catalog will need to be created, pg_location.

It will need to have the following fields:

locoid		OID	UNIQUE	NOT NULL	Location identifier
locname		TEXT	UNIQUE	NOT NULL	Location name
locpath		TEXT		NOT NULL	Location path (eg. /spaces/ind1)
locconfig	TEXT[]				GUC variables for objects
						   in this location.
locacl		ACLITEM[]			Access controls for location.

New fields will be required in pg_database:

datrellocid	OID							Default table location identifier
datindlocid	OID							Default index location identifier

New fields will be required in pg_namespace:

nsprellocid	OID							Default table location identifier
nspindlocid	OID							Default index location identifier

The default location fields above can be NULL, in which case objects
default to datpath for the database.

*** Should we just remove datpath and make datrellocid NOT NULL???

PERMISSIONS
-----------

Locations will have a single permission - USAGE.  By default, the creator of a tablespace will be its owner and will have USAGE rights.

Locations can only be created and altered by a superuser.

GRAMMAR
-------

For direct manipulation of locations:

CREATE LOCATION <locname> AS '<locpath>';

DROP LOCATION <locname> [ CASCADE | RESTRICT ];

ALTER LOCATION <locname> SET <variable> { TO | = } { <value> | DEFAULT };
ALTER LOCATION <locname> RESET <variable>;
ALTER LOCATION <locname> RENAME TO <newname>;

For the specification of default locations:

CREATE DATABASE <datname> [ WITH ] { TABLE | INDEX } LOCATION <locname>;
ALTER DATABASE <datname> { TABLE | INDEX } LOCATION { <locname> | DEFAULT };

*** How do we handle existing LOCATION clause?

CREATE SCHEMA <nspname> { TABLE | INDEX } LOCATION <locname>;
ALTER SCHEMA <nspname> { TABLE | INDEX } LOCATION { <locname> | DEFAULT };

Object creation:

CREATE TABLE ... ( ... PRIMARY KEY LOCATION <locname>, UNIQUE LOCATION <locname> ... ) ... LOCATION <locname>;
CREATE INDEX ... LOCATION <locname>;
ALTER TABLE ... ADD { UNIQUE | PRIMARY KEY } ... LOCATION <locname>;

DIAGNOSTICS
-----------

These are the result strings for location manipulation:

CREATE LOCATION
DROP LOCATION
ALTER LOCATION

EXOTIC FEATURES
---------------

These features are cool, but won't make it into the initial implementation
most likely:

1. The SET <variable> stuff above.
2. WAL location
3. Location quotas