Merge pull request #8448 from kenjis/docs-forge-data-types

docs: add about field data types on Forge

Author: kenjis

user_guide_src/source/dbmgmt/forge.rst

@@ -96,34 +96,67 @@ mechanism for this.
 Adding Fields
 =============
 
+$forge->addField()
+------------------
+
 Fields are normally created via an associative array. Within the array, you must
-include a ``type`` key that relates to the datatype of the field. For
-example, INT, VARCHAR, TEXT, etc. Many datatypes (for example VARCHAR)
-also require a ``constraint`` key.
+include a ``type`` key that relates to the datatype of the field.
+
+For example, ``INT``, ``VARCHAR``, ``TEXT``, etc.
+Many datatypes (for example ``VARCHAR``) also require a ``constraint`` key.
 
 .. literalinclude:: forge/006.php
 
 Additionally, the following key/values can be used:
 
--  ``unsigned``/true : to generate "UNSIGNED" in the field definition.
--  ``default``/value : to generate a default value in the field definition.
--  ``null``/true : to generate "null" in the field definition. Without this,
-   the field will default to "NOT null".
+-  ``unsigned``/true : to generate ``UNSIGNED`` in the field definition.
+-  ``default``/value : to generate ``DEFAULT`` constraint in the field definition.
+-  ``null``/true : to generate ``NULL`` in the field definition. Without this,
+   the field will default to ``NOT NULL``.
 -  ``auto_increment``/true : generates an auto_increment flag on the
    field. Note that the field type must be a type that supports this,
-   such as integer.
+   such as ``INTEGER``.
 -  ``unique``/true : to generate a unique key for the field definition.
 
 .. literalinclude:: forge/007.php
 
 After the fields have been defined, they can be added using
 ``$forge->addField($fields)`` followed by a call to the
-``createTable()`` method.
+:ref:`createTable() <creating-a-table>`  method.
 
-$forge->addField()
-------------------
+Notes on Data Types
+-------------------
+
+Floating-Point Types
+^^^^^^^^^^^^^^^^^^^^
 
-The ``addField()`` method will accept the above array.
+Floating-Point types such as ``FLOAT`` and ``DOUBLE`` represent approximate values.
+Therefore, they should not be used when exact values are needed.
+
+::
+
+    mysql> CREATE TABLE t (f FLOAT, d DOUBLE);
+    mysql> INSERT INTO t VALUES(99.9, 99.9);
+
+    mysql> SELECT * FROM t WHERE f=99.9;
+    Empty set (0.00 sec)
+
+    mysql> SELECT * FROM t WHERE f > 99.89 AND f < 99.91;
+    +------+------+
+    | f    | d    |
+    +------+------+
+    | 99.9 | 99.9 |
+    +------+------+
+    1 row in set (0.01 sec)
+
+When it is important to preserve exact precision, for example with monetary data,
+``DECIMAL`` or ``NUMERIC`` should be used.
+
+TEXT
+^^^^
+
+``TEXT`` should not be used on SQLSRV. It is deprecated.
+See `ntext, text, and image (Transact-SQL) - SQL Server | Microsoft Learn <https://learn.microsoft.com/en-us/sql/t-sql/data-types/ntext-text-and-image-transact-sql?view=sql-server-ver16>`_.
 
 .. _forge-addfield-default-value-rawsql:
 
@@ -209,6 +242,8 @@ You can specify the desired action for the "on update" and "on delete" propertie
 
 .. note:: SQLite3 does not support the naming of foreign keys. CodeIgniter will refer to them by ``prefix_table_column_foreign``.
 
+.. _creating-a-table:
+
 Creating a Table
 ================
 

user_guide_src/source/dbmgmt/forge/007.php

@@ -27,3 +27,4 @@
         'default'    => 'pending',
     ],
 ];
+$forge->addField($fields);

user_guide_src/source/dbmgmt/forge/025.php

@@ -1,4 +1,4 @@
 <?php
 
-$forge->dropColumn('table_name', 'column_1,column_2'); // by proving comma separated column names
+$forge->dropColumn('table_name', 'column_1,column_2');      // by proving comma separated column names
 $forge->dropColumn('table_name', ['column_1', 'column_2']); // by proving array of column names

user_guide_src/source/dbmgmt/forge/028.php

@@ -1,5 +1,5 @@
 <?php
 
-// MySqli Produces: ALTER TABLE `tablename` DROP PRIMARY KEY
+// MySQLi Produces: ALTER TABLE `tablename` DROP PRIMARY KEY
 // Others Produces: ALTER TABLE `tablename` DROP CONSTRAINT `pk_tablename`
 $forge->dropPrimaryKey('tablename');