> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-poc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# attach_tablespace()

> Attach a tablespace to a hypertable

export const PG = 'Postgres';

export const TIMESCALE_DB = 'TimescaleDB';

export const CHUNK = 'chunk';

export const HYPERTABLE_CAP = 'Hypertable';

export const HYPERTABLE = 'hypertable';

<Icon icon="tag" iconType="duotone" /> Since [0.7.0][tsdb-0.7.0]

Attach a tablespace to a {HYPERTABLE} and use it to store {CHUNK}s. A
[tablespace][postgres-tablespaces] is a directory on the filesystem
that allows control over where individual tables and indexes are
stored on the filesystem. A common use case is to create a tablespace
for a particular storage disk, allowing tables to be stored
there. To learn more, see the [{PG} documentation on
tablespaces][postgres-tablespaces].

{TIMESCALE_DB} can manage a set of tablespaces for each {HYPERTABLE},
automatically spreading {CHUNK}s across the set of tablespaces attached
to a {HYPERTABLE}. If a {HYPERTABLE} is hash partitioned, {TIMESCALE_DB}
tries to place {CHUNK}s that belong to the same partition in the same
tablespace. Changing the set of tablespaces attached to a {HYPERTABLE}
may also change the placement behavior. A {HYPERTABLE} with no attached
tablespaces has its {CHUNK}s placed in the database's default
tablespace.

## Samples

Attach the tablespace `disk1` to the {HYPERTABLE} `conditions`:

```sql theme={"dark"}
SELECT attach_tablespace('disk1', 'conditions');
SELECT attach_tablespace('disk2', 'conditions', if_not_attached => true);
```

## Arguments

The syntax is:

```sql theme={"dark"}
SELECT attach_tablespace(
    tablespace = '<tablespace_name>',
    hypertable = '<hypertable_name>',
    if_not_attached = true | false
);
```

| Name              | Type     | Default | Required | Description                                                                                                                               |
| ----------------- | -------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `tablespace`      | TEXT     | -       | ✔        | Name of the tablespace to attach.                                                                                                         |
| `hypertable`      | REGCLASS | -       | ✔        | {HYPERTABLE_CAP} to attach the tablespace to.                                                                                             |
| `if_not_attached` | BOOLEAN  | `false` | ✖        | Set to true to avoid throwing an error if the tablespace is already attached to the table. A notice is issued instead. Defaults to false. |

Tablespaces need to be [created][postgres-createtablespace] before
being attached to a {HYPERTABLE}. Once created, tablespaces can be
attached to multiple {HYPERTABLE}s simultaneously to share the
underlying disk storage. Associating a regular table with a tablespace
using the `TABLESPACE` option to `CREATE TABLE`, prior to calling
`create_hypertable`, has the same effect as calling
`attach_tablespace` immediately following `create_hypertable`.

## Returns

This function returns void.

[postgres-createtablespace]: https://www.postgresql.org/docs/current/sql-createtablespace.html

[postgres-tablespaces]: https://www.postgresql.org/docs/current/manage-ag-tablespaces.html

[tsdb-0.7.0]: https://github.com/timescale/timescaledb/releases/tag/0.7.0