Hi Yufei, Thanks for raising this — it's a fair point, and I agree it's worth the community weighing in.
I looked into how MySQL handles this and tested it against a real MySQL instance (Connector/J 9.1.0). A couple of findings that, I think, let the driver-configuration approach hold up even with MySQL in the picture: - MySQL has no notion of a schema below a database — "schema" and "database" are synonyms there. The namespace is selected by the database in the JDBC URL, which is exactly what the MySQL PR (#4281) already does: jdbc:mysql://<host>:3306/POLARIS_SCHEMA. So MySQL's namespace is also selected through standard datasource configuration; it's just a different property, because that is how MySQL natively models it. In both cases the persistence layer stays agnostic of the schema name. - The shipped currentSchema default is harmless on MySQL. It is set on the default (PostgreSQL) datasource, and #4281 exposes MySQL as a separate named datasource, so it does not apply there. And even if it were applied, MySQL Connector/J silently ignores currentSchema — I verified that it connects without error and the property simply has no effect. (A database in the URL also overrides currentSchema on both PostgreSQL and MySQL.) So a Polaris-owned generic schema-name would not actually buy MySQL anything: there is nothing below the database for it to translate to, so it would either no-op or duplicate the URL database — while reintroducing the extension-point change and the per-driver quoting/casing logic that this rework removed. That said, the generic approach does offer one real thing: a single uniform knob, so operators don't have to know each driver's idiom. My preference is the driver-configuration approach, but I'm genuinely fine either way, and if the community leans toward the uniform knob it's a bounded change to layer back on. To avoid surprises in the meantime, I've documented in the Helm values that currentSchema is PostgreSQL/CockroachDB-specific and is silently ignored by MySQL (where the schema is the database in the URL). Thanks again for the careful review! Eundo 2026년 7월 22일 (수) 오전 10:10, Yufei Gu <[email protected]>님이 작성: > Thanks a lot for working on this, Eundo. The new approach[1] introduces a > hard dependency on the driver's behavior. It's fine now since the > PostgreSQL driver is the only JDBC driver needed in production. However, > there is an effort to support MySQL. In that case, we may need a different > way to inject the schema name. > The previous approach is a more generic in that regard, though it involves > a bit more complexity. Personally, I'm fine with either approach, but I'd > like to hear more opinions from the community. > > 1. https://github.com/apache/polaris/pull/4945/changes#r3626702105 > > Yufei > > > On Tue, Jul 21, 2026 at 12:40 AM Eundo Lee <[email protected]> wrote: > > > Hi all, > > > > A quick update: the rework discussed on this thread has landed on the PR, > > and it now follows the direction Alex proposed — the Relational JDBC > > persistence layer is completely agnostic of the schema name. > > > > What changed: > > > > - The schema is selected entirely through the JDBC driver's currentSchema > > connection property; the persistence code no longer qualifies SQL, > > validates a schema name, or sets a session schema. There is no > > Polaris-level configuration option and no extension-point change -- > > RelationalJdbcConfiguration is unchanged from main. > > > > - A default is shipped in runtime/defaults and the admin tool > > > > > > > (quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA), > > so upgrades and the out-of-the-box experience are unchanged. A > > currentSchema set in the JDBC URL takes precedence over it (verified > > against PostgreSQL and CockroachDB). > > > > - Polaris no longer issues CREATE SCHEMA: the schema is a prerequisite > > created by a DBA. Fresh deployments are a two-step procedure (create > the > > schema, then bootstrap); this is a documented breaking change. The > > getting-started compose assets and the Helm test fixture create the > > schema at the database-provisioning layer, so the tutorials themselves > > are unchanged. > > > > - The Helm chart exposes persistence.relationalJdbc.additionalProperties > > (default {currentSchema: POLARIS_SCHEMA}), which also leaves room for > > other JDBC driver properties. > > > > The PR is out of draft and ready for review: > > https://github.com/apache/polaris/pull/4945 > > > > Thanks to Alex for the thorough review that got us to a much cleaner > > solution, and to Yufei and Dmitri for the input on the schema-version and > > legacy-script questions. Further review and feedback are very welcome. > > > > Thanks, > > Eundo > > > > 2026년 7월 21일 (화) 오전 11:16, Eundo Lee <[email protected]>님이 작성: > > > > > Hi Alex, > > > > > > Thanks for your input! > > > > > > 1. I'll keep my changes on the PR that add the default > > > quarkus.datasource.jdbc.additional-jdbc-properties.currentSc > > > hema=POLARIS_SCHEMA > > > 2. I'll brainstorm further and see if I can find some way! > > > 3. Thanks for the great suggestion. I totally agree and will reflect > this > > > in the PR. > > > > > > With regards, > > > > > > Eundo > > > > > > 2026년 7월 21일 (화) 오전 5:23, Alexandre Dutra <[email protected]>님이 작성: > > > > > >> Hi Eundo, > > >> > > >> Thanks for the thorough analysis! I'm glad to see that we're > > >> converging to a really nice solution. > > >> > > >> To your points: > > >> > > >> > I'd therefore propose shipping a default in runtime/defaults: > > >> > > > quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA > > >> > > >> +1 on this idea, I think it makes migration a lot easier. > > >> > > >> > I think the two-step procedure is the right call for production > [...] > > >> but it does add a manual step to every quickstart, docker-compose, and > > Helm > > >> example > > >> > > >> Indeed. I'm personally OK with that and am sure we can find a smart > > >> way to update the quickstart examples holistically. > > >> > > >> > the Helm chart's persistence.relationalJdbc.schemaName value could > > stay > > >> > > >> I would rather suggest a new field: > > >> persistence.relationalJdbc.additionalProperties, with default value: { > > >> currentSchema: POLARIS_SCHEMA }. This way we also leave the door open > > >> for users that want to customize other JDBC properties. > > >> > > >> Thank you for working on this! > > >> > > >> Alex > > >> > > >> > > >> On Sun, Jul 19, 2026 at 1:24 PM Eundo Lee <[email protected]> wrote: > > >> > > > >> > Hi Alex, > > >> > > > >> > Thanks for taking this further — I agree with the direction. > > >> Driver-level > > >> > schema selection is the logical endpoint of the review so far > > >> > (statement-level -> connection-level -> driver-level), and it > removes > > >> the > > >> > hardest parts of the PR from Polaris's responsibility entirely: > > quoting, > > >> > identifier case folding, validation, and the per-database SET > > statements > > >> > all become the driver's documented behavior. It also helps with > MySQL > > >> > support later (#3960), and — procedurally nice — it eliminates the > > >> > RelationalJdbcConfiguration change altogether, so the PR no longer > > >> touches > > >> > an extension point at all. Most of the already-reviewed work > > >> (unqualified > > >> > generated SQL, schema-agnostic scripts for the current schema > version) > > >> > carries over unchanged. > > >> > > > >> > Two points I'd like to settle before reworking the PR in this > > direction: > > >> > > > >> > 1. Upgrade compatibility. Today every relational-jdbc deployment has > > its > > >> > tables in POLARIS_SCHEMA because the code and scripts force it. > If > > >> the > > >> > persistence layer becomes fully schema-agnostic, an existing > > >> deployment > > >> > that upgrades without adding currentSchema to its JDBC > > configuration > > >> > would resolve unqualified names against the default search path — > > >> > "public" on PostgreSQL — and break (or quietly bootstrap a second > > set > > >> > of tables in public, which is what #1116 set out to avoid). I'd > > >> > therefore propose shipping a default in runtime/defaults: > > >> > > > >> > > > >> > > > >> > > > quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA > > >> > > > >> > This covers PostgreSQL and CockroachDB (the shipped drivers; H2 > is > > >> > test-only), keeps upgrades and the out-of-the-box experience > > >> unchanged, > > >> > and is trivially overridable: pgjdbc documents that when a > property > > >> is > > >> > specified both in the URL and in the Properties object, the > > >> Properties > > >> > value is ignored [1] — and additional-jdbc-properties reaches the > > >> driver > > >> > through the Properties channel. I verified this empirically with > > >> pgjdbc > > >> > 42.7.13 against both PostgreSQL 17 and CockroachDB: a > currentSchema > > >> URL > > >> > parameter overrides the connection property in both, the property > > >> alone > > >> > selects the schema correctly in both, and with neither set the > > >> session > > >> > lands in "public" — which is exactly the silent failure mode the > > >> shipped > > >> > default would prevent. (The currentSchema value is also > case-folded > > >> like > > >> > any unquoted identifier on both databases, consistent with the > > casing > > >> > behavior we already agreed on.) > > >> > > > >> > [1] https://jdbc.postgresql.org/documentation/use/ > > >> > > > >> > 2. Bootstrap friction for fresh deployments. With no CREATE SCHEMA > > >> issued > > >> > by Polaris, even a default fresh installation needs a DBA (or > init > > >> > script) to run CREATE SCHEMA polaris_schema before the admin tool > > can > > >> > bootstrap. I think the two-step procedure is the right call for > > >> > production — schema creation is privileged DBA work — but it does > > >> add a > > >> > manual step to every quickstart, docker-compose, and Helm > example, > > so > > >> > I'd like the community to explicitly bless that trade-off. The > > >> > getting-started materials would gain an init step as part of the > > PR. > > >> > > > >> > One suggestion to keep the operator UX: the Helm chart's > > >> > persistence.relationalJdbc.schemaName value could stay, but instead > of > > >> > mapping to a Polaris property it would simply render the > > >> > additional-jdbc-properties.currentSchema datasource property. > > Operators > > >> > keep one discoverable knob; the persistence code stays 100% > > >> > schema-agnostic. > > >> > > > >> > On tests: agreed this is solvable — H2 supports running > initialization > > >> SQL > > >> > via the INIT= URL parameter (e.g. CREATE SCHEMA IF NOT EXISTS ... \; > > >> > SET SCHEMA ...), which covers schema creation and selection for the > > >> > H2-based tests cleanly. > > >> > > > >> > I'll rework the PR accordingly — it's mostly deletions at this > point, > > >> but > > >> > we can > > >> > make additional changes if any disagreements arise. > > >> > > > >> > Also, as Yufei mentioned in the PR comment [2], I believe the > > community > > >> has > > >> > reached a level of consensus high enough for this PR to be moved out > > of > > >> > draft > > >> > state. Moving to your new direction would actually eliminate the new > > >> > extension point (polaris.persistence.relational.jdbc.schema-name) as > > >> well. > > >> > > > >> > [2] > > https://github.com/apache/polaris/pull/4945#discussion_r3583285567 > > >> > > > >> > Thanks, > > >> > Eundo > > >> > > > >> > 2026년 7월 16일 (목) 오전 1:47, Alexandre Dutra <[email protected]>님이 작성: > > >> > > > >> > > Hi Eundo, > > >> > > > > >> > > I did another review and I think things are shaping up nicely. > > >> > > > > >> > > I think though that we need to go one step further and make the > > whole > > >> > > JDBC persistence layer completely agnostic of the schema name. The > > >> > > schema name can be provided through configuration, using standard > > >> > > Quarkus configuration properties; the Agroal datasource would then > > >> > > take care of setting the schema on each connection. There is > nothing > > >> > > to do code-wise. > > >> > > > > >> > > This imho eliminates all the issues stemming from quoting / casing > > the > > >> > > schema names, and makes the code a lot more portable. > > >> > > > > >> > > This approach, of course, makes it impossible for Polaris to > issue a > > >> > > CREATE SCHEMA statement on the user's behalf. I understand that > this > > >> > > is a breaking change. > > >> > > But I also think it is a good thing to stop creating schemas on > the > > >> > > fly: such a statement should be executed by DB admins, as they > > require > > >> > > elevated privileges. > > >> > > > > >> > > If we agree with this direction, then the bootstrap story becomes > a > > >> > > two-step procedure: a DB admin first creates the schema, then a > > >> > > Polaris admin invokes the admin tool to bootstrap the realm, and > > >> > > passes the schema to use via Quarkus config. > > >> > > > > >> > > I'm aware that this may require some changes to tests using H2, > but > > >> > > I'm fairly confident there is a way to initialize the schema in > > these > > >> > > cases. > > >> > > > > >> > > Let me know what you think! > > >> > > > > >> > > Thanks, > > >> > > Alex > > >> > > > > >> > > On Tue, Jul 14, 2026 at 4:24 AM Eundo Lee <[email protected]> > > wrote: > > >> > > > > > >> > > > Hi Yufei, > > >> > > > > > >> > > > Thanks for the quick action. I've updated the PR to leave > > historical > > >> > > > DDL scripts unchanged. > > >> > > > > > >> > > > With regards, > > >> > > > > > >> > > > Eundo > > >> > > > > > >> > > > 2026년 7월 14일 (화) 오전 1:45, Yufei Gu <[email protected]>님이 작성: > > >> > > > > > >> > > > > Hi Eundo, > > >> > > > > > > >> > > > > Thanks for the clarification. Just a small update, the > > >> --schema-version > > >> > > > > option has already been removed from the bootstrap command( > > >> > > > > https://github.com/apache/polaris/pull/5044), so I don't > think > > we > > >> > > need to > > >> > > > > update the historical DDL scripts anymore. > > >> > > > > > > >> > > > > With that out of the way, I think this PR can focus on making > > the > > >> > > current > > >> > > > > schema configurable and updating the current bootstrap path > > >> > > accordingly. > > >> > > > > > > >> > > > > Thanks again for working on this! > > >> > > > > > > >> > > > > Yufei > > >> > > > > > > >> > > > > > > >> > > > > On Sat, Jul 11, 2026 at 2:01 AM Eundo Lee <[email protected]> > > >> wrote: > > >> > > > > > > >> > > > > > Hi Yufei, > > >> > > > > > > > >> > > > > > I was not aware of the discussion regarding keeping the > latest > > >> schema > > >> > > > > > version only. > > >> > > > > > Thanks for the heads up. > > >> > > > > > > > >> > > > > > It seems that you've opened a separate discussion thread on > > the > > >> > > removal > > >> > > > > of > > >> > > > > > --schema-version > > >> > > > > > option from the bootstrap command. So I'm guessing that the > > >> removal > > >> > > > > should > > >> > > > > > be out of scope > > >> > > > > > from this PR. > > >> > > > > > > > >> > > > > > In that case, in order for the polaris deployment to work > > as-is > > >> with > > >> > > a > > >> > > > > > configurable schema, > > >> > > > > > I think we should keep the changes to the historical DDL > > >> scripts, and > > >> > > > > > remove the scripts once > > >> > > > > > the --schema-version option is removed from the bootstrap > > >> command. > > >> > > > > > > > >> > > > > > Please feel free to correct me if I'm wrong. > > >> > > > > > > > >> > > > > > Thanks, > > >> > > > > > > > >> > > > > > Eundo > > >> > > > > > > > >> > > > > > > > >> > > > > > 2026년 7월 11일 (토) 오전 9:00, Yufei Gu <[email protected]>님이 > > 작성: > > >> > > > > > > > >> > > > > > > Hi Eundo, > > >> > > > > > > > > >> > > > > > > Thanks for working on this. Making the schema name > > >> configurable is > > >> > > a > > >> > > > > good > > >> > > > > > > idea. I also agree with Alex that we should avoid setting > > the > > >> > > schema > > >> > > > > > every > > >> > > > > > > time we obtain a connection from the pool. > > >> > > > > > > > > >> > > > > > > I do have one minor concern. I don't think we need to > touch > > >> the > > >> > > > > > historical > > >> > > > > > > JDBC schemas. We've previously discussed on the dev > mailing > > >> list > > >> > > that > > >> > > > > > each > > >> > > > > > > Polaris release should only keep the latest schema > version. > > >> One > > >> > > small > > >> > > > > > > behavior change would naturally follow from this. We could > > >> remove > > >> > > the > > >> > > > > > > --schema-version option from the bootstrap command[1]. > That > > >> option > > >> > > > > allows > > >> > > > > > > users to bootstrap a realm with a historical schema > version. > > >> While > > >> > > it > > >> > > > > may > > >> > > > > > > be useful in some rare cases, I don't think it provides > > enough > > >> > > value to > > >> > > > > > > justify the added complexity. > > >> > > > > > > > > >> > > > > > > 1. > > >> > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > >> > > > https://polaris.apache.org/releases/1.6.0/admin-tool/#bootstrapping-realms-and-principal-credentials > > >> > > > > > > > > >> > > > > > > Thanks, > > >> > > > > > > > > >> > > > > > > Yufei > > >> > > > > > > > > >> > > > > > > > > >> > > > > > > On Thu, Jul 2, 2026 at 2:08 AM Eundo Lee < > [email protected] > > > > > >> > > wrote: > > >> > > > > > > > > >> > > > > > > > Thank you for taking your time to review. > > >> > > > > > > > > > >> > > > > > > > I've applied your suggestion on using an explicit > default > > >> value > > >> > > for > > >> > > > > the > > >> > > > > > > > helm chart. > > >> > > > > > > > For other points I agree very much with your direction. > > >> > > > > > > > However, I just wanted to confirm with you the design / > > >> > > > > implementation > > >> > > > > > > > details > > >> > > > > > > > before diving in to create more commits. > > >> > > > > > > > > > >> > > > > > > > I would greatly appreciate additional inputs. > > >> > > > > > > > > > >> > > > > > > > Thanks, > > >> > > > > > > > Eundo Lee > > >> > > > > > > > > > >> > > > > > > > > > >> > > > > > > > 2026년 7월 1일 (수) 오후 11:57, Alexandre Dutra < > > >> [email protected]>님이 > > >> > > 작성: > > >> > > > > > > > > > >> > > > > > > > > Hi Eundo, > > >> > > > > > > > > > > >> > > > > > > > > Thank you for raising this topic and providing an > > initial > > >> draft > > >> > > > > PR! I > > >> > > > > > > > > left a few comments. > > >> > > > > > > > > > > >> > > > > > > > > I generally agree with the idea of making the schema > > name > > >> > > > > > > > > configurable. But I'm not sure I agree with some > design > > >> choices > > >> > > > > made > > >> > > > > > > > > in the PR: for example, I think it would be easier to > > let > > >> the > > >> > > > > Agroal > > >> > > > > > > > > pool set the schema on each JDBC connection, rather > than > > >> > > having it > > >> > > > > > set > > >> > > > > > > > > on each SQL statement generated by the QueryGenerator. > > >> > > > > > > > > > > >> > > > > > > > > Let's keep discussing implementation details in the PR > > >> though. > > >> > > > > > > > > > > >> > > > > > > > > Thanks, > > >> > > > > > > > > Alex > > >> > > > > > > > > > > >> > > > > > > > > On Wed, Jul 1, 2026 at 11:30 AM 이은도 < > [email protected]> > > >> wrote: > > >> > > > > > > > > > > > >> > > > > > > > > > Hi all, > > >> > > > > > > > > > > > >> > > > > > > > > > I'd like to get feedback on a small enhancement to > the > > >> > > Relational > > >> > > > > > > JDBC > > >> > > > > > > > > > persistence backend before moving the PR out of > draft. > > >> > > > > > > > > > > > >> > > > > > > > > > Problem > > >> > > > > > > > > > > > >> > > > > > > > > > The backend currently hard-codes its database schema > > as > > >> > > > > > > POLARIS_SCHEMA > > >> > > > > > > > > > -- both in QueryGenerator (there's an existing "// > > >> TODO: make > > >> > > > > > schema > > >> > > > > > > > name > > >> > > > > > > > > > configurable.") and in the bootstrap SQL scripts. > This > > >> makes > > >> > > it > > >> > > > > > > > > impossible > > >> > > > > > > > > > to comply with a schema-naming policy that > > organizations > > >> > > might > > >> > > > > > have. > > >> > > > > > > > > > It came up while looking at issue #1116 (the older > > >> > > EclipseLink > > >> > > > > > "avoid > > >> > > > > > > > > > public schema" > > >> > > > > > > > > > request); the JDBC backend fixed the "not public" > part > > >> by > > >> > > > > > > hard-coding a > > >> > > > > > > > > > name, > > >> > > > > > > > > > but the value still isn't configurable. > > >> > > > > > > > > > > > >> > > > > > > > > > Issue: > https://github.com/apache/polaris/issues/4944 > > >> > > > > > > > > > Draft PR: > https://github.com/apache/polaris/pull/4945 > > >> > > > > > > > > > > > >> > > > > > > > > > Proposed change > > >> > > > > > > > > > > > >> > > > > > > > > > Add polaris.persistence.relational.jdbc.schema-name, > > >> > > defaulting > > >> > > > > to > > >> > > > > > > > > > POLARIS_SCHEMA so existing deployments are > unaffected. > > >> The > > >> > > value > > >> > > > > is > > >> > > > > > > > > > validated as a plain SQL identifier (it's > interpolated > > >> into > > >> > > SQL, > > >> > > > > > not > > >> > > > > > > > > > bound). Bootstrap scripts use a ${schema} > placeholder > > >> > > substituted > > >> > > > > > at > > >> > > > > > > > > > script-execution time so the configured schema is > > >> created and > > >> > > > > used > > >> > > > > > > > > > consistently. > > >> > > > > > > > > > > > >> > > > > > > > > > Points I'd like input on > > >> > > > > > > > > > > > >> > > > > > > > > > 1. This adds a method to > RelationalJdbcConfiguration, > > >> which > > >> > > is an > > >> > > > > > > > > > extension point -- hence this discussion per > > >> > > CONTRIBUTING.md. > > >> > > > > > > > > > > > >> > > > > > > > > > 2. To wire the schema through, I converted > > >> QueryGenerator > > >> > > from a > > >> > > > > > > static > > >> > > > > > > > > > utility to an instance bound to the schema. > That's > > >> the > > >> > > bulk of > > >> > > > > > the > > >> > > > > > > > > diff > > >> > > > > > > > > > (mechanical call-site updates). An alternative is > > >> > > threading > > >> > > > > the > > >> > > > > > > > schema > > >> > > > > > > > > > through method parameters; the instance approach > > >> seemed > > >> > > > > cleaner, > > >> > > > > > > but > > >> > > > > > > > > I'm > > >> > > > > > > > > > happy to change direction. > > >> > > > > > > > > > > > >> > > > > > > > > > 3. For the admin tool, I exposed the schema as the > > same > > >> > > config > > >> > > > > > > property > > >> > > > > > > > > > rather than a separate CLI flag, so the admin > tool > > >> and > > >> > > server > > >> > > > > > > can't > > >> > > > > > > > > > bootstrap into different schemas. Let me know if > a > > >> CLI > > >> > > flag is > > >> > > > > > > > > preferred > > >> > > > > > > > > > despite that drift risk. > > >> > > > > > > > > > > > >> > > > > > > > > > Feedback welcome -- I'll hold the PR in draft until > > >> there's > > >> > > > > > > consensus. > > >> > > > > > > > > > > > >> > > > > > > > > > Thanks, > > >> > > > > > > > > > Eundo Lee > > >> > > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > >> > > > > > >
