postgres: Module PostgreSQL pour NGINX

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et 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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_postgres_module.so;

Ce document décrit nginx-module-postgres v1.0 publié le 22 août 2020.

---

ngx_postgres est un module en amont qui permet à nginx de communiquer directement avec la base de données PostgreSQL.

La réponse est générée au format rds, donc elle est compatible avec les modules ngx_rds_json et ngx_drizzle.

Directives de configuration

postgres_server

• syntax: postgres_server ip[:port] dbname=dbname user=user password=pass
• default: none
• context: upstream

Définissez les détails concernant le serveur de base de données.

postgres_keepalive

• syntax: postgres_keepalive off | max=count [mode=single|multi] [overflow=ignore|reject]
• default: max=10 mode=single overflow=ignore
• context: upstream

Configurez les paramètres de keepalive :

• max - nombre maximum de connexions keepalive (par processus de travail),
• mode - mode de correspondance du backend,
• overflow - soit ignore le fait que le pool de connexions keepalive est plein et autorise la demande, mais ferme la connexion par la suite, soit reject la demande avec une réponse 503 Service Unavailable.

postgres_pass

• syntax: postgres_pass upstream
• default: none
• context: location, if location

Définissez le nom d'un bloc en amont qui sera utilisé pour les connexions à la base de données (il peut inclure des variables).

postgres_query

• syntax: postgres_query [methods] query
• default: none
• context: http, server, location, if location

Définissez la chaîne de requête (elle peut inclure des variables). Lorsque des méthodes sont spécifiées, la requête est utilisée uniquement pour celles-ci, sinon elle est utilisée pour toutes les méthodes.

Cette directive peut être utilisée plusieurs fois dans le même contexte.

postgres_rewrite

• syntax: postgres_rewrite [methods] condition [=]status_code
• default: none
• context: http, server, location, if location

Réécrivez le status_code de la réponse lorsque la condition donnée est remplie (la première qui correspond l'emporte !) :

• no_changes - aucune ligne n'a été affectée par la requête,
• changes - au moins une ligne a été affectée par la requête,
• no_rows - aucune ligne n'a été retournée dans l'ensemble de résultats,
• rows - au moins une ligne a été retournée dans l'ensemble de résultats.

Lorsque status_code est préfixé par le signe =, alors le corps de la réponse originale est envoyé au client au lieu de la page d'erreur par défaut pour le status_code donné.

Par conception, no_changes et changes s'appliquent uniquement aux requêtes SQL INSERT, UPDATE, DELETE, MOVE, FETCH et COPY.

Cette directive peut être utilisée plusieurs fois dans le même contexte.

postgres_output

• syntax: postgres_output rds|text|value|binary_value|none
• default: rds
• context: http, server, location, if location

Définissez le format de sortie :

• rds - retourner toutes les valeurs de l'ensemble de résultats au format rds (avec le Content-Type approprié),
• text - retourner toutes les valeurs de l'ensemble de résultats au format texte (avec le Content-Type par défaut), les valeurs sont séparées par une nouvelle ligne,
• value - retourner une seule valeur de l'ensemble de résultats au format texte (avec le Content-Type par défaut),
• binary_value - retourner une seule valeur de l'ensemble de résultats au format binaire (avec le Content-Type par défaut),
• none - ne rien retourner, cela ne doit être utilisé que lors de l'extraction de valeurs avec postgres_set pour une utilisation avec d'autres modules (sans Content-Type).

postgres_set

• syntax: postgres_set $variable row column [optional|required]
• default: none
• context: http, server, location

Obtenez une seule valeur de l'ensemble de résultats et conservez-la dans $variable.

Lorsque le niveau d'exigence est défini sur required et que la valeur est soit hors limites, NULL ou de longueur zéro, alors nginx retourne une réponse 500 Internal Server Error. Une telle condition est silencieusement ignorée lorsque le niveau d'exigence est défini sur optional (par défaut).

Les numéros de ligne et de colonne commencent à 0. Le nom de la colonne peut être utilisé à la place du numéro de colonne.

Cette directive peut être utilisée plusieurs fois dans le même contexte.

postgres_escape

• syntax: postgres_escape $escaped [[=]$unescaped]
• default: none
• context: http, server, location

Échappez et citez la chaîne $unescaped. Le résultat est stocké dans la variable $escaped qui peut être utilisée en toute sécurité dans les requêtes SQL.

Parce que nginx ne peut pas faire la différence entre des chaînes vides et inexistantes, toutes les chaînes vides sont par défaut échappées en valeur NULL. Ce comportement peut être désactivé en préfixant la chaîne $unescaped avec le signe =.

postgres_connect_timeout

• syntax: postgres_connect_timeout timeout
• default: 10s
• context: http, server, location

Définissez le délai d'attente pour se connecter à la base de données.

postgres_result_timeout

• syntax: postgres_result_timeout timeout
• default: 30s
• context: http, server, location

Définissez le délai d'attente pour recevoir le résultat de la base de données.

Variables de configuration

$postgres_columns

Nombre de colonnes dans l'ensemble de résultats reçu.

$postgres_rows

Nombre de lignes dans l'ensemble de résultats reçu.

$postgres_affected

Nombre de lignes affectées par la requête SQL INSERT, UPDATE, DELETE, MOVE, FETCH ou COPY.

$postgres_query

Requête SQL, telle que vue par la base de données PostgreSQL.

Exemples de configurations

Exemple de configuration #1

Retourner le contenu de la table cats (au format 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";
        }
    }
}

Exemple de configuration #2

Retourner uniquement les lignes de la table sites qui correspondent au filtre host qui est évalué pour chaque demande en fonction de sa variable $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'";
        }
    }
}

Exemple de configuration #3

Passer la demande au backend sélectionné dans la base de données (routeur de trafic).

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

Modules requis (autres que ngx_postgres) :

• nginx-eval-module (fork d'agentzh),

Exemple de configuration #4

Restreindre l'accès aux fichiers locaux en s'authentifiant contre la base de données 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;
        }
    }
}

Modules requis (autres que ngx_postgres) :

• ngx_http_auth_request_module,
• ngx_coolkit.

Exemple de configuration #5

Service web RESTful simple retournant des réponses JSON avec des codes de statut HTTP appropriés.

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

Modules requis (autres que ngx_postgres) :

• ngx_rds_json.

Exemple de configuration #6

Utiliser un paramètre GET dans la requête SQL.

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

Modules requis (autres que ngx_postgres) :

• ngx_set_misc.

Tests

ngx_postgres est livré avec une suite de tests complète basée sur Test::Nginx.

Vous pouvez tester la fonctionnalité de base en exécutant :

$ TEST_NGINX_IGNORE_MISSING_DIRECTIVES=1 prove

Vous pouvez également tester l'interopérabilité avec les modules suivants :

• ngx_coolkit,
• ngx_echo,
• ngx_form_input,
• ngx_set_misc,
• ngx_http_auth_request_module,
• nginx-eval-module (fork d'agentzh),
• ngx_rds_json.

en exécutant :

$ prove

Voir aussi

• ngx_rds_json,
• ngx_drizzle,
• ngx_lua,
• nginx-eval-module (fork d'agentzh).

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-postgres.