Как установить PostgreSQL и подключиться: пошаговая инструкция

За 15–20 минут вы установите PostgreSQL 16 на Ubuntu 22.04 или 24.04, создадите пользователя и базу данных, а затем подключитесь к ней через psql. Инструкция рассчитана на локальную разработку: сервер будет доступен только на вашем компьютере, без публикации порта в интернет.

Что нужно подготовить

Ниже используются команды для Ubuntu 22.04 и 24.04 с systemd. Нужна учётная запись с правами sudo и доступ к интернету. Подойдёт обычный терминал: отдельный графический клиент на первом этапе не нужен.

• Ubuntu 22.04 или 24.04;
• права администратора через sudo;
• свободные несколько сотен мегабайт на диске;
• терминал с поддержкой копирования команд.

Примеры написаны для PostgreSQL 16.x. Команды psql, createdb и pg_isready сохраняют тот же принцип в PostgreSQL 15–17, но имя пакета и расположение конфигурации могут отличаться. Если система установит другой основной релиз, сначала проверьте его командой psql --version.

Сноска. Роль в PostgreSQL — учётная запись, которой назначают права. Она может входить в систему и владеть базами данных, поэтому в документации вместо привычного слова «пользователь» часто встречается именно «роль».

Для приложения не используйте встроенную роль postgres. Создайте отдельную роль с доступом только к нужной базе: так ошибка в приложении не превратится в полный доступ к серверу.

Установка PostgreSQL на Ubuntu

Шаг 1. Обновите список пакетов

Откройте терминал и выполните:

sudo apt update

Команда обновляет сведения о пакетах, но ещё ничего не устанавливает. Проверка: команда завершается без сообщения об ошибке и возвращает приглашение оболочки. Предупреждение о том, что некоторые пакеты можно обновить, на этом этапе допустимо.

Шаг 2. Установите сервер и клиент

sudo apt install postgresql postgresql-contrib

Подтвердите установку клавишей Y. Пакет postgresql содержит сервер и утилиту psql, а postgresql-contrib — дополнительные расширения из стандартного набора.

Проверьте версию клиента:

psql --version

Проверка считается успешной, если терминал показывает строку вида psql (PostgreSQL) 16.x. Точный номер минорной версии может быть другим. Если вам нужен именно PostgreSQL 16, а Ubuntu устанавливает другой основной релиз, используйте пакет из официального репозитория PostgreSQL для вашей версии Ubuntu, а не подставляйте номер в команду наугад.

Шаг 3. Проверьте состояние сервера

sudo systemctl status postgresql

В выводе должна быть строка Active: active (exited) или Active: active (running). Для Debian и Ubuntu это нормальное состояние: служба может управлять кластером через отдельный процесс.

Более короткая проверка готовности:

pg_isready

Успешный результат выглядит как /var/run/postgresql:5432 - accepting connections. Порт 5432 — стандартный порт PostgreSQL, но он может быть изменён в конфигурации.

Первое подключение через psql

Шаг 4. Войдите встроенной ролью администратора

После установки Ubuntu обычно создаёт роль postgres. Войти через неё можно от имени системного пользователя postgres:

sudo -u postgres psql

Проверка: приглашение терминала изменится на postgres=#. Это означает, что вы внутри консольного клиента, а не в обычной оболочке Linux.

Чтобы выйти из psql, введите метакоманду:

\q

Обратный слеш здесь обязателен. Он не относится к SQL, а запускает команду самого клиента.

Шаг 5. Создайте отдельную роль приложения

Снова войдите в psql:

sudo -u postgres psql

Создайте роль с правом входа:

CREATE ROLE app_user LOGIN;

Задайте пароль интерактивно, чтобы не оставить его в истории команд:

\password app_user

Клиент дважды попросит ввести пароль. В терминале символы не отображаются — это нормальное поведение. Проверка: после повторного ввода psql сообщит, что пароль изменён, и вернёт приглашение postgres=#.

Не вставляйте пароль в команду вроде CREATE ROLE ... PASSWORD '...'. Он может попасть в историю shell, журнал терминала или систему сбора команд.

Шаг 6. Создайте базу данных

В том же сеансе выполните:

CREATE DATABASE app_db OWNER app_user;

Команда создаёт базу app_db и назначает её владельцем роль app_user. Проверка: сервер отвечает CREATE DATABASE без ошибки. Теперь выйдите:

\q

Шаг 7. Подключитесь к новой базе по TCP

Параметр -h 127.0.0.1 специально указывает TCP-подключение. Это ближе к тому, как к базе обращается веб-приложение, чем подключение через локальный Unix-сокет.

psql -h 127.0.0.1 -p 5432 -U app_user -d app_db

Введите пароль роли app_user. Проверка: появится приглашение app_db=>. Выполните запрос:

SELECT current_user, current_database();

В ответе должны быть значения app_user и app_db. Выйти можно командой \q.

Если подключение не работает

«command not found: psql»

Клиент не установлен или его каталог не входит в PATH. На Ubuntu повторите установку пакета:

sudo apt update
sudo apt install postgresql postgresql-client

Затем снова выполните psql --version. Если пакет установлен, но команда не находится, проверьте, не используете ли вы другой контейнер, виртуальную машину или пользователя с отдельным окружением.

«connection refused»

Сервер не запущен или не слушает указанный порт. Проверьте:

sudo systemctl restart postgresql
pg_isready -h 127.0.0.1 -p 5432

Если pg_isready сообщает, что соединение отклонено, посмотрите состояние службы через sudo systemctl status postgresql. Если в вашей конфигурации используется другой порт, укажите его после параметра -p.

«password authentication failed for user»

Роль существует, но пароль не совпадает или вы подключаетесь не к тому серверу. Задайте пароль заново:

sudo -u postgres psql

Внутри клиента выполните \password app_user, выйдите и повторите подключение. Не меняйте файл pg_hba.conf на режим без проверки пароля: это ослабляет защиту и обычно не нужно для локальной разработки.

«database does not exist»

В параметре -d указано имя, которого нет в текущем экземпляре PostgreSQL. Посмотрите список баз:

sudo -u postgres psql -c "\l"

Если app_db отсутствует, создайте её снова командой sudo -u postgres createdb -O app_user app_db. Имена базы и роли чувствительны к точному написанию.

«role does not exist»

Такая роль не создана в экземпляре, к которому вы подключаетесь, либо в команде допущена опечатка. Проверьте роли:

sudo -u postgres psql -c "\du"

В списке должна быть строка app_user. Если её нет, повторите шаг 5.

Windows и macOS: что меняется

На Windows скачайте установщик PostgreSQL 16 для Windows с официальной страницы проекта. Во время установки задайте пароль для роли postgres и запомните выбранный порт. После установки подключайтесь той же командой, но запускайте её в PowerShell: psql -h 127.0.0.1 -p 5432 -U postgres -d postgres. Если psql не найден, добавьте каталог bin установленного PostgreSQL в переменную среды Path или используйте SQL Shell (psql), который устанавливается вместе с сервером.

На macOS через Homebrew команда установки выглядит как brew install postgresql@16. Формулы Homebrew и их пути меняются, поэтому после установки сверяйте способ запуска с актуальной страницей формулы. Проверка версии остаётся прежней: psql --version. Создание роли, базы и подключение выполняются теми же SQL-командами.

Что делать дальше

Сначала подключите к app_db выбранное приложение и сохраните параметры соединения в переменных окружения, а не в репозитории. В продакшене отдельно настройте резервное копирование, ограничьте сетевой доступ, включите TLS при удалённых соединениях и создайте роль без прав администратора.

Для проверки перед первым проектом измерьте три вещи: к какому хосту и порту подключается приложение, под какой ролью оно работает и к какой базе обращается. Большинство первых ошибок PostgreSQL находится именно в этих трёх значениях, а не в SQL-запросах.