# Кластер, PGDATA и каталоги

_Хранение и формат на диске · PostgreSQL Knowledge Base_

**TL;DR:** Кластер PostgreSQL - это один каталог на диске (PGDATA) и один набор
процессов, обслуживающий сразу несколько баз. Внутри PGDATA лежат base/
с данными баз, global/ с общими объектами, pg_wal/ с журналом и служебные
каталоги вроде pg_xact/. Всё хранение начинается отсюда.


Когда говорят «поставил Postgres», обычно имеют в виду одну установку
сервера. Внутри это **кластер** - один каталог с данными и один главный
процесс (postmaster), который обслуживает несколько баз данных сразу.
Слово «кластер» тут не про несколько машин. Это про несколько баз под
одним сервером.

Каталог с данными называют **PGDATA** - по имени переменной окружения,
которая на него указывает. Узнать его путь можно прямо из работающего
сервера:

```sql
SHOW data_directory;
-- /var/lib/postgresql/data
```

## Что лежит в PGDATA

Заглянем внутрь. Имена каталогов одинаковы на любой установке:

| Каталог | Что хранит |
|---|---|
| `base/` | данные всех обычных баз, по подкаталогу на базу |
| `global/` | объекты, общие для кластера (список баз, роли) |
| `pg_wal/` | журнал предзаписи (WAL) |
| `pg_xact/` | статусы транзакций (clog) |
| `pg_tblspc/` | ссылки на табличные пространства |
| `postgresql.conf` | конфигурация сервера |

Каждая база внутри `base/` - это подкаталог, названный по числовому
идентификатору базы (OID). Посмотреть соответствие «имя - OID»:

```sql
SELECT oid, datname FROM pg_database ORDER BY oid;
--   oid  |  datname
-- -------+-----------
--      1 | template1
--      4 | template0
--      5 | postgres
--  16384 | lab
```

Системные базы получают маленькие фиксированные OID, а созданные позже -
числа из диапазона от 16384. То есть данные нашей учебной базы `lab` с
OID 16384 лежат в `base/16384/`. Внутри этого подкаталога - файлы
отдельных таблиц и индексов. Какой именно файл соответствует таблице,
расскажет [relfilenode-forks](/courses/postgres/kb/relfilenode-forks.md).

## Три базы по умолчанию

Свежий кластер уже содержит три базы. `template1` и `template0` - это
шаблоны: `CREATE DATABASE` физически копирует `template1`. `template0`
держат нетронутым как чистый эталон на случай, если `template1` испортили.
База `postgres` - просто удобная база по умолчанию, в неё можно зайти
сразу после установки.

## Табличные пространства

По умолчанию все данные лежат внутри PGDATA. Но таблицу или целую базу
можно положить на другой диск через **табличное пространство** (tablespace) -
именованную ссылку на каталог вне PGDATA. Внутри `base/` тогда останется
только символическая ссылка через `pg_tblspc/`. Это инструмент уровня
администрирования: вынести горячие индексы на быстрый SSD, архив - на
медленный диск.

## Почему это важно знать

Понимание, что кластер - это один каталог с предсказуемой раскладкой,
убирает магию из всего остального. Размер базы - это размер каталога.
Бэкап на уровне файлов - это копия PGDATA в согласованном состоянии.
Повреждение - это конкретный битый файл в конкретном подкаталоге. Когда
знаешь, где что лежит, диагностика перестаёт быть гаданием.


## Команды

```sql
SHOW data_directory;
```
Путь к каталогу PGDATA текущего кластера

```sql
SELECT oid, datname FROM pg_database ORDER BY oid;
```
Список баз и их числовых идентификаторов (имена подкаталогов в base/)

```sql
SELECT pg_size_pretty(pg_database_size('postgres'));
```
Размер базы на диске в человекочитаемом виде

```sql
SELECT spcname FROM pg_tablespace;
```
Список табличных пространств кластера


## См. также

- [relfilenode и форки отношения](/courses/postgres/kb/relfilenode-forks.md)
- [Раскладка страницы 8 КБ](/courses/postgres/kb/page-layout.md)
- [TOAST: вынос и сжатие длинных значений](/courses/postgres/kb/toast.md)