database.name should namespace schema names on MySQL, as it does on PostgreSQL

Start with Connection.schema_prefix and Connection.qualify_schema_name, then Schema.activate, list_schemas and the MySQL database.name warning, which the linked PR #1583 already changes. Open design questions (separator, already-prefixed names, lineage, opt-out, removal release) need maintainer decisions before any patch. Done means the unit prefix rule and the MySQL and PostgreSQL integration tests pass, and the docs follow-up is written.

What happens now

When several projects share one database server, each project needs its own set of schemas: two pipelines that both declare dj.Schema("subject") must not write to the same tables, and an administrator wants to grant a project's users access to that project's schemas only.

• PostgreSQL: database.name (DJ_DATABASE_NAME) selects the database. Each project gets its own database, the pipeline writes dj.Schema("subject"), and the projects stay apart.

• MySQL: database.name is ignored, with the warning "database.name is set but the MySQL backend does not support database selection". The only way to separate projects is to put a prefix into every schema name in pipeline code:

  prefix = os.environ["MY_PREFIX"]          # or dj.config.database.database_prefix
  subject = dj.Schema(prefix + "subject")
  session = dj.Schema(prefix + "session")
  

• database.database_prefix (DJ_DATABASE_PREFIX): it stores the value but DataJoint never applies it. It is deprecated with the message "will be removed in DataJoint 2.3. Use database.name to select a PostgreSQL database instead". That message is stale on 2.3.x, and it gives MySQL users no replacement.

So the same pipeline is written differently for the two backends. Every MySQL pipeline carries its own prefix handling, and a published example that writes dj.Schema("subject") can't be dropped into a shared MySQL server unchanged.

Proposal

Make database.name the connection's schema namespace on both backends:

• Prefixing. Schema adds the prefix itself, so pipelines write plain schema names on both backends. This also covers VirtualModule, virtual_schema and Schema.activate.
• schema.database. It is the name on the server (lab_project_subject), as it is today for any schema.
• dj.list_schemas(). It lists the namespace's schemas under their plain names (subject), so every name it returns can be passed back to dj.Schema. A connection without database.name still lists every schema it can see.
• Grants. Access is granted by pattern on MySQL (GRANT ... ON \lab_project_%`.*`) and by database on PostgreSQL.
• Already-prefixed names. A name that already starts with the prefix is used as is, with a warning ("write subject instead"). Code that still prefixes by hand keeps reaching the same schemas rather than silently creating lab_project_lab_project_subject.
• database_prefix. It stays deprecated and unapplied. Its message points to database.name, and the "removed in 2.3" text goes.

Compatibility. A MySQL user who sets database.name today gets a warning and no effect. After this change, their schema names gain the prefix: for example, an environment that sets DJ_DATABASE_NAME for a PostgreSQL database and is reused against MySQL. That is a behaviour change, so it belongs in a minor release, with a note in the release notes.

Migration for a MySQL deployment that prefixes by hand with myproject_: set database.name = "myproject", then drop the prefix from the pipeline's dj.Schema(...) calls. The schemas on the server do not change.

Questions to settle

1. Separator. The proposal adds _ itself (name + "_"). The alternative is to take the prefix verbatim, as database_prefix did. Adding _ keeps database.name a name rather than a fragment, and matches the common project_ convention.
2. Already-prefixed names. Should they be used as is with a warning, or raise an error? A warning makes migration safe. The cost is one edge case: with namespace lab, a schema meant to be named lab_session resolves to lab_session rather than lab_lab_session.
3. Lineage. Lineage strings embed the schema's server name (schema.table.attribute). On MySQL the prefix becomes part of them; on PostgreSQL the database name does not. Restoring a namespace under a different name then needs schema.rebuild_lineage() on MySQL only. Should lineage record the plain name instead?
4. Reaching outside the namespace. On PostgreSQL a connection cannot reach another database. On MySQL the prefix confines dj.Schema to the namespace. A shared reference schema outside it would need either a second connection without database.name or an explicit opt-out (e.g. dj.Schema(name, namespace=False)). The proposal leaves the opt-out out of the first version.
5. Removing database_prefix. In which release?

Implementation

The behaviour above is implemented and tested in the linked PR:

• Connection.schema_prefix and Connection.qualify_schema_name;
• Schema.activate applies the prefix, and list_schemas filters and strips it;
• the MySQL warning is removed and the deprecation message updated.

Tests:

• Unit: the prefix rule on both backends.
• Integration (MySQL and PostgreSQL): two namespaces each hold a subject schema with separate contents; list_schemas returns plain names; VirtualModule resolves inside the namespace; an already-prefixed name is not prefixed twice.
• Results: unit 457 passed; integration 694 passed, 16 skipped, both backends.

Related: #1426 (added database.name for PostgreSQL and deprecated database_prefix), #1351 (renamed schema_prefix to database_prefix).

Docs follow-up: how-to/configure-database.md, how-to/deploy-production.md §Use Database Prefixes, reference/configuration.md.