--- title: "Create and Manage Tablespaces" source: https://cloudberry.apache.org/docs/operate-with-data/operate-with-db-objects/create-and-manage-tablespaces --- # 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 Apache Cloudberry, 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 Apache Cloudberry system object (a global object), you can use a tablespace from any database if you have appropriate privileges. > **Note** Apache Cloudberry 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: ```sql CREATE TABLESPACE fastspace LOCATION '/fastdisk/gpdb'; ``` Database superusers define tablespaces and grant access to database users with the `GRANT``CREATE`command. For example: ```sql 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: ```sql CREATE TABLE tablename(options) TABLESPACE spacename ``` For example, the following command creates a table in the tablespace *space1*: ```sql 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: ```sql 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 Apache Cloudberry system if you have appropriate privileges. ## Viewing Existing Tablespaces Every Apache Cloudberry 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`: ```sql 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. ```sql # 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. ```sql 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 Apache Cloudberry 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.