This decision has been migrated to the Technical Council's Decision Log as part of a consolidation effort. See: DR-000002 - Tenant Id and Module Name Restrictions
PostgreSQL silently truncates identifiers after 63 bytes.
The PostgreSQL schema name is <tenant id>_<module name>. Truncation may result in the same schema name, for example for mod-inventory and mod-inventory-storage.
Name clash problem
The PostgreSQL schema name is <tenant id>_<module name> with minus/hyphen converted to underscore.
foo and module name
bar-baz result in schema name
foo-bar and module name
baz result in the same schema name
foo_bar_baz resulting in a name clash.
Module name uniqueness problem
A PostgreSQL schema name is case insensitive, and the module converts minus/hyphen to underscore because minus/hyphen is not allowed in a PostgreSQL schema name.
However, Okapi's module name is case sensitive and may contain lower and upper case letters. And it allows both minus/hyphen and underscore.
The module names
Mod_Foo result in the same PostgreSQL schema name when created for the same tenant.
Reserved key word problem
PostgreSQL has a few reserved key words with underscore:
Trying to use them as a schema name results in a syntax error.
Example: If a module has name
user then enabling it for tenant id
session will fail.
Kubernetes and AWS ECS label problem
Kubernetes label names must follow the DNS label standard:
- contain at most 63 characters
- contain only lowercase alphanumeric characters or '-'
- start with an alphabetic character
- end with an alphanumeric character
Labels like mod-inventory-storage-23-0-2 are commonly used and may exceed the maximum length if a long module name is combined with a long version number.
AWS ECS has these restrictions:
- Service Name: Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
- TargetGroup Name: A maximum of 32 alphanumeric characters including hyphens are allowed, but the name must not begin or end with a hyphen.
The existing module name mod-data-import-converter-storage already exceeds this 32 character limit. Sysops have assigned a special TargetGroup Name for this module, such a workaround should be avoided.
The problems stated above need to be solved.
More restrictions exist that are already enforced:
- Tenant id must not begin with a digit because PostgreSQL schema names must not begin with a digit. This is already enforced by PostgreSQL.
- Okapi restricts tenant id letters to be lower case and a-z. Accented letters and unicode characters are not allowed. (Okapi's regexp)
- Okapi doesn't allow a module name to contain a minus/hyphen followed by a digit because this starts the version suffix (Okapi's ModuleId parsing).
Limit tenant id to 31 bytes. Disallow underscore in tenant id. Regexp:
Restrictions for back-end modules:
- Module name can contain only lowercase letters, digits and minus. Start with a letter. Disallow minus followed by a digit or a minus.
- Limit module name to 31 bytes. Disallow uppercase letters. Disallow underscore.
- Disallow these module names:
Some FOLIO installations use tenant ids with underscore that is no longer allowed.
One back-end module fails the new module name restrictions:
- mod-data-import-converter-storage is 33 bytes long exceeding the length limit of 31 bytes.
Tenant name migration
To reduce the downtime in multi-tenant installations it must be possible to migrate one tenant at a time.
Okapi and the modules should provide APIs and/or scripts to do the migration.
A shorter name for this repository and module name
might be mod-data-import-conv-storage with only 28 bytes will be mod-di-converter-storage with only 24 bytes (MODDICONV-259).
Follow guide https://dev.folio.org/guides/rename-module/
When the renamed module executes the tenant upgrade it checks whether the schema name with the old module name still exists. If yes it is renamed, the PostgreSQL ROLE is renamed and a new ROLE password is assigned if needed.