Tenant Id and Module Name Restrictions

Truncation problem

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.

Tenant id foo and module name bar-baz result in schema name foo_bar_baz.

Tenant id 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 and 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:

• CURRENT_CATALOG
• CURRENT_DATE
• CURRENT_ROLE
• CURRENT_TIME
• CURRENT_TIMESTAMP
• CURRENT_USER
• SESSION_USER

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 current or 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.

Other restrictions

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).

Solution

Proposed solution:

Limit tenant id to 31 bytes. Disallow underscore in tenant id. Regexp: [a-z][a-z0-9]{0,30}

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.
• Regexp: [a-z]([a-z0-9]|-(?=[a-z])){0,30}
• Disallow these module names: catalog, date, role, time, timestamp, user

Migration

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.

mod-data-import-converter-storage rename

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.

References