Импорт CSV в PostgreSQL: что проверить до загрузки

Сначала проверьте файл, потом запускайте импорт

Импорт CSV в PostgreSQL может завершиться ошибкой из-за лишнего разделителя, несовпадения типов или кодировки — а может пройти успешно и загрузить значения не в те столбцы. Для первого импорта через psql закладывайте время на проверку файла и схемы таблицы: команды ниже подходят для PostgreSQL 16. Перед загрузкой сделайте копию CSV и импортируйте данные во временную или отдельную таблицу, а не поверх рабочей.

Понадобятся установленный клиент psql, адрес сервера и имя базы, учётная запись с правом вставлять строки в целевую таблицу, сам CSV и понимание, куда именно должны попасть его столбцы. Если вы работаете через графический клиент, шаги проверки остаются теми же, но интерфейс импорта будет другим.

Что выяснить до подключения

Посмотрите на CSV как на данные, а не как на расширение файла

CSV не задаёт единственный обязательный формат. Разделителем может быть запятая или точка с запятой; текст могут заключать в двойные кавычки; десятичный разделитель и формат дат зависят от того, чем файл создан. Первая строка тоже не обязательно содержит названия полей.

Откройте файл обычным текстовым редактором и проверьте несколько строк: короткую, самую длинную, строку с кавычками и строку с пустыми полями. Просмотр в табличном редакторе может скрыть реальные разделители и автоматически преобразовать даты.

Сопоставьте поля с таблицей

Посмотрите схему целевой таблицы: порядок и типы столбцов, ограничения, значения по умолчанию. Важны не только названия. Строка с датой в неожиданном формате не станет корректной датой автоматически; значение, длиннее ограничения столбца, не поместится; обязательное поле без значения может нарушить ограничение NOT NULL.

Не рассчитывайте, что PostgreSQL догадается о назначении столбцов по содержимому файла. При импорте укажите список столбцов явно и в том же порядке, в каком они идут в CSV. Это защищает от случайного сдвига, если в таблице есть служебное поле или порядок столбцов не совпадает с файлом.

Самая дешёвая проверка импорта — сверить одну строку CSV со списком столбцов до загрузки. После импорта неверное сопоставление уже придётся исправлять в данных.

Подготовьте команду импорта

В PostgreSQL есть команда COPY, а в интерактивном клиенте psql — метакоманда \copy. Для локального CSV обычно удобнее \copy: файл читает клиентская машина, где запущен psql. Обычный COPY обращается к файлу со стороны сервера и требует соответствующего доступа там.

Ниже — шаблон для PostgreSQL 16. Замените имена базы, таблицы и столбцов на свои; укажите путь к файлу и разделитель, которые вы проверили. Команда предполагает, что CSV содержит строку заголовка, а поля разделены запятыми.

\copy public.import_target (id, name, created_at) FROM '/path/to/data.csv' WITH (FORMAT csv, HEADER true, ENCODING 'UTF8');

Если разделитель — точка с запятой, добавьте параметр DELIMITER ';' в список WITH. Если заголовка нет, укажите HEADER false. Не меняйте эти параметры наугад: неверные настройки могут либо прервать импорт, либо привести к неправильному разбору значений.

Сделайте пробный импорт в отдельную таблицу

Для теста создайте таблицу с подходящими типами столбцов или используйте отдельную копию целевой таблицы. Не загружайте пробные данные в рабочую таблицу, если не уверены, как удалить именно добавленные строки. После импорта проверьте число строк, несколько значений из начала и конца файла и поля с датами, кавычками и пустыми значениями.

Число строк в CSV не всегда равно числу строк в таблице: заголовок не загружается как данные, а ограничения или ошибки могут остановить команду. Сверьте итог с ожидаемым количеством записей, а не только с сообщением об успешном завершении.

Типичные ошибки и что проверить

• Сообщение о слишком большом числе полей. Частая причина — выбран не тот разделитель или в данных есть разделитель внутри текста без корректных кавычек. Сверьте настройки с исходным файлом.
• Ошибка входного синтаксиса для типа. Например, текст не преобразуется в дату или число. Найдите строку и значение, проверьте формат и тип столбца; не исправляйте данные массовой заменой, пока не выяснили, что именно означают значения.
• Ошибка кодировки или нечитаемая кириллица. Уточните кодировку файла и параметр импорта. Не пересохраняйте оригинал, не сохранив копию: редактор может изменить символы или формат.
• Отказ в доступе к файлу. При \copy проверьте путь и права пользователя на компьютере, где запущен psql. При серверном COPY проверять нужно доступ со стороны сервера.
• Нарушено ограничение таблицы. Проверьте обязательные поля, уникальность значений и внешние ключи. Исправление зависит от смысла данных: не отключайте ограничения, чтобы просто «продавить» импорт.

Если нужно преобразовать значения перед загрузкой, сначала разберите причину на небольшой выборке. Для сложного файла безопаснее загрузить поля как текст во временную таблицу, проверить их и перенести в целевую таблицу отдельным запросом. Это уже отдельный сценарий: он требует продуманной обработки ошибочных строк.

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

Перед загрузкой в рабочую таблицу сохраните оригинал CSV, зафиксируйте версию PostgreSQL и параметры импорта, проверьте тестовую загрузку и сопоставьте ожидаемое число записей с фактическим. Если импортируете регулярно, оформите проверку формата файла как отдельный этап процесса и определите, кто разбирает строки, которые не проходят проверку.

Термин: заголовок CSV — первая строка файла с именами полей, например id,name,created_at. Параметр HEADER true сообщает PostgreSQL, что эту строку нужно трактовать как заголовок, а не как запись данных.

Параметры файлов и поведение импорта сверяйте с документацией именно той версии PostgreSQL, с которой работаете: здесь команды приведены для PostgreSQL 16.