Skip to content

Commit

Permalink
Revert "#301 - Fixed asciidoc"
Browse files Browse the repository at this point in the history 
This reverts commit c40ae89.
  • Loading branch information
@starnowski
starnowski committed Mar 6, 2024
1 parent 55f4189 commit 04f6ad3
Showing 1 changed file with 54 additions and 69 deletions.
123 changes: 54 additions & 69 deletions ...ion-parent/configuration-jar/src/main/resources/configuration-yaml-interpreter-readme.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Configuration-yaml-interpreter
# Configuration-yaml-interpreter

The configuration-yaml-interpreter module can interpreted configuration file in yaml format and based on that it creates
DDL statements that allows to create the shared schema strategy.
Expand All @@ -12,7 +12,7 @@ The YAML schema description is below.
- #custom-sql-definitions
- #details

## Simple example:
## Simple example:

Bellow, there is a configuration example for a schema with the name "public".
The schema contains four tables, users, posts, groups, and users\_groups (many-to-many relation).
Expand Down Expand Up @@ -73,29 +73,28 @@ tables:
group_id: uuid
```

## Root properties

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
|#default_schema | String | Yes | Yes | Name of the database schema for which changes should be applied. |
|#current_tenant_id_property_type | String | No | No | Type of column that stores tenant identifier and it is also the type of parameters for some generated functions. |
|#current_tenant_id_property | String | No | No | Property name that stores the value of tenant identifier in the database connection. |
|#get_current_tenant_id_function_name | String | No | No | Name of the function that returns the current tenant identifier. |
|#set_current_tenant_id_function_name | String | No | No | Name of the function that sets the current tenant identifier. |
|#tenant_has_authorities_function_name | String | No | No | Name of the function name that checks if the current tenant has authority to a table row. |
|#force_row_level_security_for_table_owner | Boolean | No | Yes | Option that force RLS policy for table owner. |
|#default_tenant_id_column | String | No | No | Default name of column that stores tenant identifier. |
|#grantee | String | Yes | No | Database user for which RLS policy is going to be created. |
|#create_foreignkey_constraint_with_tenant_column | Boolean | No | Yes | Create the foreign key constraint that tenant column is part of composite key. Instead of function that check if reference key exist for specific tenant. |
## Root properties

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|---------------|
|#default_schema | String | Yes | Yes | Name of the database schema for which changes should be applied. |
|#current_tenant_id_property_type | String | No | No | Type of column that stores tenant identifier and it is also the type of parameters for some generated functions. |
|#current_tenant_id_property | String | No | No | Property name that stores the value of tenant identifier in the database connection. |
|#get_current_tenant_id_function_name | String | No | No | Name of the function that returns the current tenant identifier. |
|#set_current_tenant_id_function_name | String | No | No | Name of the function that sets the current tenant identifier. |
|#tenant_has_authorities_function_name | String | No | No | Name of the function name that checks if the current tenant has authority to a table row. |
|#force_row_level_security_for_table_owner | Boolean | No | Yes | Option that force RLS policy for table owner. |
|#default_tenant_id_column | String | No | No | Default name of column that stores tenant identifier. |
|#grantee | String | Yes | No | Database user for which RLS policy is going to be created. |

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|---------------|
|#equals_current_tenant_identifier_function_name | String | No | No | Name of the function name that checks if passed identifier is the same as the current tenant identifier. |
|#set_current_tenant_identifier_as_default_value_for_tenant_column_in_all_tables | Boolean | No | Yes | Generate a statement that sets a default value for the tenant column in all tables. |

## Setting a list of invalid tenant identifier values
## Setting a list of invalid tenant identifier values

The valid_tenant_value_constraint object is used to configure constraint that will be added to all tenant column in all tables.
The valid_tenant_value_constraint object is used to configure constraint that will be added to all tenant column in all tables.
Constraint keeps tenant column value valid.

| Property name | Type | Required | Nullable | Description |
Expand All @@ -115,14 +114,14 @@ valid_tenant_value_constraint:

For more information please check https://github.com/starnowski/posmulten#setting-a-list-of-invalid-tenant-identifier-values.

## Tables configuration
## Tables configuration

The tables property is an array of objects that each references to a single table.
The tables property is an array of objects that each references to a single table.
The table object ables to configure things like the RLS policy or the constraint that checks if the foreign key belongs to the same tenant as a current logged tenant.
It is not mandatory to configure all tables. In some cases, there is no sense to create an entry for the table.
For example, tables that are supposed to use by all tenants, like dictionary tables, do not need to have a configured RLS policy.

Table object
Table object

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|---------------|
Expand All @@ -131,7 +130,7 @@ For example, tables that are supposed to use by all tenants, like dictionary tab
|#rls_policy | Object | No | No | Object that defines RLS for table |
|#foreign_keys | Array of objects | No | No | An array of objects that defines foreign key constraint for a table with RLS policy |

### rls_policy
### rls_policy

The rls\_policy entry is required to specify the RLS policy for table.

Expand All @@ -144,14 +143,14 @@ The rls\_policy entry is required to specify the RLS policy for table.
|#skip_adding_of_tenant_column_default_value | Boolean | No | No | Option force to skip adding default value to tenant column for a table |
|#primary_key_definition | Object | No | No | Object that defines primary keys for a table |

### primary_key_definition
### primary_key_definition

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|------------------------------------------------------------------------------------------------------------------------------|---------------|---------------|
|#pk_columns_name_to_type | Map | No | Yes | Map of primary key columns where the key is column name and value is its type |
|#name_for_function_that_checks_if_record_exists_in_table | String | if flag #create_foreignkey_constraint_with_tenant_column is null or false | Yes | Function name that checks if passed primary key for a specific table exists for the current tenant |
| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|---------------|
|#pk_columns_name_to_type | Map | No | Yes | Map of primary key columns where the key is column name and value is its type |
|#name_for_function_that_checks_if_record_exists_in_table | String | Yes | No | Function name that checks if passed primary key for a specific table exists for the current tenant |

### foreign_keys
### foreign_keys

An array of objects that defines foreign key constraint for a table with RLS policy.
Based on each array object, there is going to be created constraint that checks if a foreign key value refers to a record that exists for the current logged tenant.
Expand Down Expand Up @@ -212,14 +211,14 @@ tables:
parent_comment_random_uuid: random_uuid
```

## SQL definitions validation
## SQL definitions validation

The sql_definitions_validation property is used to configure the validation of generated sql definitions.
The sql_definitions_validation property is used to configure the validation of generated sql definitions.
It is a complex type.

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|---------------|
|disabled | Boolean | No | No | Validation toggle, by default property has value false which means that validation is enabled |
|disabled | Boolean | No | No | Validation toggle, by default property has value false which means that validation is enabled |
|identifier\_max\_length | Integer | No | No | Maximum allowed length for the identifier |
|identifier\_min\_length | Integer | No | No | Minimum allowed length for the identifier |

Expand All @@ -232,9 +231,9 @@ sql_definitions_validation:
disabled: false
```

## Custom SQL Definitions
## Custom SQL Definitions

The custom_sql_definitions property is an array of objects that purpose is to define custom SQL definitions that should be added to the generated script.
The custom_sql_definitions property is an array of objects that purpose is to define custom SQL definitions that should be added to the generated script.
Just like the #tables-configuration property, it is also a top element of the configuration file just like in the below example.

Example:
Expand Down Expand Up @@ -263,19 +262,19 @@ custom_sql_definitions:
SELECT (371) FROM ...
```

custom_sql_definitions object
custom_sql_definitions object

| Property name | Type | Required | Nullable | Description |
|---------------|-----------|---------------|---------------|---------------|
|position | String | Yes | No | Specify where definition should be added in generated script. Available values are AT\_END (at the end), AT\_BEGINNING (at the beginning) and CUSTOM. For the CUSTOM the custom_position property has to be also specified |
|position | String | Yes | No | Specify where definition should be added in generated script. Available values are AT\_END (at the end), AT\_BEGINNING (at the beginning) and CUSTOM. For the CUSTOM the custom_position property has to be also specified |
|creation\_script | String | Yes | No | SQL statement added to creation script |
|drop\_script | String | No | No | SQL statement added to dropping script |
|validation\_scripts | Array of strings | Yes | No | SQL statements that check if changes made by creation_script were added. Each statement as result should return one integer column, value bigger than zero means that changes were applied correctly otherwise the changes were not applied |
|custom\_position | String | Only if position has the CUSTOM value | No | Custom position of the script. This does not have to be an integer value. There might be a case that some custom component was added in the code and it handles the definition with a specific position |
|validation\_scripts | Array of strings | Yes | No | SQL statements that check if changes made by creation_script were added. Each statement as result should return one integer column, value bigger than zero means that changes were applied correctly otherwise the changes were not applied |
|custom\_position | String | Only if position has the CUSTOM value | No | Custom position of the script. This does not have to be an integer value. There might be a case that some custom component was added in the code and it handles the definition with a specific position |

## Details
## Details

### default_schema
### default_schema

Name of the database schema for which changes should be applied.

Expand All @@ -291,7 +290,7 @@ default_schema:

For more information please check https://github.com/starnowski/posmulten/tree/master#setting-default-database-schema.

### current_tenant_id_property_type
### current_tenant_id_property_type

Type of column that stores tenant identifier and it is also the type of parameters for some generated functions.
For example, for the below entries:
Expand All @@ -313,7 +312,7 @@ PARALLEL SAFE;

For more information please check https://github.com/starnowski/posmulten/tree/master#setting-of-type-for-tenant-identifier-value.

### current_tenant_id_property
### current_tenant_id_property

Property name that stores the value of tenant identifier in the database connection.
Example:
Expand All @@ -324,7 +323,7 @@ current_tenant_id_property: "pos.c.ten"

For more information please check https://github.com/starnowski/posmulten#setting-the-property-name-that-stores-tenant-identifier-value.

### get_current_tenant_id_function_name
### get_current_tenant_id_function_name

Name of the function that returns the current tenant identifier.
For example, for the below entries:
Expand All @@ -343,7 +342,7 @@ STABLE
PARALLEL SAFE;
```

### set_current_tenant_id_function_name
### set_current_tenant_id_function_name

Name of the function that sets the current tenant identifier.
For example, for the below entries:
Expand All @@ -363,7 +362,7 @@ $$ LANGUAGE plpgsql
VOLATILE;
```

### equals_current_tenant_identifier_function_name
### equals_current_tenant_identifier_function_name

Name of the function name that checks if passed identifier is the same as the current tenant identifier.
For example, for the below entries:
Expand All @@ -382,7 +381,7 @@ STABLE
PARALLEL SAFE;
```

### tenant_has_authorities_function_name
### tenant_has_authorities_function_name

Name of the function name that checks if the current tenant has authority to a table row.
For example, for the below entries:
Expand All @@ -401,7 +400,7 @@ STABLE
PARALLEL SAFE;
```

### force_row_level_security_for_table_owner
### force_row_level_security_for_table_owner

Option that force RLS policy for table owner.
This option is required if the database user for which RLS is created is also a table owner.
Expand All @@ -414,7 +413,7 @@ force_row_level_security_for_table_owner: true

For more information please check https://github.com/starnowski/posmulten#force-rls-policy-for-table-owner.

### default_tenant_id_column
### default_tenant_id_column

The default name of the column that stores the tenant identifier.
This name is used when the table does not have a specified custom name for the column that stores the tenant identifier.
Expand All @@ -426,7 +425,7 @@ default_tenant_id_column: "tenant_uuid"

For more information please check https://github.com/starnowski/posmulten#setting-default-tenant-column-name.

### grantee
### grantee

Database user for which RLS policy is going to be created.
Example:
Expand All @@ -437,20 +436,7 @@ grantee: "application-user"

For more information please check https://github.com/starnowski/posmulten#setting-default-database-user-for-rls-policy.

### create_foreignkey_constraint_with_tenant_column

Create the foreign key constraint that tenant column is part of composite key.
Instead of function that check if reference key exist for specific tenant.

Example:

```yaml
create_foreignkey_constraint_with_tenant_column: true
```

For more information please check https://github.com/starnowski/posmulten#setting-foreign-key-constraint-where-tenant-column-is-part-of-composite-key.

### set_current_tenant_identifier_as_default_value_for_tenant_column_in_all_tables
### set_current_tenant_identifier_as_default_value_for_tenant_column_in_all_tables

Generate a statement that sets a default value for the tenant column in all tables.
This functionality is useful when we don't always want to specified tenant id value in the insert statement.
Expand All @@ -463,7 +449,7 @@ set_current_tenant_identifier_as_default_value_for_tenant_column_in_all_tables:

For more information please check https://github.com/starnowski/posmulten#adding-default-value-for-tenant-column.

### is_tenant_valid_function_name
### is_tenant_valid_function_name

Name of the function that checks if passed tenant identifier is valid.
For example, for the below entries:
Expand All @@ -488,7 +474,7 @@ PARALLEL SAFE;

For more information please check https://github.com/starnowski/posmulten#setting-a-list-of-invalid-tenant-identifier-values.

### is_tenant_valid_constraint_name
### is_tenant_valid_constraint_name

Name of the constraint that checks if the tenant column has a valid value.
For example, for the below entries:
Expand All @@ -509,30 +495,29 @@ ALTER TABLE "posts" ADD CONSTRAINT tenant_must_be_valid CHECK (tenant_id IS NULL

For more information please check https://github.com/starnowski/posmulten#setting-a-list-of-invalid-tenant-identifier-values.

### create_tenant_column_for_table
### create_tenant_column_for_table

Option force to create tenant column for the table.
By default, the Posmulten library assumes that the tenant column exists.
To check what kind of DDL statements are generated for tenant column definition please check the https://github.com/starnowski/posmulten#adding-tenant-column-to-tenant-table.

### skip_adding_of_tenant_column_default_value
### skip_adding_of_tenant_column_default_value

Option force to skip adding default value to tenant column for table.
This option make sense to use when the #set_current_tenant_identifier_as_default_value_for_tenant_column_in_all_tables option is turned on.
It simply allows to skip adding default value definition for tenant column is specified table.
For more information please check https://github.com/starnowski/posmulten#skipping-adding-default-value-for-tenant-column-for-a-single-table.

### pk_columns_name_to_type
### pk_columns_name_to_type

Map of primary key columns where the key is column name and value is its type.
The map can be empty or even null.
This is a valid case for example for a many-to-many relation table without any primary key, just with foreign keys for tables that it refers to.

### name_for_function_that_checks_if_record_exists_in_table
### name_for_function_that_checks_if_record_exists_in_table

Function name that checks if passed primary key for a specific table exists for the current tenant.
This function is generated only when some other table has a #foreign_keys that refers to the primary key table.
if flag #create_foreignkey_constraint_with_tenant_column is null or false then value is mandatory.

For more information please check:

Expand Down

0 comments on commit 04f6ad3

Please sign in to comment.