Configure PostgreSQL tablespaces in PGO-managed clusters

PostgreSQL tablespaces let you store database objects (tables, indexes) on a filesystem path separate from the main data directory. Common use cases include placing large or infrequently accessed tables on cheaper storage, directing I/O-intensive indexes to faster disks, or satisfying data-placement requirements across storage tiers. PGO supports tablespaces through the TablespaceVolumes feature gate. Each tablespace is backed by its own PersistentVolumeClaim, and PGO handles creating the directory structure and registering the tablespace inside PostgreSQL automatically.

TablespaceVolumes is an alpha feature that is disabled by default. Alpha features may change or be removed in future releases. Do not rely on them for production workloads without thoroughly testing upgrades.

Enable the feature gate

To use tablespace volumes, enable the TablespaceVolumes feature gate on the operator deployment. Add the flag to the operator’s startup arguments:

# In the operator Deployment spec
args:
  - --feature-gates=TablespaceVolumes=true

For Kustomize-based installations, patch the operator Deployment to add the --feature-gates argument. For Helm installations, consult the chart’s values.yaml for the feature gate configuration option.

Define tablespace volumes

Once the feature gate is enabled, add a tablespaceVolumes list to the instance set definition. Each entry requires a unique name and a dataVolumeClaimSpec describing the PersistentVolumeClaim.

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 16
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 10Gi
      tablespaceVolumes:
        - name: fastdisk
          dataVolumeClaimSpec:
            accessModes:
              - ReadWriteOnce
            storageClassName: premium-ssd
            resources:
              requests:
                storage: 50Gi
        - name: archive
          dataVolumeClaimSpec:
            accessModes:
              - ReadWriteOnce
            storageClassName: standard-hdd
            resources:
              requests:
                storage: 200Gi

TablespaceVolume fields

Field	Type	Required	Description
`name`	string	Yes	Name of the tablespace. Used as the directory name on the volume and as the PostgreSQL tablespace name. Must be lowercase letters and numbers only, starting with a letter (`^[a-z][a-z0-9]*$`). Must be unique within the instance set.
`dataVolumeClaimSpec`	VolumeClaimSpec	Yes	PersistentVolumeClaim specification for the tablespace volume. Must include `accessModes` and `resources.requests.storage`.

How PGO sets up tablespace directories

When TablespaceVolumes is enabled and configured, PGO:

Creates a PersistentVolumeClaim for each tablespaceVolumes entry.
Mounts each PVC into the instance pod.
Creates the required PostgreSQL tablespace directory structure inside the mounted volume.
Creates a symlink so PostgreSQL can locate the tablespace at the expected path.
Registers the tablespace in PostgreSQL using CREATE TABLESPACE.

You do not need to run CREATE TABLESPACE manually; PGO handles the full lifecycle.

Use a tablespace in PostgreSQL

Once the tablespace is created by PGO, you can use it by name in SQL:

-- Create a table in the fastdisk tablespace
CREATE TABLE events (
  id BIGSERIAL PRIMARY KEY,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  payload JSONB
) TABLESPACE fastdisk;

-- Move an existing table to a tablespace
ALTER TABLE events SET TABLESPACE archive;

-- Create an index on a specific tablespace
CREATE INDEX idx_events_created ON events (created_at) TABLESPACE fastdisk;

Considerations

Name constraints: Tablespace names must match ^[a-z][a-z0-9]*$. They must be unique within an instance set because they become both the directory path and the PostgreSQL tablespace identifier.
Volume expansion: Tablespace PVCs can be resized using the same approach as the main data volume. See Resize cluster resources.
Replicas: Each instance in the set gets its own PVC per tablespace. PGO ensures tablespace directories exist on all instances so that replicas can follow the primary correctly.
Backups: pgBackRest does not automatically back up tablespace volumes that are separate PVCs. Ensure your backup strategy accounts for tablespace data.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Configure PostgreSQL tablespaces in PGO-managed clusters

Enable the feature gate

Define tablespace volumes

TablespaceVolume fields

How PGO sets up tablespace directories

Use a tablespace in PostgreSQL

Considerations

Next steps

Resize cluster resources

Feature gates reference

​Enable the feature gate

​Define tablespace volumes

​TablespaceVolume fields

​How PGO sets up tablespace directories

​Use a tablespace in PostgreSQL

​Considerations

​Next steps

Resize cluster resources

Feature gates reference

Enable the feature gate

Define tablespace volumes

TablespaceVolume fields

How PGO sets up tablespace directories

Use a tablespace in PostgreSQL

Considerations

Next steps