database guidelines

modules/developer_manual/pages/app/fundamentals/database.adoc

@@ -42,6 +42,29 @@ class AuthorDAO {
 }
 ----
 
+Database programming guidelines
+-------------------------------
+
+* Always use the Query Builder
+* Don't update more than 1 million rows within a transaction due to DB limitations
+* Don't add more than 999 conditions in a `WHERE ... IN ...` statement but chunk it into separate queries when using SQLite
+* When processing big tables, always do this in chunks, don't store the whole table in memory
+* Oracle compatibility specifics:
+** For Oracle `null` and empty strings are the same thing. Need special handling to catch these cases
+** When reading values, make sure to convert null to empty string when expected
+** Keep this in mind when designing DB schema and values expectations.
+** When using a condition based on empty strings, use `is not null` with Oracle instead
+** Oracle can only compare the first 4000 bytes of a `CLOB` column
+** Make sure to properly escape column names when using custom functions with `createFunction`. the escaping is usually done automatically by the query builder otherwise. Oracle is the most likely to complain about unquoted columns while other databases will work fine
+* Always add the table name when calling `lastInsertId($tableName)`, it is required by Oracle to return correct values
+* In general don't specify a value for autoincrement column. if you have to, keep in mind that Oracle's autoincrement trigger will get in the way on `INSERT`, so you'll need a subsequent `UPDATE` to properly adjust the value
+* *Always* make sure there are unit tests for the database operations with queries to verify the result, this will help find out whether the database related code works on all databases and often times might reveal database quirks
+* Running unit tests with specific databases:  `make test-php TEST_PHP_SUITE=path/to/test/file.php TEST_DATABASE=$databasetype` where "$databasetype" is one of "sqlite", "mysql", "mariadb", "pgsql", "oci" and "mysqlmb4"
+* String concatenation should be done like this:
+** `CONCAT(str1, str2, ... strN)` for Mysql
+** `str1 || str1 ... || strN` Sqlite/PgSQL/Oracle
+* Use `IQueryBuilder::createPositionalParameter` instead of `IQueryBuilder::createNamedParameter` when using `like()`
+
 [[mappers]]
 Mappers
 -------