Пошук уроків, статей та іншого контенту
Налаштуємо PostgreSQL для NestJS, створимо базу даних і підготуємо конфігурацію підключення.
У цьому уроці ми:
запустимо PostgreSQL;
створимо користувача та базу даних;
встановимо пакети для роботи NestJS із PostgreSQL;
додамо змінні середовища;
налаштуємо підключення через ConfigModule і TypeOrmModule;
перевіримо, що NestJS успішно підключається до бази даних.
NestJS сам по собі не створює базу даних PostgreSQL. Спочатку потрібно підготувати PostgreSQL, а потім передати NestJS параметри підключення.
Для локальної розробки зручно запустити PostgreSQL у Docker:
docker run --name nest-postgres \
-e POSTGRES_USER=nest_user \
-e POSTGRES_PASSWORD=nest_password \
-e POSTGRES_DB=nest_db \
-p 5432:5432 \
-d postgres:16Ця команда:
створює контейнер із назвою nest-postgres;
створює користувача nest_user;
встановлює пароль nest_password;
створює базу даних nest_db;
відкриває порт PostgreSQL 5432.
Перевірити запущені контейнери можна командою:
docker psЯкщо PostgreSQL уже встановлений локально, Docker не потрібен. У такому разі достатньо створити базу даних і користувача засобами PostgreSQL.
psqlНаприклад, базу даних можна створити вручну:
CREATE USER nest_user WITH PASSWORD 'nest_password';
CREATE DATABASE nest_db OWNER nest_user;База даних зазвичай працює на порту 5432. Якщо PostgreSQL налаштований на іншому порту, це потрібно буде вказати в конфігурації NestJS.
У проєкті NestJS встановимо такі пакети:
npm install @nestjs/config @nestjs/typeorm typeorm pgПризначення пакетів:
@nestjs/config — читає змінні середовища;
@nestjs/typeorm — інтегрує TypeORM із NestJS;
typeorm — ORM для роботи з базою даних;
pg — драйвер PostgreSQL для Node.js.
NestJS не підключається до PostgreSQL безпосередньо. Для цього використовується драйвер pg, а TypeORM спрощує виконання запитів і роботу з таблицями.
У корені проєкту створіть файл .env:
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=nest_user
DB_PASSWORD=nest_password
DB_NAME=nest_dbЗмінні середовища дають змогу не записувати параметри підключення безпосередньо в коді.
Файл .env не варто додавати до Git, особливо якщо він містить справжні паролі. Додайте його до .gitignore:
.envДля команди або прикладу можна створити файл .env.example без реальних секретів:
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=your_user
DB_PASSWORD=your_password
DB_NAME=your_databaseConfigModuleВідкрийте файл src/app.module.ts і налаштуйте модулі:
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
}),
TypeOrmModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
type: 'postgres',
host: configService.getOrThrow<string>('DB_HOST'),
port: Number(configService.getOrThrow<string>('DB_PORT')),
username: configService.getOrThrow<string>('DB_USERNAME'),
password: configService.getOrThrow<string>('DB_PASSWORD'),
database: configService.getOrThrow<string>('DB_NAME'),
// Сутності автоматично додаються до конфігурації TypeORM
autoLoadEntities: true,
// Зручно під час розробки, але не слід використовувати в production
synchronize: configService.get<string>('NODE_ENV') !== 'production',
}),
),
],
})
export class AppModule {}ConfigModule.forRoot() завантажує змінні з файлу .env.
Параметр:
isGlobal: trueробить ConfigModule доступним у всіх модулях без повторного імпорту.
TypeOrmModule.forRootAsync() використовує асинхронну фабрику конфігурації. Через ConfigService ми отримуємо значення змінних середовища:
configService.getOrThrow<string>('DB_HOST')Метод getOrThrow() повертає значення або завершує запуск із помилкою, якщо змінна не задана. Це краще, ніж непомітно передати undefined у конфігурацію підключення.
Порт зберігається у змінних середовища як текстове значення, тому його потрібно перетворити на число:
Number(configService.getOrThrow<string>('DB_PORT'))Запустіть NestJS у режимі розробки:
npm run start:devЯкщо всі параметри правильні, застосунок запуститься без помилки підключення до бази даних.
Якщо PostgreSQL працює в Docker, контейнер має бути запущений до старту NestJS:
docker start nest-postgres
npm run start:devЗупинити контейнер можна командою:
docker stop nest-postgresСам факт успішного запуску NestJS із налаштованим TypeOrmModule означає, що TypeORM зміг встановити з’єднання з PostgreSQL.
Для додаткової перевірки можна відкрити PostgreSQL у контейнері:
docker exec -it nest-postgres psql \
-U nest_user \
-d nest_dbПісля підключення виконайте SQL-команду:
SELECT current_database(), current_user;Очікувано PostgreSQL поверне назву бази nest_db і користувача nest_user.
Вийти з psql можна командою:
\qsynchronizeУ прикладі використовується:
synchronize: configService.get<string>('NODE_ENV') !== 'production'Коли NODE_ENV має значення development, TypeORM може автоматично синхронізувати структуру таблиць із сутностями.
Це зручно під час навчання та локальної розробки, але небезпечно для production. Зміна сутності може призвести до зміни або втрати структури таблиці.
У production варто вимикати автоматичну синхронізацію:
synchronize: falseМіграції бази даних розглядаються окремо. На цьому етапі важливо запам’ятати: synchronize не слід бездумно використовувати для реальної бази даних.
ECONNREFUSED 127.0.0.1:5432PostgreSQL не запущений або працює на іншому порту.
Перевірте контейнер:
docker psЯкщо контейнер зупинений:
docker start nest-postgrespassword authentication failedНеправильні значення DB_USERNAME або DB_PASSWORD.
Перевірте, чи збігаються дані у .env і параметри, з якими було створено користувача PostgreSQL.
database "nest_db" does not existБаза даних із таким іменем не створена або вказано неправильне значення DB_NAME.
undefinedПереконайтеся, що:
файл .env розташований у корені проєкту;
назви змінних написані без помилок;
у AppModule підключено ConfigModule.forRoot();
NestJS перезапущено після зміни .env.
Змінні середовища завжди читаються як текст. Для порту потрібне перетворення:
port: Number(configService.getOrThrow<string>('DB_PORT'))Для підключення NestJS до PostgreSQL потрібно:
Запустити PostgreSQL.
Створити базу даних і користувача.
Встановити @nestjs/config, @nestjs/typeorm, typeorm і pg.
Зберегти параметри підключення у .env.
Підключити ConfigModule.
Налаштувати TypeOrmModule.forRootAsync().
Запустити застосунок і перевірити відсутність помилок підключення.
Після цього NestJS готовий працювати з таблицями PostgreSQL через TypeORM.