Admin Tool

Polaris includes a tool for administrators to manage the metastore.

The tool must be built with the necessary JDBC drivers to access the metastore database. For example, to build the tool with support for Postgres, run the following:

./gradlew \
  :polaris-admin:assemble \
  :polaris-admin:quarkusAppPartsBuild --rerun \
  -Dquarkus.container-image.build=true

The above command will generate:

• One Fast-JAR in runtime/admin/build/quarkus-app/quarkus-run.jar
• Two Docker images named apache/polaris-admin-tool:latest and apache/polaris-admin-tool:<version>

Usage

Please make sure the admin tool and Polaris server are with the same version before using it. To run the standalone JAR, use the following command:

java -jar runtime/admin/build/quarkus-app/quarkus-run.jar --help

To run the Docker image, use the following command:

docker run apache/polaris-admin-tool:latest --help

The basic usage of the Polaris Admin Tool is outlined below:

Usage: polaris-admin-tool.jar [-hV] [COMMAND]
Polaris administration & maintenance tool
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help       Display help information about the specified command.
  bootstrap  Bootstraps realms and root principal credentials.
  purge      Purge realms and all associated entities.

Configuration

The Polaris Admin Tool must be executed with the same configuration as the Polaris server. The configuration can be done via environment variables or system properties.

At a minimum, it is necessary to configure the Polaris Admin Tool to connect to the same database used by the Polaris server.

See the metastore documentation for more information on configuring the database connection.

Note: Polaris will always create schema ‘polaris_schema’ during bootstrap under the configured database.

Bootstrapping Realms and Principal Credentials

The bootstrap command is used to bootstrap realms and create the necessary principal credentials for the Polaris server. This command is idempotent and can be run multiple times without causing any issues. If a realm is already bootstrapped, running the bootstrap command again will not have any effect on that realm.

java -jar runtime/admin/build/quarkus-app/quarkus-run.jar bootstrap --help

The basic usage of the bootstrap command is outlined below:

Usage: polaris-admin-tool.jar bootstrap [-hV] [-v=<schema version>]
                                        ([-r=<realm> [-r=<realm>]... [-c=<realm,
                                        clientId,clientSecret>]... [-p]] |
                                        [[-f=<file>]])
Bootstraps realms and root principal credentials.
  -h, --help                Show this help message and exit.
  -v, --schema-version=<schema version>
                            The version of the schema to load in [1, 2, 3,
                              LATEST].
  -V, --version             Print version information and exit.
Standard Input Options:
  -c, --credential=<realm,clientId,clientSecret>
                            Root principal credentials to bootstrap. Must be of
                              the form 'realm,clientId,clientSecret'.
  -p, --print-credentials   Print root credentials to stdout
  -r, --realm=<realm>       The name of a realm to bootstrap.
File Input Options:
  -f, --credentials-file=<file>
                            A file containing root principal credentials to
                              bootstrap.

For example, to bootstrap the realm1 realm and create its root principal credential with the client ID admin and client secret admin, you can run the following command:

java -jar runtime/admin/build/quarkus-app/quarkus-run.jar bootstrap -r realm1 -c realm1,admin,admin

Purging Realms and Principal Credentials

The purge command is used to remove realms and principal credentials from the Polaris server.

java -jar runtime/admin/build/quarkus-app/quarkus-run.jar purge --help

The basic usage of the purge command is outlined below:

Usage: polaris-admin-tool.jar purge [-hV] -r=<realm> [-r=<realm>]...
Purge realms and all associated entities.
  -h, --help            Show this help message and exit.
  -r, --realm=<realm>   The name of a realm to purge.
  -V, --version         Print version information and exit.

For example, to purge the realm1 realm, you can run the following command:

java -jar runtime/admin/build/quarkus-app/quarkus-run.jar purge -r realm1