You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "hemasrishalini (via GitHub)" <gi...@apache.org> on 2026/05/16 19:12:06 UTC
[PR] docs: improve MongoDB NoSQL setup documentation [polaris]
hemasrishalini opened a new pull request, #4464:
URL: https://github.com/apache/polaris/pull/4464
## Summary
This PR improves the MongoDB NoSQL setup documentation by adding:
* local MongoDB Docker setup instructions
* a verification step using `docker ps`
* admin tool build instructions before bootstrap operations
The changes are based on practical local testing of the MongoDB NoSQL setup workflow.
Closes #3398
## Testing
Manually tested by:
* starting MongoDB locally using Docker
* verifying the MongoDB container with `docker ps`
* building the Polaris admin tool using:
```bash
./gradlew :polaris-admin:build -x test
```
## Checklist
* [x] 🧪 Added/updated tests with good coverage, or manually tested (and explained how)
* [x] 📚 Updated documentation in `site/content/in-dev/unreleased` (if needed)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] closed pull request #4464: docs: improve MongoDB NoSQL setup documentation
URL: https://github.com/apache/polaris/pull/4464
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #4464:
URL: https://github.com/apache/polaris/pull/4464#discussion_r3278108892
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -82,27 +98,33 @@ quarkus.mongodb.write-concern.safe=true
quarkus.mongodb.read-preference=primaryPreferred
```
-For TLS/SSL connections, add `tls=true` to the connection string:
-
-```properties
-quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>/?tls=true
-```
-
-For more details on available MongoDB configuration options, please refer to the [Quarkus MongoDB configuration reference](https://quarkus.io/guides/mongodb#configuration-reference).
+For the full list of available options, refer to the
+[Quarkus MongoDB configuration reference](https://quarkus.io/guides/mongodb#configuration-reference).
## Bootstrapping Polaris
-Before using Polaris with the MongoDB backend, you must bootstrap the metastore to create the necessary collections and initial realm. This is done using the [Admin Tool]({{% ref "../admin-tool" %}}).
+Before starting Polaris for the first time, you must bootstrap the metastore. This creates
+the necessary MongoDB collections (`objs` and `refs`) and an initial realm with root
+credentials. Bootstrapping is a one-time operation performed using the
+[Admin Tool]({{% ref "../admin-tool" %}}).
+
+{{< alert note >}}
+The bootstrap command connects directly to MongoDB and does not require the Polaris server
Review Comment:
This is already implied by the paragraph above 🤷
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -26,51 +26,67 @@ weight: 200
The MongoDB backend is currently in **beta**.
{{< /alert >}}
-This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup.
+Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension.
+Configuration is provided through environment variables or JVM `-D` flags at startup.
-## Basic Configuration
+For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas).
+A single-node standalone MongoDB instance is not supported for production use, as Polaris
+requires replica set semantics for its transaction model.
Review Comment:
I would not say that Polaris _requires_ "replica set semantics" 🤷
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -26,51 +26,67 @@ weight: 200
The MongoDB backend is currently in **beta**.
{{< /alert >}}
-This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup.
+Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension.
+Configuration is provided through environment variables or JVM `-D` flags at startup.
-## Basic Configuration
+For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas).
+A single-node standalone MongoDB instance is not supported for production use, as Polaris
+requires replica set semantics for its transaction model.
-Using environment variables:
+## Prerequisites
-```properties
-POLARIS_PERSISTENCE_TYPE=nosql
-POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb
-QUARKUS_MONGODB_DATABASE=polaris
-QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port>
-```
+- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster
Review Comment:
What is the rationale for the 3 node recommendation?
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -26,51 +26,67 @@ weight: 200
The MongoDB backend is currently in **beta**.
{{< /alert >}}
-This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup.
+Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension.
+Configuration is provided through environment variables or JVM `-D` flags at startup.
-## Basic Configuration
+For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas).
+A single-node standalone MongoDB instance is not supported for production use, as Polaris
+requires replica set semantics for its transaction model.
-Using environment variables:
+## Prerequisites
-```properties
-POLARIS_PERSISTENCE_TYPE=nosql
-POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb
-QUARKUS_MONGODB_DATABASE=polaris
-QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port>
-```
+- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster
+- Network connectivity from the Polaris server to all MongoDB replica set members
+- The `apache/polaris-admin-tool` Docker image or the standalone JAR, for bootstrapping
+
+## Production Configuration
-Using properties file:
+### Replica Set
+
+For a self-managed MongoDB replica set, configure Polaris with all replica set member
+hostnames in the connection string:
```properties
polaris.persistence.type=nosql
polaris.persistence.nosql.backend=MongoDb
-quarkus.mongodb.database=polaris
-quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>
+quarkus.mongodb.database=<database-name>
+quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin
```
-## MongoDB Atlas Configuration
+You must also tell Polaris which realms to serve at startup. The realm name must exactly
+match the name used during bootstrapping (case-sensitive):
Review Comment:
This is placed in-between different Mongo config options... which is kind of odd.
Also the tone of this phrase could probably be improved.
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -26,51 +26,67 @@ weight: 200
The MongoDB backend is currently in **beta**.
{{< /alert >}}
-This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup.
+Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension.
+Configuration is provided through environment variables or JVM `-D` flags at startup.
-## Basic Configuration
+For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas).
+A single-node standalone MongoDB instance is not supported for production use, as Polaris
+requires replica set semantics for its transaction model.
-Using environment variables:
+## Prerequisites
-```properties
-POLARIS_PERSISTENCE_TYPE=nosql
-POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb
-QUARKUS_MONGODB_DATABASE=polaris
-QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port>
-```
+- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster
+- Network connectivity from the Polaris server to all MongoDB replica set members
+- The `apache/polaris-admin-tool` Docker image or the standalone JAR, for bootstrapping
+
+## Production Configuration
-Using properties file:
+### Replica Set
+
+For a self-managed MongoDB replica set, configure Polaris with all replica set member
+hostnames in the connection string:
```properties
polaris.persistence.type=nosql
polaris.persistence.nosql.backend=MongoDb
-quarkus.mongodb.database=polaris
-quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>
+quarkus.mongodb.database=<database-name>
+quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin
```
-## MongoDB Atlas Configuration
+You must also tell Polaris which realms to serve at startup. The realm name must exactly
+match the name used during bootstrapping (case-sensitive):
+
+```properties
+polaris.realm-context.realms=<realm-name>
+```
+
+{{< alert warning >}}
+The realm name is case-sensitive. If you bootstrap a realm as `polaris`, you must configure
Review Comment:
This is not specific to Mongo. It is probably best to mention this on the Admin Tool page rather than here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #4464:
URL: https://github.com/apache/polaris/pull/4464#discussion_r3258538087
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -105,6 +127,8 @@ docker run --rm -it \
apache/polaris-admin-tool:latest bootstrap -r <realm-name> -c <realm-name>,<client-id>,<client-secret>
```
+
Review Comment:
Spurious change?
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -94,6 +109,13 @@ For more details on available MongoDB configuration options, please refer to the
Before using Polaris with the MongoDB backend, you must bootstrap the metastore to create the necessary collections and initial realm. This is done using the [Admin Tool]({{% ref "../admin-tool" %}}).
+Build the Polaris admin tool before running the bootstrap command:
Review Comment:
This is generally not necessary, unless you've modified the admin tool.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on PR #4464:
URL: https://github.com/apache/polaris/pull/4464#issuecomment-4491203592
Thanks for your contribution, @hemasrishalini ! However, I'm not sure this PR alone is sufficient to "close" #3398 (as mentioned in the description).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "hemasrishalini (via GitHub)" <gi...@apache.org>.
hemasrishalini commented on PR #4464:
URL: https://github.com/apache/polaris/pull/4464#issuecomment-4492033305
Hi @adutra @dimas-b, thanks for the feedback! I've updated the PR to remove the local MongoDB setup instructions, removed the admin tool build step, and cleaned up the formatting changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #4464:
URL: https://github.com/apache/polaris/pull/4464#issuecomment-4775009165
This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on PR #4464:
URL: https://github.com/apache/polaris/pull/4464#issuecomment-4492445391
@hemasrishalini : but the PR is empty now?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "hemasrishalini (via GitHub)" <gi...@apache.org>.
hemasrishalini commented on PR #4464:
URL: https://github.com/apache/polaris/pull/4464#issuecomment-4496186032
Hi @dimas-b @snazy @adutra,
I've updated the PR based on hands-on testing with a 3-node MongoDB replica set using Docker.
Key things I discovered during testing that were missing from the doc:
* `polaris.realm-context.realms=<realm-name>` is required when starting the server, otherwise you get `Unknown realm` errors at runtime
* The realm name is case-sensitive and must match exactly what was used during bootstrap
* The "Starting Polaris" section was completely missing
* `--network=host` is needed for admin tool Docker commands to reach MongoDB
I also added a verification step showing that bootstrap creates `objs` and `refs` collections in MongoDB.
Backup/restore is not covered yet, happy to do that as a follow-up PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on code in PR #4464:
URL: https://github.com/apache/polaris/pull/4464#discussion_r3259988645
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -94,6 +109,13 @@ For more details on available MongoDB configuration options, please refer to the
Before using Polaris with the MongoDB backend, you must bootstrap the metastore to create the necessary collections and initial realm. This is done using the [Admin Tool]({{% ref "../admin-tool" %}}).
+Build the Polaris admin tool before running the bootstrap command:
Review Comment:
I'd like to add that we should direct our users to the released artifacts and not build from source.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #4464:
URL: https://github.com/apache/polaris/pull/4464#discussion_r3268959996
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -47,6 +47,21 @@ polaris.persistence.nosql.backend=MongoDb
quarkus.mongodb.database=polaris
quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>
```
+## Local MongoDB Setup
Review Comment:
+1
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #4464:
URL: https://github.com/apache/polaris/pull/4464#discussion_r3258548476
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -47,6 +47,21 @@ polaris.persistence.nosql.backend=MongoDb
quarkus.mongodb.database=polaris
quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>
```
+## Local MongoDB Setup
Review Comment:
I think we are mixing developer setup instructions with production setup instructions here. I think that this page should focus on production setup only.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve MongoDB NoSQL setup documentation [polaris]
Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #4464:
URL: https://github.com/apache/polaris/pull/4464#discussion_r3282999825
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -82,27 +98,33 @@ quarkus.mongodb.write-concern.safe=true
quarkus.mongodb.read-preference=primaryPreferred
```
-For TLS/SSL connections, add `tls=true` to the connection string:
-
-```properties
-quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>/?tls=true
-```
-
-For more details on available MongoDB configuration options, please refer to the [Quarkus MongoDB configuration reference](https://quarkus.io/guides/mongodb#configuration-reference).
+For the full list of available options, refer to the
+[Quarkus MongoDB configuration reference](https://quarkus.io/guides/mongodb#configuration-reference).
## Bootstrapping Polaris
-Before using Polaris with the MongoDB backend, you must bootstrap the metastore to create the necessary collections and initial realm. This is done using the [Admin Tool]({{% ref "../admin-tool" %}}).
+Before starting Polaris for the first time, you must bootstrap the metastore. This creates
+the necessary MongoDB collections (`objs` and `refs`) and an initial realm with root
+credentials. Bootstrapping is a one-time operation performed using the
+[Admin Tool]({{% ref "../admin-tool" %}}).
+
+{{< alert note >}}
+The bootstrap command connects directly to MongoDB and does not require the Polaris server
+to be running.
+{{< /alert >}}
Using Docker:
```bash
docker run --rm -it \
+ --network=host \
Review Comment:
`--network=host` is Linux-only. On macOS/Windows Docker Desktop, point users at `host.docker.internal` or a user-defined network. Same applies to the start, maintenance-run, maintenance-info, and maintenance-log examples.
##########
site/content/in-dev/unreleased/metastores/nosql-mongodb.md:
##########
@@ -26,51 +26,67 @@ weight: 200
The MongoDB backend is currently in **beta**.
{{< /alert >}}
-This implementation uses MongoDB as the persistence backend and leverages the Quarkus MongoDB extension for connection management. Configuration can be done through environment variables or JVM -D flags at startup.
+Polaris supports MongoDB as a persistence backend via the Quarkus MongoDB extension.
+Configuration is provided through environment variables or JVM `-D` flags at startup.
-## Basic Configuration
+For production deployments, MongoDB must be running as a **replica set** (or via MongoDB Atlas).
+A single-node standalone MongoDB instance is not supported for production use, as Polaris
+requires replica set semantics for its transaction model.
-Using environment variables:
+## Prerequisites
-```properties
-POLARIS_PERSISTENCE_TYPE=nosql
-POLARIS_PERSISTENCE_NOSQL_BACKEND=MongoDb
-QUARKUS_MONGODB_DATABASE=polaris
-QUARKUS_MONGODB_CONNECTION_STRING=mongodb://<username>:<password>@<host>:<port>
-```
+- A running MongoDB replica set (minimum 3 nodes recommended) or a MongoDB Atlas cluster
+- Network connectivity from the Polaris server to all MongoDB replica set members
+- The `apache/polaris-admin-tool` Docker image or the standalone JAR, for bootstrapping
+
+## Production Configuration
-Using properties file:
+### Replica Set
+
+For a self-managed MongoDB replica set, configure Polaris with all replica set member
+hostnames in the connection string:
```properties
polaris.persistence.type=nosql
polaris.persistence.nosql.backend=MongoDb
-quarkus.mongodb.database=polaris
-quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host>:<port>
+quarkus.mongodb.database=<database-name>
+quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin
```
-## MongoDB Atlas Configuration
+You must also tell Polaris which realms to serve at startup. The realm name must exactly
+match the name used during bootstrapping (case-sensitive):
+
+```properties
+polaris.realm-context.realms=<realm-name>
+```
+
+{{< alert warning >}}
+The realm name is case-sensitive. If you bootstrap a realm as `polaris`, you must configure
+`polaris.realm-context.realms=polaris` (lowercase) when starting the server. A mismatch will
+cause `Unknown realm` errors at runtime.
+{{< /alert >}}
+
+### MongoDB Atlas
For MongoDB Atlas deployments, use the `mongodb+srv://` connection string format:
```properties
polaris.persistence.type=nosql
polaris.persistence.nosql.backend=MongoDb
-quarkus.mongodb.database=polaris
+quarkus.mongodb.database=<database-name>
quarkus.mongodb.connection-string=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority
+polaris.realm-context.realms=<realm-name>
```
-## MongoDB Replica Set Configuration
+### TLS/SSL
-For replica set deployments:
+For encrypted connections, add `tls=true` to the connection string:
```properties
-polaris.persistence.type=nosql
-polaris.persistence.nosql.backend=MongoDb
-quarkus.mongodb.database=polaris
-quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&authSource=admin
+quarkus.mongodb.connection-string=mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<rs-name>&tls=true
```
Review Comment:
Worth a one-liner pointing at Quarkus TLS options (CA bundles, hostname verification) so users don't blindly add `tlsAllowInvalidCertificates=true`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org