Prefix guidance contradicts itself; update for database.name as the schema namespace

Library proposal: datajoint/datajoint-python#1582 (database.name namespaces schema names on MySQL as it does on PostgreSQL).

how-to/deploy-production.md §Use Database Prefixes:
- It teaches database.database_prefix / DJ_DATABASE_PREFIX with manual concatenation (dj.Schema(prefix + 'subject')).
- It does so under a banner saying the setting is deprecated and "will be removed in 2.3", with replacement advice that covers only PostgreSQL.
- The same page uses DJ_DATABASE_PREFIX in its environment, Docker Compose and checklist examples (lines ~203, 221, 288, 311–312, 336); one of these is a validation function that requires database_prefix in production.
how-to/configure-database.md: it says database.name is "PostgreSQL only" and that setting it on MySQL emits a warning (line 72, §Database Name).
reference/configuration.md: it says database.name is for PostgreSQL connections and database_prefix is "deprecated — use database.name instead" (lines 25, 28, 269), without saying what that means on MySQL.

A MySQL user who reads all three ends up with no supported way to separate projects.

configure-database.md:
- Describe database.name as the namespace on both backends: the database on PostgreSQL, a schema-name prefix (name_) on MySQL.
- Add a short example with two projects on one server, and update the settings table.
deploy-production.md: rewrite §Use Database Prefixes as "Separate projects on a shared server".
- Set DJ_DATABASE_NAME per project; pipelines write plain schema names.
- Grant by pattern on MySQL (lab\_project\_%) and by database on PostgreSQL.
- Show the migration from hand-made prefixes.
- Replace DJ_DATABASE_PREFIX in the environment, Compose and checklist examples.
reference/configuration.md: new descriptions for both settings and a version note on database.name.
Version admonitions: "Changed in 2.x" on database.name; on database_prefix, drop "removed in 2.3".

Two rules from the review of datajoint/datajoint-python#1583, for the docs this issue asks for:

On MySQL, database.name may not contain an underscore. It becomes the prefix name + "_" of every schema name, and an underscore would let one namespace's prefix begin another's (lab_ begins lab_proj_). Such a name raises a DataJointError. PostgreSQL allows underscores, since there the name selects a database.
A schema name that already starts with the prefix is used as is, with a warning. Pipelines that add the prefix themselves keep reaching the same schemas after they set database.name. As a consequence, under lab, dj.Schema("lab_notes") and dj.Schema("notes") name the same schema. The migration section should say to drop the hand-built prefix once database.name is set.

Navigation Menu