feat: Process options argument (denodrivers#396)

Author: Soremwar

connection/connection.ts

@@ -196,21 +196,29 @@ export class Connection {
     }
   }
 
+  /** https://www.postgresql.org/docs/14/protocol-flow.html#id-1.10.5.7.3 */
   async #sendStartupMessage(): Promise<Message> {
     const writer = this.#packetWriter;
     writer.clear();
+
     // protocol version - 3.0, written as
     writer.addInt16(3).addInt16(0);
-    const connParams = this.#connection_params;
+    // explicitly set utf-8 encoding
+    writer.addCString("client_encoding").addCString("'utf-8'");
+
     // TODO: recognize other parameters
-    writer.addCString("user").addCString(connParams.user);
-    writer.addCString("database").addCString(connParams.database);
+    writer.addCString("user").addCString(this.#connection_params.user);
+    writer.addCString("database").addCString(this.#connection_params.database);
     writer.addCString("application_name").addCString(
-      connParams.applicationName,
+      this.#connection_params.applicationName,
+    );
+    // The database expects options in the --key=value
+    writer.addCString("options").addCString(
+      Object.entries(this.#connection_params.options).map(([key, value]) =>
+        `--${key}=${value}`
+      ).join(" "),
     );
 
-    // eplicitly set utf-8 encoding
-    writer.addCString("client_encoding").addCString("'utf-8'");
     // terminator after all parameters were writter
     writer.addCString("");
 

connection/connection_params.ts

@@ -12,6 +12,7 @@ import { fromFileUrl, isAbsolute } from "../deps.ts";
  * - application_name
  * - dbname
  * - host
+ * - options
  * - password
  * - port
  * - sslmode
@@ -27,12 +28,13 @@ export type ConnectionString = string;
  */
 function getPgEnv(): ClientOptions {
   return {
+    applicationName: Deno.env.get("PGAPPNAME"),
     database: Deno.env.get("PGDATABASE"),
     hostname: Deno.env.get("PGHOST"),
+    options: Deno.env.get("PGOPTIONS"),
+    password: Deno.env.get("PGPASSWORD"),
     port: Deno.env.get("PGPORT"),
     user: Deno.env.get("PGUSER"),
-    password: Deno.env.get("PGPASSWORD"),
-    applicationName: Deno.env.get("PGAPPNAME"),
   };
 }
 
@@ -84,6 +86,7 @@ export interface ClientOptions {
   database?: string;
   hostname?: string;
   host_type?: "tcp" | "socket";
+  options?: string | Record<string, string>;
   password?: string;
   port?: string | number;
   tls?: Partial<TLSOptions>;
@@ -96,6 +99,7 @@ export interface ClientConfiguration {
   database: string;
   hostname: string;
   host_type: "tcp" | "socket";
+  options: Record<string, string>;
   password?: string;
   port: number;
   tls: TLSOptions;
@@ -152,21 +156,67 @@ interface PostgresUri {
   dbname?: string;
   driver: string;
   host?: string;
+  options?: string;
   password?: string;
   port?: string;
   sslmode?: TLSModes;
   user?: string;
 }
 
-function parseOptionsFromUri(connString: string): ClientOptions {
+function parseOptionsArgument(options: string): Record<string, string> {
+  const args = options.split(" ");
+
+  const transformed_args = [];
+  for (let x = 0; x < args.length; x++) {
+    if (/^-\w/.test(args[x])) {
+      if (args[x] === "-c") {
+        if (args[x + 1] === undefined) {
+          throw new Error(
+            `No provided value for "${args[x]}" in options parameter`,
+          );
+        }
+
+        // Skip next iteration
+        transformed_args.push(args[x + 1]);
+        x++;
+      } else {
+        throw new Error(
+          `Argument "${args[x]}" is not supported in options parameter`,
+        );
+      }
+    } else if (/^--\w/.test(args[x])) {
+      transformed_args.push(args[x].slice(2));
+    } else {
+      throw new Error(
+        `Value "${args[x]}" is not a valid options argument`,
+      );
+    }
+  }
+
+  return transformed_args.reduce((options, x) => {
+    if (!/.+=.+/.test(x)) {
+      throw new Error(`Value "${x}" is not a valid options argument`);
+    }
+
+    const key = x.slice(0, x.indexOf("="));
+    const value = x.slice(x.indexOf("=") + 1);
+
+    options[key] = value;
+
+    return options;
+  }, {} as Record<string, string>);
+}
+
+function parseOptionsFromUri(connection_string: string): ClientOptions {
   let postgres_uri: PostgresUri;
   try {
-    const uri = parseConnectionUri(connString);
+    const uri = parseConnectionUri(connection_string);
     postgres_uri = {
       application_name: uri.params.application_name,
       dbname: uri.path || uri.params.dbname,
       driver: uri.driver,
       host: uri.host || uri.params.host,
+      options: uri.params.options,
       password: uri.password || uri.params.password,
       port: uri.port || uri.params.port,
       // Compatibility with JDBC, not standard
@@ -194,6 +244,10 @@ function parseOptionsFromUri(connString: string): ClientOptions {
     ? (isAbsolute(postgres_uri.host) ? "socket" : "tcp")
     : "socket";
 
+  const options = postgres_uri.options
+    ? parseOptionsArgument(postgres_uri.options)
+    : {};
+
   let tls: TLSOptions | undefined;
   switch (postgres_uri.sslmode) {
     case undefined: {
@@ -223,6 +277,7 @@ function parseOptionsFromUri(connString: string): ClientOptions {
     database: postgres_uri.dbname,
     hostname: postgres_uri.host,
     host_type,
+    options,
     password: postgres_uri.password,
     port: postgres_uri.port,
     tls,
@@ -240,6 +295,7 @@ const DEFAULT_OPTIONS:
     host: "127.0.0.1",
     socket: "/tmp",
     host_type: "socket",
+    options: {},
     port: 5432,
     tls: {
       enabled: true,
@@ -304,6 +360,27 @@ export function createParams(
     host = provided_host ?? DEFAULT_OPTIONS.host;
   }
 
+  const provided_options = params.options ?? pgEnv.options;
+
+  let options: Record<string, string>;
+  if (provided_options) {
+    if (typeof provided_options === "string") {
+      options = parseOptionsArgument(provided_options);
+    } else {
+      options = provided_options;
+    }
+  } else {
+    options = {};
+  }
+
+  for (const key in options) {
+    if (!/^\w+$/.test(key)) {
+      throw new Error(`The "${key}" key in the options argument is invalid`);
+    }
+
+    options[key] = options[key].replaceAll(" ", "\\ ");
+  }
+
   let port: number;
   if (params.port) {
     port = Number(params.port);
@@ -344,6 +421,7 @@ export function createParams(
     database: params.database ?? pgEnv.database,
     hostname: host,
     host_type,
+    options,
     password: params.password ?? pgEnv.password,
     port,
     tls: {

docs/README.md

@@ -52,6 +52,9 @@ config = {
   hostname: "localhost",
   host_type: "tcp",
   password: "password",
+  options: {
+    "max_index_keys": "32",
+  },
   port: 5432,
   user: "user",
   tls: {
@@ -108,6 +111,9 @@ of search parameters such as the following:
 - host: If host is not specified in the url, this will be taken instead
 - password: If password is not specified in the url, this will be taken instead
 - port: If port is not specified in the url, this will be taken instead
+- options: This parameter can be used by other database engines usable through
+  the Postgres protocol (such as Cockroachdb for example) to send additional
+  values for connection (ej: options=--cluster=your_cluster_name)
 - sslmode: Allows you to specify the tls configuration for your client, the
   allowed values are the following:
   - disable: Skip TLS connection altogether

tests/config.ts

@@ -45,6 +45,7 @@ export const getClearConfiguration = (
     database: config.postgres_clear.database,
     host_type: "tcp",
     hostname: config.postgres_clear.hostname,
+    options: {},
     password: config.postgres_clear.password,
     port: config.postgres_clear.port,
     tls: tls ? enabled_tls : disabled_tls,
@@ -58,6 +59,7 @@ export const getClearSocketConfiguration = (): SocketConfiguration => {
     database: config.postgres_clear.database,
     host_type: "socket",
     hostname: config.postgres_clear.socket,
+    options: {},
     password: config.postgres_clear.password,
     port: config.postgres_clear.port,
     user: config.postgres_clear.users.socket,
@@ -71,6 +73,7 @@ export const getMainConfiguration = (): TcpConfiguration => {
     database: config.postgres_md5.database,
     hostname: config.postgres_md5.hostname,
     host_type: "tcp",
+    options: {},
     password: config.postgres_md5.password,
     port: config.postgres_md5.port,
     tls: enabled_tls,
@@ -84,6 +87,7 @@ export const getMd5Configuration = (tls: boolean): TcpConfiguration => {
     database: config.postgres_md5.database,
     hostname: config.postgres_md5.hostname,
     host_type: "tcp",
+    options: {},
     password: config.postgres_md5.password,
     port: config.postgres_md5.port,
     tls: tls ? enabled_tls : disabled_tls,
@@ -97,6 +101,7 @@ export const getMd5SocketConfiguration = (): SocketConfiguration => {
     database: config.postgres_md5.database,
     hostname: config.postgres_md5.socket,
     host_type: "socket",
+    options: {},
     password: config.postgres_md5.password,
     port: config.postgres_md5.port,
     user: config.postgres_md5.users.socket,
@@ -109,6 +114,7 @@ export const getScramConfiguration = (tls: boolean): TcpConfiguration => {
     database: config.postgres_scram.database,
     hostname: config.postgres_scram.hostname,
     host_type: "tcp",
+    options: {},
     password: config.postgres_scram.password,
     port: config.postgres_scram.port,
     tls: tls ? enabled_tls : disabled_tls,
@@ -122,6 +128,7 @@ export const getScramSocketConfiguration = (): SocketConfiguration => {
     database: config.postgres_scram.database,
     hostname: config.postgres_scram.socket,
     host_type: "socket",
+    options: {},
     password: config.postgres_scram.password,
     port: config.postgres_scram.port,
     user: config.postgres_scram.users.socket,
@@ -134,6 +141,7 @@ export const getTlsOnlyConfiguration = (): TcpConfiguration => {
     database: config.postgres_md5.database,
     hostname: config.postgres_md5.hostname,
     host_type: "tcp",
+    options: {},
     password: config.postgres_md5.password,
     port: config.postgres_md5.port,
     tls: enabled_tls,