Code formatting, doc and test updates

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -1365,28 +1365,25 @@ Connection Methods
 
             Each column’s ``name`` is always given. If the column is a :ref:`nested cursor <nestedcursors>`, then the column’s object will also contain a ``metaData`` attribute which is an array describing each column in the nested query.
 
-            Extended metadata is now always returned and includes the following information:
-
-            - ``annotations``: The `annotations <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/annotations_clause.html#GUID-1AC16117-BBB6-4435-8794-2B99F8F68052>`__ object associated with the fetched column. If the column has no associated annotations, this property value is `undefined`. Annotations are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
+            Extended metadata is now always returned and includes the following information attributes:
 
+            - ``annotations``: The `annotations <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/annotations_clause.html#GUID-1AC16117-BBB6-4435-8794-2B99F8F68052>`__ object associated with the fetched column. If the column has no associated annotations, this attribute value is `undefined`. Annotations are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
             - ``byteSize``: The database byte size. This is only set for ``oracledb.DB_TYPE_VARCHAR``, ``oracledb.DB_TYPE_CHAR`` and ``oracledb.DB_TYPE_RAW`` column types.
             - ``dbType``: one of the :ref:`Oracle Database Type Constant <oracledbconstantsdbtype>` values.
             - ``dbTypeClass``: The class associated with the database type. This is only set if the database type is an object type.
             - ``dbTypeName``: The name of the database type, such as “NUMBER” or “VARCHAR2”. For object types, this will be the object name.
-            - ``domainName``: The name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a data use case domain, this property value is `undefined`. `Data use case domains <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4743FDE1-7C6E-471B-BC9D-442383CCA2F9>`__ are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
-
-            - ``domainSchema``: The schema name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a data use case domain, this property value is `undefined`. `Data use case domains <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4743FDE1-7C6E-471B-BC9D-442383CCA2F9>`__ are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
-
+            - ``domainName``: The name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a data use case domain, this attribute value is `undefined`. `Data use case domains <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4743FDE1-7C6E-471B-BC9D-442383CCA2F9>`__ are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
+            - ``domainSchema``: The schema name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a data use case domain, this attribute value is `undefined`. `Data use case domains <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4743FDE1-7C6E-471B-BC9D-442383CCA2F9>`__ are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
             - ``fetchType``: One of the :ref:`Node-oracledb Type Constant <oracledbconstantsnodbtype>` values.
             - ``isJson``: Indicates if the column is known to contain JSON data. This will be ``true`` for JSON columns (from Oracle Database 21c) and for LOB and VARCHAR2 columns where "IS JSON" constraint is enabled (from Oracle Database 19c). This property will be ``false`` for all the other columns. It will also be ``false`` for any column when Oracle Client 18c or earlier is used in Thick mode or the Oracle Database version is earlier than 19c.
             - ``isOson``: Indicates if the column is known to contain binary encoded OSON data. This attribute will be ``true`` in Thin mode and while using Oracle Client version 21c (or later) in Thick mode when the "IS JSON FORMAT OSON" check constraint is enabled on BLOB and RAW columns. It will be set to ``false`` for all other columns. It will also be set to ``false`` for any column when the Thick mode uses Oracle Client versions earlier than 21c. Note that the "IS JSON FORMAT OSON" check constraint is available from Oracle Database 19c onwards.
             - ``isSparseVector``: Indicates if the column is known to contain a sparse vector. This will be ``true`` for vector columns containing sparse vectors.
-            - ``name``: The column name follows Oracle’s standard name-casing rules. It will commonly be uppercase, since most applications create tables using unquoted, case-insensitive names.
+            - ``name``: The unique column name chosen by node-oracledb. It follows Oracle’s standard name-casing rules. It will commonly be uppercase, since most applications create tables using unquoted, case-insensitive names. If the query does not contain duplicate columns, this value will be the same as the actual database column name. If the query contains duplicate columns, the this attribute will create unique column names by appending an underscore and a unique number.
             - ``nullable``: Indicates whether ``NULL`` values are permitted for this column.
             - ``precision``: Set only for ``oracledb.DB_TYPE_NUMBER``, ``oracledb.DB_TYPE_TIMESTAMP``, ``oracledb.DB_TYPE_TIMESTAMP_TZ``, and ``oracledb.DB_TYPE_TIMESTAMP_LTZ`` columns.
             - ``scale``: Set only for ``oracledb.DB_TYPE_NUMBER`` columns.
-            - ``vectorDimensions``: The number of dimensions of the VECTOR column. If the column is not a VECTOR column or allows for any number of dimensions, then the value of this property is *undefined*.
-            - ``vectorFormat``: The storage format of each dimension value in the VECTOR column. If the column is not a VECTOR column or allows for any storage format, then the value of this property is *undefined*.
+            - ``vectorDimensions``: The number of dimensions of the VECTOR column. If the column is not a VECTOR column or allows for any number of dimensions, then the value of this attribute is *undefined*.
+            - ``vectorFormat``: The storage format of each dimension value in the VECTOR column. If the column is not a VECTOR column or allows for any storage format, then the value of this attribute is *undefined*.
 
             .. versionchanged:: 6.8
 

doc/src/user_guide/bind.rst

@@ -19,15 +19,32 @@ and ``:country_name`` are the two bind variables in this SQL statement:
      {country_id: 90, country_name: "Tonga"}
    );
 
-IN binds are values passed into the database. OUT binds are used to
-retrieve data. IN OUT binds are passed in, and may return a different
-value after the statement executes.
+As part of execution, the supplied bind variable values ``90`` and
+``"Tonga"`` are substituted for the placeholders by the database. This is
+called binding.
 
-.. note::
+Using bind variables is important for scalability and security. They help
+avoid SQL Injection security problems because data is never treated as part of
+an executable statement when it is parsed.
 
-    Using bind parameters is recommended in preference to constructing SQL or
-    PL/SQL statements by string concatenation or template literals. This is
-    for performance and security.
+Bind variables reduce parsing and execution costs when statements are executed
+more than once with different data values. If you do not use bind variables,
+Oracle must reparse and cache multiple statements. When using bind variables,
+Oracle Database may be able to reuse the statement execution plan and context.
+
+.. important::
+
+    Never concatenate or interpolate user data into SQL statements.
+
+    .. code-block:: javascript
+
+        const did = 280;
+        const dnm = "Facility";
+
+        // !! Never do this !!
+        const sql = `INSERT INTO departments (department_id, department_name)
+                  VALUES ({did}, '{dnm}')`;
+        await connection.execute(sql);
 
 Inserted data that is bound is passed to the database separately from
 the statement text. It can never be executed directly. This means there
@@ -44,6 +61,9 @@ used for direct substitution of column or table names in dynamically
 constructed statements, see :ref:`Binding Column and Table Names in
 Queries <sqlbindtablename>`.
 
+Bind parameters can be :ref:`IN <inbind>`, :ref:`OUT <outbind>`, or
+:ref:`IN OUT <outbind>` and are detailed in the subsequent sections.
+
 Bind variables cannot be used in `DDL <https://www.oracle.com/pls/topic/
 lookup?ctx=dblatest&id=GUID-FD9A8CB4-6B9A-44E5-B114-EFB8DA76FC88>`__
 statements, for example ``CREATE TABLE`` or ``ALTER`` commands.