CREATE_TABLESPACE(7pg17)

💅 CREATE_TABLESPACE — define a new tablespace

okay so bestie, welcome to the CREATE TABLESPACE page of the PostgreSQL 17.11 Documentation (that's the create_tablespace(7) page btw, iykyk). this one's actually iconic — it's how u give ur database objects a whole new home on the filesystem. let's get into it 🎀

---

✨ NAME ✨

CREATE_TABLESPACE — define a new tablespace

---

🦋 SYNOPSIS 🦋

CREATE TABLESPACE tablespace_name
    [ OWNER { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ]
    LOCATION 'directory'
    [ WITH ( tablespace_option = value [, ... ] ) ]

like, that's the whole shape of it. copy it exactly, don't get creative 💅

---

🌸 DESCRIPTION 🌸

CREATE TABLESPACE registers a new cluster-wide tablespace. the tablespace name has to be distinct from the name of any existing tablespace in the database cluster — no duplicates, no copycats, periodt.

so what even is a tablespace? basically it lets superusers define an alternative location on the file system where the data files containing database objects (think tables and indexes) can live. like giving ur data its own apartment 🏠

a user with appropriate privileges can pass tablespace_name to CREATE DATABASE, CREATE TABLE, CREATE INDEX or ADD CONSTRAINT to have the data files for these objects stored inside the specified tablespace. slay.

⚠️ Warning — a tablespace cannot be used independently of the cluster in which it is defined. like, it's not a standalone thing, it's tied to its cluster fr. see Section 22.6 for the deets.

---

💖 PARAMETERS 💖

• tablespace_name — the name of the tablespace ur about to create. the name cannot begin with pg_ because those names are reserved for system tablespaces. no touching, that's the system's ✋
• user_name — the name of the user who will own the tablespace. if u omit it, it defaults to the user executing the command. and here's the thing: only superusers can create tablespaces, but they can assign ownership of tablespaces to non-superusers. generous queens 👑
• directory — the directory that will be used for the tablespace. important vibes here:
  • the directory must exist (CREATE TABLESPACE will not create it — it's not doing that for u 😭)
  • it should be empty
  • it must be owned by the PostgreSQL system user
  • it must be specified by an absolute path name
• tablespace_option — a tablespace parameter to be set or reset. rn the only available parameters are seq_page_cost, random_page_cost, effective_io_concurrency and maintenance_io_concurrency. setting these values for a particular tablespace will override the planner's usual estimate of the cost of reading pages from tables in that tablespace, plus the executor's prefetching behavior, as established by the configuration parameters of the same name (see seq_page_cost, random_page_cost, effective_io_concurrency, maintenance_io_concurrency). this is lowkey useful if one tablespace is located on a disk which is faster or slower than the remainder of the I/O subsystem. basically: if ur disk is built different, tell the planner 💀

---

🧚 NOTES 🧚

CREATE TABLESPACE cannot be executed inside a transaction block. not me trying to wrap it in BEGIN… don't. 🙈

---

⭐ EXAMPLES ⭐

ok so say u wanna create a tablespace called dbspace at file system location /data/dbs. first, create the directory using operating system facilities and set the correct ownership:

mkdir /data/dbs
chown postgres:postgres /data/dbs

then issue the tablespace creation command inside PostgreSQL:

CREATE TABLESPACE dbspace LOCATION '/data/dbs';

and if u wanna create a tablespace owned by a different database user, use a command like this:

CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes';

see how easy that was? main character energy fr fr 🔥

---

🌈 COMPATIBILITY 🌈

CREATE TABLESPACE is a PostgreSQL extension. it's our thing, not standard SQL's thing 💅

---

👑 SEE ALSO 👑

• CREATE DATABASE (CREATE_DATABASE(7))
• CREATE TABLE (CREATE_TABLE(7))
• CREATE INDEX (CREATE_INDEX(7))
• DROP TABLESPACE (DROP_TABLESPACE(7))
• ALTER TABLESPACE (ALTER_TABLESPACE(7))

---

and that's the whole page bestie 🫶 this was PostgreSQL 17.11, dated 2026, from the CREATE TABLESPACE(7) manual — go forth and give ur data files a cute new address ✨🎀