18.6. Tablespaces

Tablespaces in PostgreSQL allow database administrators to define locations in the file system where the files representing database objects can be stored. Once created, a tablespace can be referred to by name when creating database objects.

By using tablespaces, a database administrator can control the disk layout of a PostgreSQL installation. This is useful in at least two ways. Firstly, if the partition or volume on which the cluster was initialized runs out of space and cannot be extended logically or otherwise, a tablespace can be created on a different partition and used until the system can be reconfigured.

Secondly, tablespaces allow a database administrator to arrange data locations based on the usage patterns of database objects. For example, an index which is very heavily used can be placed on very fast, highly available disk, such as an expensive solid state device. At the same time a table storing archived data which is rarely used or not performance critical could be stored on a less expensive, slower disk system.

To define a tablespace, use the CREATE TABLESPACE command, for example:

CREATE TABLESPACE fastspace LOCATION '/mnt/sda1/postgresql/data';

The location must be an existing, empty directory that is owned by the PostgreSQL system user. All objects subsequently created within the tablespace will be stored in files underneath this directory.

Note: There is usually not much point in making more than one tablespace per logical filesystem, since you can't control the location of individual files within a logical filesystem. However, PostgreSQL does not enforce any such limitation, and indeed it's not directly aware of the filesystem boundaries on your system. It just stores files in the directories you tell it to use.

Creation of the tablespace itself must be done as a database superuser, but after that you can allow ordinary database users to make use of it. To do that, grant them the CREATE privilege on it.

Databases, schemas, tables, and indexes can all be assigned to particular tablespaces. To do so, a user with the CREATE privilege on a given tablespace must pass the tablespace name as a parameter to the relevant command. For example, the following creates a table in the tablespace space1:

CREATE TABLE foo(i int) TABLESPACE space1;

The tablespace associated with a database is used to store the system catalogs of that database, as well as any temporary files created by server processes using that database. Furthermore, it is the default tablespace selected for any objects created within the database, if no specific TABLESPACE clause is given when those objects are created. If a database is created without specifying a tablespace for it, it uses the same tablespace as the template database it is copied from.

A schema does not in itself occupy any storage (other than a system catalog entry), so assigning a tablespace to a schema does not in itself do anything. What this actually does is to set a default tablespace for tables later created within the schema. If no tablespace is mentioned when creating a schema, it inherits its default tablespace from the current database.

The default choice of tablespace for an index is the same tablespace already assigned to the table the index is for.

Another way to state the above rules is that when a schema, table, or index is created without specifying a tablespace, the object inherits its logical parent's tablespace. A schema will be created in the current database's tablespace; a table will be created in the tablespace of the schema it is being created in; an index will be created in the tablespace of the table underlying the index.

Two tablespaces are automatically created by initdb. The pg_global tablespace is used for shared system catalogs. The pg_default tablespace is the default tablespace of the template1 and template0 databases (and, therefore, will be the default tablespace for everything else as well, unless explicit TABLESPACE clauses are used somewhere along the line).

Once created, a tablespace can be used from any database, provided the requesting user has sufficient privilege. This means that a tablespace cannot be dropped until all objects in all databases using the tablespace have been removed.

To simplify the implementation of tablespaces, PostgreSQL makes extensive use of symbolic links. This means that tablespaces can be used only on systems that support symbolic links.

The directory $PGDATA/pg_tblspc contains symbolic links that point to each of the non-built-in tablespaces defined in the cluster. Although not recommended, it is possible to adjust the tablespace layout by hand by redefining these links. Two warnings: do not do so while the postmaster is running; and after you restart the postmaster, update the pg_tablespace catalog to show the new locations. (If you do not, pg_dump will continue to show the old tablespace locations.)