As mentioned in A General Overview of Database Mapping , DB Mapping is available with the launch of cPanel 11.25.1. Let’s recap what DB Mapping is and then we can chew on the details:
- DB Mapping is core code in 11.25.1
- DB Mapping exposes DB Prefixing behaviors
- DB Mapping provides an interface for importing non-cPanel accounts
Core Code
DB Mapping is coded directly into cPanel. This includes modifications to our binary code base as well as the Perl Cpanel modules. We’ve packed in more methods and dynamic code paths that allow cPanel to function in a forward-capable mode. We have chosen to use new models in our instantiated objects that expose new functionalities and at the same time can be rendered into the 11.25.0 user model.
This new functionality is, well new, and can’t always be converted to an old convention. For example, account transfers benefit tremendously from DB Mapping functionality, yet are bound to coding practicalities. Products of a new, complex code base cannot be manipulated to work in an older code base; something new can only exist in the environment for which it was designed. To put it simply, DB Mapping features are not 100% backwards compatible.
DB Prefixing
Prefixing database resources is a very common practice in web hosting environments. In cPanel versions prior to 11.25.1, any database resource created by a user receives a prefix, $username_. In 11.25.1, the DB Mapping code allows the cPanel admin to turn this prefixing requirement/implementation off. DB Mapping decouples the textual name of the resource from the account name and stores the information separately.
Mapping occurs regardless of whether Prefixing is On or Off. You can find the Prefix toggle in the SQL Services section of WHM. Again, mapping is embedded in the core of cPanel which provides an easy way for cPanel admins to Opt-Out of the Prefix paradigm. Prefixing is On by default in 11.25.1 and the cPanel interface will continue to behave and render identical to previous versions.
If you turn Prefixing Off you cannot turn it back on. Additionally, you will not be able to downgrade to a cPanel version that does not have DB Mapping, e.g. 11.25.0 and below. Disabling Prefixing is a one way street.
The mapping is stored in a YAML file in /var/cpanel/databases/ as $username.yaml. These YAML files are system files and should be respected as such, e.g., manual manipulation is discouraged and can have unintended consequence. The files should be edited indirectly via the SQL cPanel interfaces or related API calls. If you find that database resources are not mapped as expected, cPanel Support can help you resolve the issue.
Non-cPanel Transfers
cPanel strives to make account migration as seamless as possible. You can imagine how daunting a task that is when you consider the number of other web hosting environments available and the variety between them. DB Mapping abstracts cPanel accounts and database resource ownership. This allows cPanel to import any account-database relationship from a non-cPanel account and keep all attached resources intact, without any manipulation*.
If a non-cPanel account is transferred to cPanel 11.25.1, it will utilize the DB Mapping feature set. This is great because the account is essentially mirrored in the cPanel host system. However, this also means that the migrated account is dependent on DB Mapping. Once you transfer a non-cPanel account, your system is not a candidate for downgrade. This is the same logic as disabling Prefixing: your accounts require the DB Mapping feature set.
For transferred accounts, the migrated account is permitted an account username up to 16 characters long, a primary database username that is different than the account username, and databases that have an arbitrary prefix**.
If your transferred account has an extremely long username, and you have not disabled Prefixing, you may find that there is inadequate character length for new database resources. For example, if the non-cPanel account has a name like accountlongname and you have Prefixing On, then all database resources will start with accountlongname_. accountlongname_ is 16 characters long. MySQL imposes a 16-character limit on database usernames and thus the account would not be able to create database virtusers in cPanel. DB Mapping is very flexible, but ultimately must operate within the confines of the MySQL sub-system. It’s a caveat, but not one that an informed administrator should be surprised by.
Long username functionality for non-cPanel transfers should be available immediately in the EDGE release of 11.25.1. Our Migration Support Services are available to you and at the ready as needed.
API and Other Tidbits
When making API calls, specifically the functions in the Mysql module, some diligence may be required on the developer’s part. For instance, adddb takes one parameter, the $dbname. In 11.25.0, $dbname is automatically prefixed with $username_ by cPanel. The $username prefix is determined by the $user parameter required by all API1 calls. In 11.25.1, $dbname will not be prefixed if Prefixing is Off. The value of $dbname is taken literally by cPanel. The chance for database name collision is increased, but like before, is not fatal. If a collision occurs, you will receive an error and will need to choose a different database name.
Likewise, when you call adduserdb, which modifies a vituser’s privileges for a database, as the developer you need to know if Prefixing is On or Off. adduserdb needs the literal database name in 11.25.1. The same call in 11.25.0 will assume $username_ if it is not present in $dbname.
New accounts created in 11.25.1, that aren’t transfer related, can also have a primary database username that differs from the account username if Prefixing is Off. Just keep in mind that if you create such an account, it is not feasible to move it to a cPanel system whose version is less than 11.25.1. Again, any account made with Prefixing disabled cannot be transferred to a cPanel version below 11.25.1; doubly so for any account who’s primary database username differs from the cPanel account username.
More Information
DB Mapping is a powerful feature set. It opens a lot of possibilities for cPanel administrators and end users. These blog posts can only cover the concepts though. You can expect detailed information in the 11.25.1 Release Notes as well as a white paper on DB Mapping. Both are forthcoming so stay tuned.
Have fun with DB Mapping and post your comments and questions on our Developer Discussion Forum!
*Not withstanding some core OS and sub-system limitations, like user group name length, or MySQL database user name length.
**The usual restriction applies that any resource name cannot conflict with an existing, identically-named resource on the host system.
