postgres: PostgreSQL-Modul für NGINX

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

• RedHat Enterprise Linux 7, 8, 9 und 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-postgres

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-postgres

Aktivieren Sie das Modul, indem Sie Folgendes am Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_postgres_module.so;

Dieses Dokument beschreibt nginx-module-postgres v1.0, veröffentlicht am 22. August 2020.

---

ngx_postgres ist ein Upstream-Modul, das es nginx ermöglicht, direkt mit der PostgreSQL-Datenbank zu kommunizieren.

Die Antwort wird im rds-Format generiert, sodass sie mit den Modulen ngx_rds_json und ngx_drizzle kompatibel ist.

Konfigurationsdirektiven

postgres_server

• Syntax: postgres_server ip[:port] dbname=dbname user=user password=pass
• Standard: none
• Kontext: upstream

Setzen Sie Details zum Datenbankserver.

postgres_keepalive

• Syntax: postgres_keepalive off | max=count [mode=single|multi] [overflow=ignore|reject]
• Standard: max=10 mode=single overflow=ignore
• Kontext: upstream

Konfigurieren Sie die Keepalive-Parameter:

• max - maximale Anzahl von Keepalive-Verbindungen (pro Worker-Prozess),
• mode - Backend-Matching-Modus,
• overflow - entweder ignore, dass der Keepalive-Verbindungspool voll ist und die Anfrage zulässt, aber die Verbindung danach schließt, oder reject die Anfrage mit einer 503 Service Unavailable-Antwort.

postgres_pass

• Syntax: postgres_pass upstream
• Standard: none
• Kontext: location, if location

Setzen Sie den Namen eines Upstream-Blocks, der für die Datenbankverbindungen verwendet wird (er kann Variablen enthalten).

postgres_query

• Syntax: postgres_query [methods] query
• Standard: none
• Kontext: http, server, location, if location

Setzen Sie die Abfragezeichenfolge (sie kann Variablen enthalten). Wenn Methoden angegeben sind, wird die Abfrage nur für diese verwendet, andernfalls wird sie für alle Methoden verwendet.

Diese Direktive kann mehr als einmal im selben Kontext verwendet werden.

postgres_rewrite

• Syntax: postgres_rewrite [methods] condition [=]status_code
• Standard: none
• Kontext: http, server, location, if location

Schreiben Sie den Antwortstatuscode um, wenn die gegebene Bedingung erfüllt ist (die erste gewinnt!):

• no_changes - es wurden keine Zeilen durch die Abfrage betroffen,
• changes - mindestens eine Zeile wurde durch die Abfrage betroffen,
• no_rows - es wurden keine Zeilen im Ergebnis zurückgegeben,
• rows - mindestens eine Zeile wurde im Ergebnis zurückgegeben.

Wenn der status_code mit einem =-Zeichen vorangestellt ist, wird der ursprüngliche Antwortkörper an den Client gesendet, anstelle der Standardfehlerseite für den angegebenen status_code.

Von Design gelten sowohl no_changes als auch changes nur für INSERT, UPDATE, DELETE, MOVE, FETCH und COPY SQL-Abfragen.

Diese Direktive kann mehr als einmal im selben Kontext verwendet werden.

postgres_output

• Syntax: postgres_output rds|text|value|binary_value|none
• Standard: rds
• Kontext: http, server, location, if location

Setzen Sie das Ausgabeformat:

• rds - gibt alle Werte aus dem Ergebnis im rds-Format zurück (mit dem entsprechenden Content-Type),
• text - gibt alle Werte aus dem Ergebnis im Textformat zurück (mit dem Standard-Content-Type), Werte sind durch neue Zeilen getrennt,
• value - gibt einen einzelnen Wert aus dem Ergebnis im Textformat zurück (mit dem Standard-Content-Type),
• binary_value - gibt einen einzelnen Wert aus dem Ergebnis im Binärformat zurück (mit dem Standard-Content-Type),
• none - gibt nichts zurück, dies sollte nur verwendet werden, wenn Werte mit postgres_set für die Verwendung mit anderen Modulen extrahiert werden (ohne Content-Type).

postgres_set

• Syntax: postgres_set $variable row column [optional|required]
• Standard: none
• Kontext: http, server, location

Holen Sie sich einen einzelnen Wert aus dem Ergebnis und speichern Sie ihn in $variable.

Wenn die Anforderungsstufe auf required gesetzt ist und der Wert entweder außerhalb des Bereichs, NULL oder null Länge ist, gibt nginx eine 500 Internal Server Error-Antwort zurück. Eine solche Bedingung wird stillschweigend ignoriert, wenn die Anforderungsstufe auf optional (Standard) gesetzt ist.

Zeilen- und Spaltennummern beginnen bei 0. Der Spaltenname kann anstelle der Spaltennummer verwendet werden.

Diese Direktive kann mehr als einmal im selben Kontext verwendet werden.

postgres_escape

• Syntax: postgres_escape $escaped [[=]$unescaped]
• Standard: none
• Kontext: http, server, location

Escape und quote $unescaped-String. Das Ergebnis wird in der $escaped-Variablen gespeichert, die sicher in SQL-Abfragen verwendet werden kann.

Da nginx den Unterschied zwischen leeren und nicht vorhandenen Strings nicht erkennen kann, werden alle leeren Strings standardmäßig in den NULL-Wert umgewandelt. Dieses Verhalten kann deaktiviert werden, indem der $unescaped-String mit einem =-Zeichen vorangestellt wird.

postgres_connect_timeout

• Syntax: postgres_connect_timeout timeout
• Standard: 10s
• Kontext: http, server, location

Setzen Sie das Timeout für die Verbindung zur Datenbank.

postgres_result_timeout

• Syntax: postgres_result_timeout timeout
• Standard: 30s
• Kontext: http, server, location

Setzen Sie das Timeout für den Empfang des Ergebnisses von der Datenbank.

Konfigurationsvariablen

$postgres_columns

Anzahl der Spalten im empfangenen Ergebnis.

$postgres_rows

Anzahl der Zeilen im empfangenen Ergebnis.

$postgres_affected

Anzahl der von INSERT, UPDATE, DELETE, MOVE, FETCH oder COPY SQL-Abfragen betroffenen Zeilen.

$postgres_query

SQL-Abfrage, wie sie von der PostgreSQL-Datenbank gesehen wird.

Beispielkonfigurationen

Beispielkonfiguration #1

Geben Sie den Inhalt der Tabelle cats (im rds-Format) zurück.

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";
        }
    }
}

Beispielkonfiguration #2

Geben Sie nur die Zeilen aus der Tabelle sites zurück, die dem host-Filter entsprechen, der für jede Anfrage basierend auf der $http_host-Variablen ausgewertet wird.

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'";
        }
    }
}

Beispielkonfiguration #3

Leiten Sie die Anfrage an das Backend weiter, das aus der Datenbank ausgewählt wurde (Traffic-Router).

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;
        }
    }
}

Erforderliche Module (außer ngx_postgres):

• nginx-eval-module (Fork von agentzh),

Beispielkonfiguration #4

Zugriff auf lokale Dateien einschränken, indem gegen die PostgreSQL-Datenbank authentifiziert wird.

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;
        }
    }
}

Erforderliche Module (außer ngx_postgres):

• ngx_http_auth_request_module,
• ngx_coolkit.

Beispielkonfiguration #5

Ein einfacher RESTful-Webservice, der JSON-Antworten mit den entsprechenden HTTP-Statuscodes zurückgibt.

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;
        }
    }
}

Erforderliche Module (außer ngx_postgres):

• ngx_rds_json.

Beispielkonfiguration #6

Verwenden Sie den GET-Parameter in der SQL-Abfrage.

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

Erforderliche Module (außer ngx_postgres):

• ngx_set_misc.

Testen

ngx_postgres kommt mit einer vollständigen Test-Suite, die auf Test::Nginx basiert.

Sie können die Kernfunktionalität testen, indem Sie Folgendes ausführen:

$ TEST_NGINX_IGNORE_MISSING_DIRECTIVES=1 prove

Sie können auch die Interoperabilität mit folgenden Modulen testen:

• ngx_coolkit,
• ngx_echo,
• ngx_form_input,
• ngx_set_misc,
• ngx_http_auth_request_module,
• nginx-eval-module (Fork von agentzh),
• ngx_rds_json.

indem Sie Folgendes ausführen:

$ prove

Siehe auch

• ngx_rds_json,
• ngx_drizzle,
• ngx_lua,
• nginx-eval-module (Fork von agentzh).

GitHub

Sie finden zusätzliche Konfigurationstipps und Dokumentation für dieses Modul im GitHub-Repository für nginx-module-postgres.