Create and Manage Tablespaces

Tablespaces allow database administrators to have multiple file systems per machine and decide how to best use physical storage to store database objects. Tablespaces allow you to assign different storage for frequently and infrequently used database objects or to control the I/O performance on certain database objects. For example, place frequently-used tables on file systems that use high performance solid-state drives (SSD), and place other tables on standard hard drives.

A tablespace requires a host file system location to store its database files. In Cloudberry Database, the file system location must exist on all hosts including the hosts running the coordinator, standby coordinator, each primary segment, and each mirror segment.

A tablespace is Cloudberry Database system object (a global object), you can use a tablespace from any database if you have appropriate privileges.

Note Cloudberry Database does not support different tablespace locations for a primary-mirror pair with the same content ID. It is only possible to configure different locations for different content IDs. Do not modify symbolic links under the pg_tblspc directory so that primary-mirror pairs point to different file locations; this will lead to erroneous behavior.

Creating a Tablespace

The CREATE TABLESPACE command defines a tablespace. For example:

CREATE TABLESPACE fastspace LOCATION '/fastdisk/gpdb';

Database superusers define tablespaces and grant access to database users with the GRANT``CREATEcommand. For example:

GRANT CREATE ON TABLESPACE fastspace TO admin;

Using a Tablespace to Store Database Objects

Users with the CREATE privilege on a tablespace can create database objects in that tablespace, such as tables, indexes, and databases. The command is:

CREATE TABLE tablename(options) TABLESPACE spacename

For example, the following command creates a table in the tablespace space1:

CREATE TABLE foo(i int) TABLESPACE space1;

You can also use the default_tablespace parameter to specify the default tablespace for CREATE TABLE and CREATE INDEX commands that do not specify a tablespace:

SET default_tablespace = space1;
CREATE TABLE foo(i int);

There is also the temp_tablespaces configuration parameter, which determines the placement of temporary tables and indexes, as well as temporary files that are used for purposes such as sorting large data sets. This can be a comma-separate list of tablespace names, rather than only one, so that the load associated with temporary objects can be spread over multiple tablespaces. A random member of the list is picked each time a temporary object is to be created.

The tablespace associated with a database stores that database's system catalogs, temporary files created by server processes using that database, and is the default tablespace selected for tables and indexes created within the database, if no TABLESPACE is specified when the objects are created. If you do not specify a tablespace when you create a database, the database uses the same tablespace used by its template database.

You can use a tablespace from any database in the Cloudberry Database system if you have appropriate privileges.

Viewing Existing Tablespaces

Every Cloudberry Database system has the following default tablespaces.

• pg_global for shared system catalogs.
• pg_default, the default tablespace. Used by the template1 and template0 databases.

These tablespaces use the default system location, the data directory locations created at system initialization.

To see tablespace information, use the pg_tablespace catalog table to get the object ID (OID) of the tablespace and then use gp_tablespace_location() function to display the tablespace directories. This is an example that lists one user-defined tablespace, myspace:

SELECT oid, * FROM pg_tablespace ;

  oid  |  spcname   | spcowner | spcacl | spcoptions
-------+------------+----------+--------+------------
  1663 | pg_default |       10 |        |
  1664 | pg_global  |       10 |        |
 16391 | myspace    |       10 |        |
(3 rows)

The OID for the tablespace myspace is 16391. Run gp_tablespace_location() to display the tablespace locations for a system that consists of two segment instances and the coordinator.

# SELECT * FROM gp_tablespace_location(16391);
 gp_segment_id |    tblspc_loc
---------------+------------------
             0 | /data/mytblspace
             1 | /data/mytblspace
            -1 | /data/mytblspace
(3 rows)

This query uses gp_tablespace_location() the gp_segment_configuration catalog table to display segment instance information with the file system location for the myspace tablespace.

WITH spc AS (SELECT * FROM  gp_tablespace_location(16391))
  SELECT seg.role, spc.gp_segment_id as seg_id, seg.hostname, seg.datadir, tblspc_loc 
    FROM spc, gp_segment_configuration AS seg 
    WHERE spc.gp_segment_id = seg.content ORDER BY seg_id;

This is information for a test system that consists of two segment instances and the coordinator on a single host.

 role | seg_id | hostname |       datadir        |    tblspc_loc
------+--------+----------+----------------------+------------------
 p    |     -1 | testhost | /data/coordinator/gpseg-1 | /data/mytblspace
 p    |      0 | testhost | /data/data1/gpseg0   | /data/mytblspace
 p    |      1 | testhost | /data/data2/gpseg1   | /data/mytblspace
(3 rows)

Dropping Tablespaces

To drop a tablespace, you must be the tablespace owner or a superuser. You cannot drop a tablespace until all objects in all databases using the tablespace are removed.

The DROP TABLESPACE command removes an empty tablespace.

info

You cannot drop a tablespace if it is not empty or if it stores temporary or transaction files.

Moving the Location of Temporary or Transaction Files

You can move temporary or transaction files to a specific tablespace to improve database performance when running queries, creating backups, and to store data more sequentially.

The Cloudberry Database server configuration parameter temp_tablespaces controls the location for both temporary tables and temporary spill files for hash aggregate and hash join queries. Temporary files for purposes such as sorting large data sets are also created in these tablespaces.

temp_tablespaces specifies tablespaces in which to create temporary objects (temp tables and indexes on temp tables) when a CREATE command does not explicitly specify a tablespace.

Also note the following information about temporary or transaction files:

• You can dedicate only one tablespace for temporary or transaction files, although you can use the same tablespace to store other types of files.
• You cannot drop a tablespace if it used by temporary files.