postgres: Модуль PostgreSQL для NGINX

Установка на Debian/Ubuntu

Эти документы относятся к APT пакету nginx-module-postgres, предоставляемому репозиторием GetPageSpeed Extras.

1. Настройте APT репозиторий, как описано в настройке APT репозитория.
2. Установите модуль:

sudo apt-get update
sudo apt-get install nginx-module-postgres

Показать дистрибутивы и архитектуры

| Дистрибутив | Версия           | Компонент   | Архитектуры     |
|-------------|-------------------|-------------|-----------------|
| debian      | bookworm          | main        | amd64, arm64    |
| debian      | bookworm-mainline | main        | amd64, arm64    |
| debian      | trixie            | main        | amd64, arm64    |
| debian      | trixie-mainline   | main        | amd64, arm64    |
| ubuntu      | focal             | main        | amd64, arm64    |
| ubuntu      | focal-mainline    | main        | amd64, arm64    |
| ubuntu      | jammy             | main        | amd64, arm64    |
| ubuntu      | jammy-mainline    | main        | amd64, arm64    |
| ubuntu      | noble             | main        | amd64, arm64    |
| ubuntu      | noble-mainline    | main        | amd64, arm64    |

---

ngx_postgres — это модуль верхнего уровня, который позволяет nginx напрямую взаимодействовать с базой данных PostgreSQL.

Ответ формируется в формате rds, так что он совместим с модулями ngx_rds_json и ngx_drizzle.

Статус

Этот модуль готов к production и совместим с следующими версиями nginx:

• 0.7.x (тестировалось с 0.7.60 по 0.7.69),
• 0.8.x (тестировалось с 0.8.0 по 0.8.55),
• 0.9.x (тестировалось с 0.9.0 по 0.9.7),
• 1.0.x (тестировалось с 1.0.0 по 1.0.11),
• 1.1.x (тестировалось с 1.1.0 по 1.1.12).
• 1.2.x (тестировалось с 1.2.3 по 1.2.3).
• 1.3.x (тестировалось с 1.3.4 по 1.3.4).

Директивы конфигурации

postgres_server

• синтаксис: postgres_server ip[:port] dbname=dbname user=user password=pass
• по умолчанию: none
• контекст: upstream

Установите данные о сервере базы данных.

postgres_keepalive

• синтаксис: postgres_keepalive off | max=count [mode=single|multi] [overflow=ignore|reject]
• по умолчанию: max=10 mode=single overflow=ignore
• контекст: upstream

Настройте параметры keepalive:

• max - максимальное количество соединений keepalive (на каждый рабочий процесс),
• mode - режим сопоставления бэкенда,
• overflow - либо игнорировать факт переполнения пула соединений keepalive и разрешить запрос, но закрыть соединение позже, либо отклонить запрос с ответом 503 Service Unavailable.

postgres_pass

• синтаксис: postgres_pass upstream
• по умолчанию: none
• контекст: location, if location

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

postgres_query

• синтаксис: postgres_query [methods] query
• по умолчанию: none
• контекст: http, server, location, if location

Установите строку запроса (может включать переменные). Когда указаны методы, то запрос используется только для них, в противном случае — для всех методов.

Эта директива может использоваться более одного раза в одном контексте.

postgres_rewrite

• синтаксис: postgres_rewrite [methods] condition [=]status_code
• по умолчанию: none
• контекст: http, server, location, if location

Перепишите код ответа status_code, когда заданное условие выполнено (первое имеет приоритет!):

• no_changes - ни одна строка не была затронута запросом,
• changes - хотя бы одна строка была затронута запросом,
• no_rows - ни одна строка не была возвращена в результирующем наборе,
• rows - хотя бы одна строка была возвращена в результирующем наборе.

Когда status_code предшествует = знака, оригинальное тело ответа отправляется клиенту вместо стандартной страницы ошибки для данного status_code.

По умолчанию как no_changes, так и changes применимы только к INSERT, UPDATE, DELETE, MOVE, FETCH и COPY SQL запросам.

Эта директива может использоваться более одного раза в одном контексте.

postgres_output

• синтаксис: postgres_output rds|text|value|binary_value|none
• по умолчанию: rds
• контекст: http, server, location, if location

Установите формат вывода:

• rds - вернуть все значения из результирующего набора в формате rds (с соответствующим Content-Type),
• text - вернуть все значения из результирующего набора в текстовом формате (с стандартным Content-Type), значения разделяются новой строкой,
• value - вернуть одно значение из результирующего набора в текстовом формате (с стандартным Content-Type),
• binary_value - вернуть одно значение из результирующего набора в бинарном формате (с стандартным Content-Type),
• none - ничего не возвращать, это следует использовать только при извлечении значений с помощью postgres_set для использования с другими модулями (без Content-Type).

postgres_set

• синтаксис: postgres_set $variable row column [optional|required]
• по умолчанию: none
• контекст: http, server, location

Получите одно значение из результирующего набора и сохраните его в $variable.

Когда уровень требования установлен на required, и значение находится вне допустимого диапазона, NULL или нулевой длины, nginx возвращает ответ 500 Internal Server Error. Такое условие тихо игнорируется, когда уровень требования установлен на optional (по умолчанию).

Номера строк и столбцов начинаются с 0. Имя столбца может быть использовано вместо номера столбца.

Эта директива может использоваться более одного раза в одном контексте.

postgres_escape

• синтаксис: postgres_escape $escaped [[=]$unescaped]
• по умолчанию: none
• контекст: http, server, location

Экранируйте и заключите в кавычки строку $unescaped. Результат сохраняется в переменной $escaped, которая может быть безопасно использована в SQL запросах.

Поскольку nginx не может различить пустые и несуществующие строки, все пустые строки по умолчанию экранируются до значения NULL. Это поведение может быть отключено, если строку $unescaped предшествует знак =.

postgres_connect_timeout

• синтаксис: postgres_connect_timeout timeout
• по умолчанию: 10s
• контекст: http, server, location

Установите тайм-аут для подключения к базе данных.

postgres_result_timeout

• синтаксис: postgres_result_timeout timeout
• по умолчанию: 30s
• контекст: http, server, location

Установите тайм-аут для получения результата из базы данных.

Переменные конфигурации

$postgres_columns

Количество столбцов в полученном результирующем наборе.

$postgres_rows

Количество строк в полученном результирующем наборе.

$postgres_affected

Количество строк, затронутых запросами INSERT, UPDATE, DELETE, MOVE, FETCH или COPY SQL запросами.

$postgres_query

SQL запрос, как его видит база данных PostgreSQL.

Примеры конфигураций

Пример конфигурации #1

Вернуть содержимое таблицы cats (в формате rds).

http {
    upstream database {
        postgres_server  127.0.0.1 dbname=test
                         user=test password=test;
    }

    server {
        location / {
            postgres_pass   database;
            postgres_query  "SELECT * FROM cats";
        }
    }
}

Пример конфигурации #2

Вернуть только те строки из таблицы sites, которые соответствуют фильтру host, который оценивается для каждого запроса на основе переменной $http_host.

http {
    upstream database {
        postgres_server  127.0.0.1 dbname=test
                         user=test password=test;
    }

    server {
        location / {
            postgres_pass   database;
            postgres_query  SELECT * FROM sites WHERE host='$http_host'";
        }
    }
}

Пример конфигурации #3

Передать запрос на бэкенд, выбранный из базы данных (маршрутизация трафика).

http {
    upstream database {
        postgres_server  127.0.0.1 dbname=test
                         user=test password=test;
    }

    server {
        location / {
            eval_subrequest_in_memory  off;

            eval $backend {
                postgres_pass    database;
                postgres_query   "SELECT * FROM backends LIMIT 1";
                postgres_output  value 0 0;
            }

            proxy_pass  $backend;
        }
    }
}

Требуемые модули (кроме ngx_postgres):

• nginx-eval-module (форк agentzh),

Пример конфигурации #4

Ограничить доступ к локальным файлам с помощью аутентификации на основе базы данных PostgreSQL.

http {
    upstream database {
        postgres_server  127.0.0.1 dbname=test
                         user=test password=test;
    }

    server {
        location = /auth {
            internal;

            postgres_escape   $user $remote_user;
            postgres_escape   $pass $remote_passwd;

            postgres_pass     database;
            postgres_query    "SELECT login FROM users WHERE login=$user AND pass=$pass";
            postgres_rewrite  no_rows 403;
            postgres_output   none;
        }

        location / {
            auth_request      /auth;
            root              /files;
        }
    }
}

Требуемые модули (кроме ngx_postgres):

• ngx_http_auth_request_module,
• ngx_coolkit.

Пример конфигурации #5

Простой RESTful веб-сервис, возвращающий JSON-ответы с соответствующими HTTP статусами.

http {
    upstream database {
        postgres_server  127.0.0.1 dbname=test
                         user=test password=test;
    }

    server {
        set $random  123;

        location = /numbers/ {
            postgres_pass     database;
            rds_json          on;

            postgres_query    HEAD GET  "SELECT * FROM numbers";

            postgres_query    POST      "INSERT INTO numbers VALUES('$random') RETURNING *";
            postgres_rewrite  POST      changes 201;

            postgres_query    DELETE    "DELETE FROM numbers";
            postgres_rewrite  DELETE    no_changes 204;
            postgres_rewrite  DELETE    changes 204;
        }

        location ~ /numbers/(?<num>\d+) {
            postgres_pass     database;
            rds_json          on;

            postgres_query    HEAD GET  "SELECT * FROM numbers WHERE number='$num'";
            postgres_rewrite  HEAD GET  no_rows 410;

            postgres_query    PUT       "UPDATE numbers SET number='$num' WHERE number='$num' RETURNING *";
            postgres_rewrite  PUT       no_changes 410;

            postgres_query    DELETE    "DELETE FROM numbers WHERE number='$num'";
            postgres_rewrite  DELETE    no_changes 410;
            postgres_rewrite  DELETE    changes 204;
        }
    }
}

Требуемые модули (кроме ngx_postgres):

• ngx_rds_json.

Пример конфигурации #6

Используйте GET параметр в SQL запросе.

location /quotes {
    set_unescape_uri  $txt $arg_txt;
    postgres_escape   $txt;
    postgres_pass     database;
    postgres_query    "SELECT * FROM quotes WHERE quote=$txt";
}

Требуемые модули (кроме ngx_postgres):

• ngx_set_misc.

Тестирование

ngx_postgres поставляется с полным набором тестов, основанных на Test::Nginx.

Вы можете протестировать основные функции, запустив:

$ TEST_NGINX_IGNORE_MISSING_DIRECTIVES=1 prove

Вы также можете протестировать совместимость с следующими модулями:

• ngx_coolkit,
• ngx_echo,
• ngx_form_input,
• ngx_set_misc,
• ngx_http_auth_request_module,
• nginx-eval-module (форк agentzh),
• ngx_rds_json.

запустив:

$ prove

См. также

• ngx_rds_json,
• ngx_drizzle,
• ngx_lua,
• nginx-eval-module (форк agentzh).