Metadata-Version: 2.1
Name: pg-save
Version: 0.3.2
Summary: An utility to export Postgres table data to a various formats without having GeoPandas as a requirement
Home-page: https://github.com/kanootoko/pg-save
License: MIT
Author: Aleksei Sokol
Author-email: kanootoko@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: click (>=8.1.6,<9.0.0)
Requires-Dist: loguru (>=0.7.0,<0.8.0)
Requires-Dist: numpy (>=1.25.1,<2.0.0)
Requires-Dist: pandas (>=2.0.3,<3.0.0)
Requires-Dist: psycopg2 (>=2.9.6,<3.0.0)
Requires-Dist: pyxlsx (>=1.1.3,<2.0.0)
Project-URL: Bug Tracker, https://github.com/kanootoko/pg-save/issues
Project-URL: Repository, https://github.com/kanootoko/pg-save
Description-Content-Type: text/markdown

# pg-save - Утилита для сохранения данных из базы данных PostgreSQL в различные форматы

Данная утилита позволяет экспортировать данные таблиц в csv, json, xlsx и geojson форматы посредством
    выгрузки из базы данных с помощью драйвера `psycopg2` и обработки и сохранения средствами `pandas`.

Сохранение geojson происходит без использования `geopandas`,
    вся нагрузка по преобразованию геометрии ложится на `PostGIS` в базе данных.

## Установка из исходного кода

1. Установить [python3](https://python3.org) версии не меньше 3.9
2. Скачать содержимое репозитория и открыть терминал в директории
3. Установить с помощью `pipx install .` или `pip install .`
4. Запустить через `pg-save --help`

## Установка через pipx (pip)

Выполнить `pipx install pg-save`.

В случае ошибки сборки psycopg2 нужно поставить необходимые зависимости, либо устанавливать из исходного кода
с заменой `psycopg2` на `psycopg2-binary` в [pyproject.toml](pyproject.toml).

## Аргументы запуска

Единственный принимаемый аргумент - запрос, название таблицы или имя файла с запросом/названием таблицы.
    Приоритеты: имя файла (если есть такой файл) -> запрос (если начинается со слова SELECT в любом регистре)
    -> название таблицы (если не подошли другие варианты).

Если аргумент не указан (а также не указаны команды получения списка таблиц, получения свойств заданной таблицы,
    или запуска интерактивного режима), то программа завершается с ошибкой.

### Параметры подключения к базе данных

Могут быть установлены через следующие аргументы:
- --db_addr / -h - адрес сервера (по-умолчанию *localhost*)
- --db_port / -p - порт сервера (по-умолчанию *5342*)
- --db_name / -d - название базы данных (по-умолчанию *city_db_final*)
- --db_user / -u - имя пользователя (по-умолчанию *postgres*)
- --db_pass / -w - пароль пользователя (по-умолчанию *postgres*)
- --verbose_level / -v - уровень работы логгера (ERROR, WARNING, INFO, DEBUG, TRACE) - также может быть загружен из
    переменной окружения VERBOSE_LEVEL

Кроме того, эти же параметры могут быть заданы через переменные окружения, пример - [env_default](env_default.txt) .

Задать имя файла для загрузки переменных окружения можно через переменную окружения ENVFILE, по-умолчанию будет
    попытка использования файла `.env` в директории запуска.
Для удобства рекомендуется скопировать и изменить файл, назвав его **env**

### Выполнение заданного select-запроса

Команда `query` позволяет выполнить заданный select-запрос. Доступные параметры:

- --geometry_column / -g - установка столбца геометрии (для вывода в geojson)
- --execute_as_is / -r (флаг) - не выполнять автоматически ST_AsGeoJSON() для геометрий объектов
- --output_filename / -o - сохранение в файл, формат по расширению (.csv, .xlsx, .geojson или .json). Для сохранения
    в geojson необходимо указать столбец геометрии (по-умолчанию *goemetry*)

### Сохранение всех данных таблицы

Команда `select-table` позволяет выполнить запрос вида `SELECT * FROM <table>`. Доступные параметры:

- --geometry_column / -g - установка столбца геометрии (для вывода в geojson)
- --use_centroids / -c (флаг) - сохранять только центроиды объектов (для выгрузки таблицы, с запросом ничего не делает)
- --output_filename / -o - сохранение в файл, формат по расширению (.csv, .xlsx, .geojson или .json). Для сохранения
    в geojson необходимо указать столбец геометрии (по-умолчанию *goemetry*)

### Варианты работы, отличные от выгрузки данных

- list-tables - получение списка таблиц в базе данных
- describe-table - получение информации о выбранной таблице/представлении/материализованном представлении
- interactive - запуск интерактивного режима (о нем ниже)

## Интерактивный режим

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

Доступные команды:

- \<query/filename\> \[> filename\] (запрос или путь до файла с запросом, опционально стрелочка и имя файла
    (в кавычках или нет)) - выполнение select-запроса с возможностью сохранения в файл. Если файл для сохранения
    не задан, резултат просто выводится на экран.
- "\<query/filename\>" \[> filename\] (запрос или путь до файла с запросом в кавычках, опционально стрелочка и имя файла
    (в кавычках или нет)) - выполнение select-запроса с возможностью сохранения в файл. Если файл для сохранения не
    задан, резултат просто выводится на экран. Запрос можно разносить на несколько строк, а также использовать внутри
    экранированные кавычки => аналогично запуску с запрсом.

    Приоритет между файлом и запросом отдается в сторону файла (если такой файл есть).
- \\s \<table_name\> \[> filename\] (имя таблицы после \s, опционально стрелочка и имя файла) - получение всего, что
    находится в таблице с опциональным сохранением в файл => аналогично запуском с аргументом - названием таблицы.
- \\dt \[schema\] - получение списка таблиц, опционально можно задать схему
    (по-умолчанию выводятся все не-системные таблицы) => аналогично ключу --list_tables.
- \\d \[schema\].\<table\> - Получение описания таблицы (столбцы, типы данных, возможность нахождения null'а и
    наличие значения по-умолчанию) => аналогично ключу --describe_table.
- \\geometry_column, \\g - изменение названия колонки геометрии для сохранения таблиц в geojson => аналогично
    ключу --geometry_column
- \\use_centroids, \\c - Переключение режима использования центроидов (используется в случае загрузки таблиц) =>
    аналогично ключу --use_centroids.
- q, quit, exit, два нажатия Ctrl+C подряд - выход из интерактивного режима

