Apache Polaris 1.8.0: What’s New, Breaking Changes, and Upgrade Guide

Apache Polaris 1.8.0 was released on September 28, 2026. The release adds dedicated authorization for semantic models, expands the Python CLI, makes relational JDBC schema placement configurable, introduces controls for list pagination, and tightens several behaviors that matter during concurrent commits and production failures. It also includes upgrade work that operators should complete manually for existing PostgreSQL and CockroachDB deployments.

The short version is that Polaris 1.8.0 is less about adding a long list of surface features and more about making an open catalog easier to operate safely. A few changes alter HTTP responses, authorization inputs, bootstrap responsibilities, token exchange, and setup export formats. Those changes are useful, but they deserve an upgrade plan rather than a routine image-tag change.

This guide explains the complete release in practical terms: what changed, why it matters, which teams need to take action, and how I would validate an upgrade. For background on the project itself, start with What Is Apache Polaris? or the deeper guide to Apache Polaris architecture.

Apache Polaris 1.8.0 at a glance

Semantic models now have first-class authorization

The most visible new feature is a dedicated privilege model for semantic models. Polaris can now distinguish listing, creating, reading, updating, and dropping a semantic model. It also separates the ability to manage grants on those models. Privileges can be assigned to catalog roles at the individual model, namespace, or catalog scope.

This is more important than simply adding another securable object. A semantic model often contains business definitions, measures, relationships, or data-product context that should not inherit a broad table permission by accident. A user may need to query governed data through an approved model without receiving permission to edit the model. A modeling team may need permission to update definitions without receiving authority to change who can access them. Polaris 1.8.0 gives administrators the vocabulary to express those differences.

• Catalog-level grants are useful for platform administrators or central modeling teams that manage models across the catalog.
• Namespace-level grants fit domain ownership, where a team controls models for a specific subject area.
• Model-level grants support exceptions and narrowly scoped publishing or review workflows.
• Grant-management privileges let an organization separate editing a model from delegating access to it.

If you already use external policy evaluation, do not assume the new privileges flow through an existing policy unchanged. Add explicit allow and deny tests for each semantic-model operation. The release also changes how the authorization SPI represents targets and multiple intents, which can affect custom integrations even when semantic models are not in use.

Custom authorizers and OPA policies need regression tests

Polaris 1.8.0 changes PolarisAuthorizer inputs in two ways. First, resource targets and parent paths no longer include the internal synthetic ROOT container. A catalog target now has an empty parent path, and a root-scoped action such as listing catalogs no longer carries a fabricated root target. Second, a request with multiple authorization intents is evaluated one intent at a time.

For OPA deployments, the second change means separate OPA queries per intent. A Rego policy that expected a combined list of intents can produce a different result or fail to match. The same warning applies to any custom implementation of the authorizer SPI. This is a breaking input-shape change, not merely an internal refactor.

I would build an authorization test matrix before upgrading. Include root-scoped operations, catalog operations, namespace operations, table operations, policy operations, and the new semantic-model operations. Test requests with one intent and requests that previously generated multiple intents. Capture both allow and deny outcomes. For an OPA deployment, compare decision logs from the old and new version so you can see whether a change came from the policy or the request shape.

Commit conflicts become safer and cheaper

Several of the best changes in 1.8.0 are about telling clients what really happened during a commit. That sounds small until two writers update the same table or a catalog loses contact with its persistence layer at the wrong moment.

Stale commits now return a retryable 409

When a concurrent table commit reaches Polaris with a stale sequence number, the response is now HTTP 409 instead of HTTP 400. The behavior applies to single-table commits and commitTransaction. A 400 tells a client that the request itself is invalid. A 409 tells it that the request conflicted with current state and may succeed after the client refreshes that state and retries according to Iceberg commit rules.

Polaris also checks whether base metadata is stale before writing the proposed metadata file. Under contention, that can avoid one object-store write followed by a delete for every rejected attempt. It also returns the conflict sooner. High-frequency streaming writers and busy ingestion pipelines should see the most benefit because they create more opportunities for overlapping commits.

Unknown commit state is no longer reported as a bad request

A CommitStateUnknownException now maps to HTTP 500, as required by the Iceberg REST specification, instead of 400. The distinction matters because an unknown state means the commit may have been applied even though the client did not receive a definitive answer. Treating that result as an ordinary client error can encourage an unsafe retry. A correct client should first reconcile the table state, identify whether its commit is present, and only then decide what to do.

The practical test is not just checking the HTTP code. Confirm that every engine and connector in your estate interprets 409 and 500 correctly. Verify retry limits, backoff, state refresh, and metrics. If a client collapses every non-2xx response into a generic failure, the server improvement will not automatically make the workload safer.

Relational JDBC deployments gain schema control and manual upgrade work

Polaris no longer assumes that its relational tables belong in a fixed schema. The JDBC driver currentSchema property selects the database schema, with a default supplied through quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema. The Helm chart exposes the equivalent through persistence.relationalJdbc.additionalProperties.currentSchema.

This makes it easier to place Polaris inside a database managed by an established platform team, especially when each service receives its own schema. It also shifts an important responsibility. The Polaris bootstrap process no longer creates the database schema. On a fresh PostgreSQL installation, a database administrator must create it before the admin tool runs bootstrap.

CREATE SCHEMA polaris_schema;

# Then configure the service to use the same schema.
# Example property name from the 1.8.0 release notes:
quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA

Existing deployments already have a schema, so they do not need to create it again. They do need to inspect any currentSchema value already embedded in the JDBC URL. Before 1.8.0, queries were qualified with POLARIS_SCHEMA, so the URL setting could be ignored. In 1.8.0, it determines where Polaris reads and writes. A wrong value can point the upgraded service at another schema. Running bootstrap at that point can create an empty second set of tables and make the installation look as if its catalog disappeared.

Two index fixes require manual action on existing databases

Schema version 6 corrects the idx_locations index for PostgreSQL and CockroachDB. The optimized location-overlap check filters by catalog, but the old index led with parent_id. With OPTIMIZED_SIBLING_CHECK enabled, creates could fall back to a realm-wide scan instead of using the intended lookup. New databases get the corrected index automatically. Existing databases do not because Polaris does not run automated schema migrations.

DROP INDEX polaris_schema.idx_locations;
CREATE INDEX idx_locations
  ON polaris_schema.entities USING btree
  (realm_id, catalog_id, location_without_scheme)
  WHERE location_without_scheme IS NOT NULL;

CockroachDB operators have a second task. Schema version 6 declares three indexes that PostgreSQL and H2 have carried since schema version 4. Existing CockroachDB databases, including databases already marked as schema version 6, need the indexes created manually.

CREATE INDEX IF NOT EXISTS idx_grants_realm_grantee
  ON polaris_schema.grant_records (realm_id, grantee_id);
CREATE INDEX IF NOT EXISTS idx_grants_realm_securable
  ON polaris_schema.grant_records (realm_id, securable_id);
CREATE INDEX IF NOT EXISTS idx_entities_catalog_id_id
  ON polaris_schema.entities (catalog_id, id);

Schedule these as database changes, not application startup commands. Confirm the actual schema name, capture query plans before and after, and understand the locking behavior for your database and table size. H2 is unaffected by the idx_locations correction, and PostgreSQL does not need the three CockroachDB additions.

Pagination becomes configurable on both sides of the API

The Python CLI adds a global --page-size option. It follows continuation tokens internally when listing Iceberg resources, which gives operators a practical way to work with large catalogs without asking for one huge response. For local catalogs, the server-side LIST_PAGINATION_ENABLED feature flag must be enabled. Federated catalogs are paginated by Polaris itself.

The server can also bound the page size requested by a client with LIST_PAGINATION_MAX_PAGE_SIZE. A catalog-specific override is available through polaris.config.list-pagination-max-page-size. The default is -1, which means unlimited, so operators must opt in to a cap. If a client asks for a larger page, Polaris reduces the page size instead of rejecting the request.

There is an interoperability detail worth calling out. The Iceberg REST specification says a request without pageToken should receive the complete result with a null continuation token. A server-side maximum can truncate that response and return a token anyway. A client that never follows continuation tokens will see only the first page. Before setting a maximum, inventory clients and test them with more resources than the cap.

Polaris 1.8.0 also turns malformed pagination tokens into 400 Bad Request with an Invalid page token message instead of allowing decoding exceptions to surface as 500 errors. That includes truncated, incompatible, or otherwise invalid serialized tokens. This gives support teams a much clearer distinction between a bad continuation value and a server outage.

The CLI is becoming a more credible automation surface

The 1.8.0 CLI work falls into three groups: catalog configuration, broader object coverage, and reliable configuration round trips.

• catalogs update accepts --no-sts and --no-kms, so operators can change STS and KMS availability on an existing S3 catalog. In older releases, those decisions were available only during creation.
• External catalog creation accepts gcp as an authentication type for Iceberg REST federation. This supports GCP-authenticated catalogs such as BigLake without placing Google credential secrets directly in command-line arguments.
• catalogs create and catalogs update accept --storage-name, which refers to a storage configuration held by the server. That improves separation between catalog definitions and reusable storage settings.
• The CLI adds operations for views and generic tables, expanding the resources that can be managed consistently from scripts.
• The global page-size option makes large list operations manageable when the server and client agree on pagination.

The setup export and apply fixes are more substantial than they first appear. Export now represents namespace paths as arrays of levels, preserving names that contain dots. Policies are emitted as a list with both name and namespace, so two namespaces can use the same policy name. Nested namespaces and their policies are included. Policy content no longer gets double encoded during apply.

Exports also preserve user-defined properties on principals, principal roles, and catalog roles, along with S3 internal endpoints, STS endpoints, the Azure hierarchical flag, and server-side storage names. Finally, export exits with an error and avoids partial YAML if a required API read fails. Before this fix, automation could receive incomplete configuration with a successful exit status, which is a particularly dangerous failure mode for backup and disaster-recovery workflows.

There is a compatibility cost: older CLI versions cannot apply every new export representation. Treat setup files as versioned artifacts. Record the CLI version that produced an export, store it with the file, and use that version or a newer one for restoration. A round-trip test should export a realm, apply it to an isolated environment, and compare catalogs, nested namespaces, policies, properties, and storage settings.

Authentication and token exchange are stricter

Internal JWTs are now bound to the generation of a principal's credentials through a polaris-cv claim. No secret material is placed in the token. The generation is enforced when an internal token is used as the subject of token exchange. Tokens created before this binding, which do not have the claim, cannot be exchanged after an upgraded node receives them. They remain usable as bearer tokens until they expire.

A rolling upgrade creates a temporary mixed-version condition. An old node may still mint a token without polaris-cv, and a new node will reject an exchange using that token with invalid_grant. Clients can therefore see intermittent exchange failures until every old node is removed. Plan around the maximum token lifetime, monitor invalid_grant, and avoid a long period with old and new issuers serving the same traffic.

The internal token broker also behaves better in mixed authentication mode. A token that the broker does not recognize now returns null from verification instead of failing the entire authentication attempt, which allows another configured mechanism to evaluate it. If your deployment combines internal tokens with an external OIDC provider, regression-test both paths and the fallback between them.

Views, generic tables, policies, and locations receive correctness fixes

Several fixes remove surprising behavior around newer Polaris resource types. DROP_WITH_PURGE_ENABLED now applies only to Iceberg tables. Previously it could also block the internal metadata purge performed when deleting a view, which meant a default configuration could reject view deletion. View cleanup is now controlled by PURGE_VIEW_METADATA_ON_DROP on its own.

If a generic table, semantic model, or policy disappears after Polaris resolves it but before the deletion is persisted, the API now returns 404 rather than 500 or 204. The Policy API also rejects an unknown policyType filter with 400. In the past, a misspelled type could be treated as no filter and return every policy, which made it hard for a client to tell a valid filtered result from an unfiltered one. For more context on policy storage and execution, see Apache Polaris policies for compaction and retention.

Namespace location handling receives two useful fixes. Creating a namespace without an explicit location now works when the catalog's default base location sits inside an allowed location. Updating namespace properties no longer rejects a location that is unchanged. The optimized overlap check also considers stored ancestor paths with and without a trailing slash, preventing nested locations from slipping past the validation under certain stored forms.

The ADD_TRAILING_SLASH_TO_LOCATION flag is deprecated. Polaris now always appends a trailing slash to namespace and table base locations. The setting is accepted but ignored, and configuring it as false produces a startup warning. Remove the override from configuration after verifying that any custom location tooling already handles normalized paths.

Storage access and cleanup become more predictable

GCS credential vending no longer fails when a table or write path points to the root of a bucket such as gs://bucket. An empty object path previously triggered an exception while Polaris built access-boundary rules. The GCS behavior now aligns with the AWS integration for this case.

When a client requests remote signing through X-Iceberg-Access-Delegation, Polaris still cannot perform that mode. The error now explains what happened and tells the client to remove the access-delegation header and configure storage credentials locally when the catalog can neither vend credentials nor sign requests. That message should shorten troubleshooting for engines that negotiate several delegation modes.

Asynchronous file cleanup now has a configurable polaris.tasks.file-deletion-timeout, with a one-hour default. A stalled storage service can no longer hold a task-executor thread forever. A timeout ends the current run instead of immediately stacking more deletions against the same unhealthy endpoint. Polaris also restores batched deletes for storage implementations that support bulk operations. Wrapper classes now propagate that capability to the cleanup code, affecting S3, GCS, ADLS, and Hadoop FileIO paths.

Operators should alert on cleanup timeouts, retry exhaustion, and queue age. A timeout prevents a blocked thread, but it does not remove the underlying files. Connect these signals to the audit and event pipeline described in Apache Polaris events and audit logging.

Error handling is more consistent across the API

Polaris 1.8.0 improves the boundary between client mistakes and server failures. Missing source or destination fields in a table or view rename request return 400 rather than 500. Server-side JSON processing failures use the standard Iceberg error envelope, so Iceberg clients can parse the error instead of failing on an unexpected body shape.

Authentication failures caused by the metastore now return 503 consistently across principal and role lookups. The response includes Retry-After: 0, which is significant because the Iceberg REST specification uses that header to indicate whether a client may retry a non-idempotent request. Client-facing messages no longer name the internal lookup that failed, while server logs retain the detail. The request ID, returned by default in X-Request-ID, connects the two sides.

These changes make status codes more useful as observability dimensions. Build dashboards that separate 400 validation errors, 404 races, 409 conflicts, 503 dependency failures, and 500 unknown outcomes. A single error-rate graph hides the operational difference between a malformed request, ordinary optimistic concurrency, and a persistence outage.

A practical Apache Polaris 1.8.0 upgrade runbook

If I were upgrading a production installation, I would use the following sequence. The exact deployment mechanics depend on whether you use Kubernetes, the official Helm chart, or another runtime. The validation gates are the important part.

1. Inventory the deployment. Record the Polaris version, persistence backend, database schema, JDBC URL, active feature flags, token issuers, external authorizers, and all client versions.
2. Back up the database and configuration. Verify that the backup can be restored. Export setup state with the current CLI and label the file with the CLI version.
3. Inspect currentSchema. If the JDBC URL sets it, verify it points to the existing Polaris tables. Make the Helm or datasource setting explicit so the result is not dependent on driver precedence.
4. Plan the index changes. Recreate idx_locations for existing PostgreSQL or CockroachDB installations. Add the three missing indexes for existing CockroachDB installations. Test the operations and query plans on a database copy.
5. Replay authorization tests. Update Rego or custom authorizer logic for the missing synthetic root and per-intent evaluation. Add semantic-model privileges if those resources are used.
6. Test clients against a canary. Exercise pagination, stale commit conflicts, unknown commit recovery, views, namespace location updates, credential vending, and malformed requests.
7. Plan the token transition. Keep the mixed-version period short. Account for pre-1.8 tokens without polaris-cv, and monitor exchange failures during the rollout.
8. Upgrade a non-production environment. Run representative concurrency and catalog-size tests. Export setup state with the new CLI, restore it in a clean environment, and compare objects and properties.
9. Roll out gradually. Start with a small traffic slice or one realm if your routing model allows it. Watch response codes, commit latency, database load, OPA decisions, token exchange, and cleanup tasks.
10. Complete post-upgrade housekeeping. Remove deprecated trailing-slash configuration, document the required CLI version for new exports, and update runbooks for schema creation on fresh installs.

For a broader deployment checklist, use the production guide for Kubernetes, Helm, and PostgreSQL. The 1.8.0 release notes should still be the authority for version-specific commands and caveats.

Who should upgrade first?

Teams with high commit concurrency have a strong reason to evaluate 1.8.0 because the release improves conflict responses and avoids unnecessary metadata writes. Large catalogs gain better pagination controls. PostgreSQL and CockroachDB deployments can benefit from corrected indexes, provided operators perform the manual work. Teams adopting semantic models need the new privilege vocabulary. Automation-heavy environments should value the setup export and apply fixes.

The groups that should move most carefully are those with custom authorizers, OPA policies that inspect combined intents, long rolling upgrades, or configuration pipelines that expect older setup YAML. Those are manageable risks, but they require explicit tests. If none of the new capabilities is urgent, it is reasonable to let the release run through your normal qualification cycle rather than treating the version number as a deadline.

What 1.8.0 says about the direction of Polaris

Polaris is expanding beyond basic Iceberg table registration while tightening the control-plane contracts needed in production. Semantic-model privileges extend governance to a higher-level asset. Better support for views, generic tables, policies, and external catalogs broadens the objects administrators can manage. At the same time, the release spends considerable effort on status codes, indexes, token semantics, configuration round trips, and cleanup behavior.

That combination is healthy for an open catalog. New object types are useful only if operators can authorize them, export their configuration, diagnose failures, and recover safely. The work in 1.8.0 makes those surrounding contracts clearer. It also shows why a catalog upgrade should be reviewed like a control-plane change, not like a stateless application refresh.

Apache Polaris 1.8.0 FAQ

When was Apache Polaris 1.8.0 released?

Apache Polaris 1.8.0 was released on September 28, 2026. The Apache download page provides source and binary distributions plus Spark client artifacts, while the GitHub release lists Docker images, the Helm chart, Maven artifacts, and the merged changes.

Does Polaris 1.8.0 contain breaking changes?

Yes. The release changes stale-commit responses, relational JDBC bootstrap and schema selection, custom authorizer inputs, per-intent authorization evaluation, and token exchange for older internal JWTs. Existing databases also need manual index review. Read the official upgrade and breaking-change notes before deployment.

Does Polaris automatically apply the database index changes?

No. Fresh schema version 6 installations receive the corrected indexes, but existing PostgreSQL and CockroachDB deployments must apply the relevant changes manually. Polaris does not provide automated schema migrations for these existing installations.

What changed for semantic models?

Semantic models now have dedicated privileges for list, create, read, update, and drop operations, plus controls for managing grants. Permissions can be attached through catalog roles at model, namespace, or catalog scope.

Where can I download Apache Polaris 1.8.0?

Use the official Apache Polaris 1.8.0 download page. It includes signatures and SHA-512 checksums. Docker images are published as apache/polaris:1.8.0 and apache/polaris-admin:1.8.0.

Final takeaway

Apache Polaris 1.8.0 gives semantic models a real authorization model and improves the catalog's behavior under concurrency, large listings, persistence failures, configuration export, and asynchronous cleanup. Its value is easiest to see in operational details: a conflict is now reported as a conflict, an unknown commit remains visibly unknown, a setup export fails instead of quietly becoming incomplete, and database placement is controlled by the operator.

The upgrade deserves preparation. Verify the JDBC schema, apply the database index fixes, retest custom authorization, plan the internal-token transition, and qualify every client that depends on pagination or commit retries. Once those gates pass, 1.8.0 is a meaningful step toward a more predictable production catalog.

To go deeper, download Apache Polaris: The Definitive Guide and explore Dremio's technical articles on the Polaris REST API, generic tables, identity, policy, and production operations.

Technical review date: September 29, 2026. Version scope: Apache Polaris 1.8.0.

Primary sources

• Apache Polaris 1.8.0 downloads, release notes, upgrade notes, and breaking changes
• Apache Polaris 1.8.0 GitHub release and merged changes
• Apache Polaris 1.8.0 documentation