Update SQL and Oracle module docs regarding Oracle DSNs (#37590)

- Add 'oracle://' URL format.
- Add note about encoding of special characters in URLs.
- Align the SQL module and the Oracle module documentation.

CHANGELOG.next.asciidoc

@@ -135,6 +135,7 @@ Setting environmental variable ELASTIC_NETINFO:false in Elastic Agent pod will d
 
 *Filebeat*
 
+- Update SQL input documentation regarding Oracle DSNs {pull}37590[37590]
 - add documentation for decode_xml_wineventlog processor field mappings.  {pull}32456[32456]
 - httpjson input: Add request tracing logger. {issue}32402[32402] {pull}32412[32412]
 - Add cloudflare R2 to provider list in AWS S3 input. {pull}32620[32620]

metricbeat/docs/modules/oracle.asciidoc

@@ -60,19 +60,24 @@ Then, Metricbeat can be launched.
 
 *Host Configuration*
 
-The following two types of host configurations are supported:
+The following types of host configuration are supported:
 
-1. Old style host configuration for backwards compatibility:
+1. An old-style Oracle connection string, for backwards compatibility:
     a. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain"]`
     b. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain as sysdba"]`
 
-2. DSN host configuration:
+2. DSN configuration as a URL:
+    a. `hosts: ["oracle://user:[email protected]:1521/ORCLPDB1.localdomain?sysdba=1"]`
+
+3. DSN configuration as a logfmt-encoded parameter list:
     a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']`
     b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']`
 
-DSN host configuration is the recommended way to configure the Oracle Metricbeat Module as it supports the usage of special characters in the password.
+DSN host configuration is the recommended configuration type as it supports the use of special characters in the password.
+
+In a URL any special characters should be URL encoded.
 
-Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`.
+In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`.
 
 [float]
 == Metricsets

metricbeat/docs/modules/sql.asciidoc

@@ -871,19 +871,26 @@ Then, Metricbeat can be launched.
 
 ===== Host Configuration for Oracle
 
-The following two types of host configurations are supported:
+The following types of host configuration are supported:
 
-1. DSN host configuration as URL:
+1. An old-style Oracle connection string, for backwards compatibility:
     a. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain"]`
     b. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain as sysdba"]`
 
-2. DSN host configuration:
+2. DSN configuration as a URL:
+    a. `hosts: ["oracle://user:[email protected]:1521/ORCLPDB1.localdomain?sysdba=1"]`
+
+3. DSN configuration as a logfmt-encoded parameter list:
     a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']`
     b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']`
 
-Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`.
+DSN host configuration is the recommended configuration type as it supports the use of special characters in the password.
+
+In a URL any special characters should be URL encoded.
 
-The username and password to connect to the database can be provided as values to `username` and `password` keys of `sql.yml`. 
+In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`.
+
+The username and password to connect to the database can be provided as values to the `username` and `password` keys of `sql.yml`.
 
 [source,yml]
 ----
@@ -901,6 +908,7 @@ The username and password to connect to the database can be provided as values t
     response_format: variables 
 ----
 
+
 :edit_url:
 
 [float]

x-pack/metricbeat/module/oracle/_meta/docs.asciidoc

@@ -48,19 +48,24 @@ Then, Metricbeat can be launched.
 
 *Host Configuration*
 
-The following two types of host configurations are supported:
+The following types of host configuration are supported:
 
-1. Old style host configuration for backwards compatibility:
+1. An old-style Oracle connection string, for backwards compatibility:
     a. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain"]`
     b. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain as sysdba"]`
 
-2. DSN host configuration:
+2. DSN configuration as a URL:
+    a. `hosts: ["oracle://user:[email protected]:1521/ORCLPDB1.localdomain?sysdba=1"]`
+
+3. DSN configuration as a logfmt-encoded parameter list:
     a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']`
     b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']`
 
-DSN host configuration is the recommended way to configure the Oracle Metricbeat Module as it supports the usage of special characters in the password.
+DSN host configuration is the recommended configuration type as it supports the use of special characters in the password.
+
+In a URL any special characters should be URL encoded.
 
-Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`.
+In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`.
 
 [float]
 == Metricsets

x-pack/metricbeat/module/sql/_meta/docs.asciidoc

@@ -859,19 +859,26 @@ Then, Metricbeat can be launched.
 
 ===== Host Configuration for Oracle
 
-The following two types of host configurations are supported:
+The following types of host configuration are supported:
 
-1. DSN host configuration as URL:
+1. An old-style Oracle connection string, for backwards compatibility:
     a. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain"]`
     b. `hosts: ["user/[email protected]:1521/ORCLPDB1.localdomain as sysdba"]`
 
-2. DSN host configuration:
+2. DSN configuration as a URL:
+    a. `hosts: ["oracle://user:[email protected]:1521/ORCLPDB1.localdomain?sysdba=1"]`
+
+3. DSN configuration as a logfmt-encoded parameter list:
     a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']`
     b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']`
 
-Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`.
+DSN host configuration is the recommended configuration type as it supports the use of special characters in the password.
+
+In a URL any special characters should be URL encoded.
 
-The username and password to connect to the database can be provided as values to `username` and `password` keys of `sql.yml`. 
+In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`.
+
+The username and password to connect to the database can be provided as values to the `username` and `password` keys of `sql.yml`.
 
 [source,yml]
 ----
@@ -887,4 +894,4 @@ The username and password to connect to the database can be provided as values t
   sql_queries: 
   - query: SELECT METRIC_NAME, VALUE FROM V$SYSMETRIC WHERE GROUP_ID = 2 and METRIC_NAME LIKE '%'
     response_format: variables 
-----
+----