Merge pull request #36 from OraMUC/feature-tenant-support

Feature tenant support

Author: ogobrecht

README.md

@@ -1,4 +1,5 @@
 <!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file src/OM_TAPIGEN.pks -->
+<!-- markdownlint-disable MD003 MD012 MD033 -->
 
 Oracle PL/SQL Table API Generator
 =================================
@@ -14,8 +15,9 @@ Oracle PL/SQL Table API Generator
 <h2><a id="om_tapigen"></a>Package om_tapigen</h2>
 <!----------------------------------------------->
 
-_This table API generator can be integrated in the Oracle SQL-Developer with an
-additional wrapper package for the [SQL Developer extension oddgen](https://www.oddgen.org/)._
+_This table API generator needs an Oracle DB version 12.1 or higher and can be
+integrated in the Oracle SQL-Developer with an additional wrapper package
+for the [SQL Developer extension oddgen](https://www.oddgen.org/)._
 
 The effort of generated API's is to reduce your PL/SQL code by calling standard
 procedures and functions for usual DML operations on tables. So the generated
@@ -34,18 +36,20 @@ FEATURES
 - Generates small wrappers around your tables
 - Highly configurable
 - You can enable or disable separately insert, update and delete functionality
-- Standard CRUD methods (column and row type based) and an additional create
-  or update method
+- Standard CRUD methods (column and row type based) and an additional create or update method
 - Set based methods for high performance DML processing
 - For each unique constraint a read method and a getter to fetch the primary key
-- Functions to check if a row exists (primary key based, returning boolean or
-  varchar2)
+- Functions to check if a row exists (primary key based, returning boolean or varchar2)
 - Support for audit columns
 - Support for a row version column
 - Optional getter and setter for each column
 - Optional 1:1 view to support the separation of concerns (also known as ThickDB/SmartDB/PinkDB paradigm)
 - Optional DML view with an instead of trigger to support low code tools like APEX
 
+PREREQUISITES
+
+- Oracle 12.1 or higher
+
 LICENSE
 
 - [The MIT License (MIT)](https://github.com/OraMUC/table-api-generator/blob/master/LICENSE.txt)
@@ -79,7 +83,7 @@ SIGNATURE
 ```sql
 PACKAGE om_tapigen AUTHID CURRENT_USER IS
 c_generator         CONSTANT VARCHAR2(10 CHAR) := 'OM_TAPIGEN';
-c_generator_version CONSTANT VARCHAR2(10 CHAR) := '0.5.2.34';
+c_generator_version CONSTANT VARCHAR2(10 CHAR) := '0.5.2.39';
 ```
 
 
@@ -124,6 +128,7 @@ PROCEDURE compile_api
   p_audit_column_mappings       IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided comma separated column names are excluded and populated by the API (you don't need a trigger for update_by, update_on...).
   p_audit_user_expression       IN VARCHAR2 DEFAULT c_audit_user_expression, -- You can overwrite here the expression to determine the user which created or updated the row (see also the parameter docs...).
   p_row_version_column_mapping  IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided column name is excluded and populated by the API with the provided SQL expression (you don't need a trigger to provide a row version identifier).
+  p_tenant_column_mapping       IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided column name is hidden inside the API, populated with the provided SQL expression and used as a tenant_id in all relevant API methods.
   p_enable_custom_defaults      IN BOOLEAN  DEFAULT FALSE, -- If true, additional methods are created (mainly for testing and dummy data creation, see full parameter descriptions).
   p_custom_default_values       IN XMLTYPE  DEFAULT NULL   -- Custom values in XML format for the previous option, if the generator provided defaults are not ok.
 );
@@ -174,6 +179,7 @@ FUNCTION compile_api_and_get_code
   p_audit_column_mappings       IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided comma separated column names are excluded and populated by the API (you don't need a trigger for update_by, update_on...).
   p_audit_user_expression       IN VARCHAR2 DEFAULT c_audit_user_expression, -- You can overwrite here the expression to determine the user which created or updated the row (see also the parameter docs...).
   p_row_version_column_mapping  IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided column name is excluded and populated by the API with the provided SQL expression (you don't need a trigger to provide a row version identifier).
+  p_tenant_column_mapping       IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided column name is hidden inside the API, populated with the provided SQL expression and used as a tenant_id in all relevant API methods.
   p_enable_custom_defaults      IN BOOLEAN  DEFAULT FALSE, -- If true, additional methods are created (mainly for testing and dummy data creation, see full parameter descriptions).
   p_custom_default_values       IN XMLTYPE  DEFAULT NULL   -- Custom values in XML format for the previous option, if the generator provided defaults are not ok.
 ) RETURN CLOB;
@@ -226,6 +232,7 @@ FUNCTION get_code
   p_audit_column_mappings       IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided comma separated column names are excluded and populated by the API (you don't need a trigger for update_by, update_on...).
   p_audit_user_expression       IN VARCHAR2 DEFAULT c_audit_user_expression, -- You can overwrite here the expression to determine the user which created or updated the row (see also the parameter docs...).
   p_row_version_column_mapping  IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided column name is excluded and populated by the API with the provided SQL expression (you don't need a trigger to provide a row version identifier).
+  p_tenant_column_mapping       IN VARCHAR2 DEFAULT NULL,  -- If not null, the provided column name is hidden inside the API, populated with the provided SQL expression and used as a tenant_id in all relevant API methods.
   p_enable_custom_defaults      IN BOOLEAN  DEFAULT FALSE, -- If true, additional methods are created (mainly for testing and dummy data creation, see full parameter descriptions).
   p_custom_default_values       IN XMLTYPE  DEFAULT NULL   -- Custom values in XML format for the previous option, if the generator provided defaults are not ok.
 ) RETURN CLOB;

docs/changelog.md

@@ -43,6 +43,7 @@ Please use for all comments, discussions, feature requests or bug reports the Gi
 - added: double quoting of table and column names can now be configured (parameter p_double_quote_names, default true)
 - added: update function with return clause (mainly for use in create_or_update_row to prevent read row after update)
 - added: unit tests with utPLSQL (it will be a permanent task to improve the tests with every new feature or bugfix)
+- removed: support for database versions < 12.1 - if this is a problem for you then use the generator version 0.5.2 (without all the new features, sorry...)
 - removed: support for a generic change log (parameter p_enable_generic_change_log - makes no sense anymore with bulk processing and multi column primary keys)
 - removed: prevent updates if columns do not differ (remove was needed to support all possible column types and for performance reasons)
 - removed: parameter p_reuse_existing_api_params (usage was was not logic, simply provide always your needed parameters and create scripts or a wrapper)

docs/parameters.md

@@ -38,6 +38,7 @@
 - [p_audit_column_mappings (since v0.6.0)](#p_audit_column_mappings-since-v060)
 - [p_audit_user_expression (since v0.6.0)](#p_audit_user_expression-since-v060)
 - [p_row_version_column_mapping (since v0.6.0)](#p_row_version_column_mapping-since-v060)
+- [p_tenant_column_mapping (since v0.6.0)](#p_tenant_column_mapping-since-v060)
 - [p_enable_custom_defaults (since v0.5.0)](#p_enable_custom_defaults-since-v050)
 - [p_custom_default_values (since v0.5.0)](#p_custom_default_values-since-v050)
 - [Removed Parameters](#removed-parameters)
@@ -223,6 +224,15 @@
 - Supports column prefix placeholders to be able to reuse the same mappings in multiple tables with different column_prefixes
 - Example with a global version sequence: `#PREFIX#_VERSION_ID=tag_global_version_sequence.nextval`
 
+## p_tenant_column_mapping (since v0.6.0)
+- String (varchar2), default: null
+- If not null, the provided column name is excluded from the parameters and appended to all primary key where clauses with the provided SQL expression
+- If you have unique keys in your tables you should make sure the tenant column is part of it, otherwise the unique key based read_row methods are not filtering correct
+- For the ref cursor based bulk fetch method `read_rows` the API cannot do anything for you, because the ref cursor is defined outside the API - you need to make sure that all view provided to the users are secured correct with an appropriate where clause - the generated DML and 1:1 views do this also
+- You should consider to hide your column from standard `select *` queries: Also see [Invisible Columns in Oracle Database 12c Release 1 (12.1)](https://oracle-base.com/articles/12c/invisible-columns-12cr1)
+- Supports column prefix placeholders to be able to reuse the same mappings in multiple tables with different column_prefixes
+- Example: `#PREFIX#_TENANT_ID=to_number(sys_context('my_sec_ctx','my_tenant_id'))`
+
 ## p_enable_custom_defaults (since v0.5.0)
 
 - Boolean, default: false