This document describes the compatibility guarantees for ODAS and the implication for upgrading. These apply to all versions of the product and exceptions will be noted in the release notes. The exceptions will be used for absolutely critical issues and rarely used.

Client-Server compatibility

ODAS guarantees that APIs on the services are backwards compatible. This means that older clients can work with newer servers with no issue. For example, a Spark client library version 1.1.x can work with a server running 1.2.x.

ODAS does not guarantee forward compatibility meaning that newer clients may not be compatible against older servers. For example, the 1.2.x client library may leverage functionality that is not in 1.1.x servers.

This applies to all the server APIs.

Impact on upgrades

Users should upgrade the server before the clients. As older clients can work against newer servers, this should not impact existing users. Once all the servers are on the new version, clients can be upgraded over time to leverage the new capabilities.

Catalog compatibility

ODAS guarantees backward and forward compatibility on the catalog (the table metadata and access policies).

This means that catalog metadata created by an older version is fully compatible with new versions and metadata created by newer versions should not impact existing metadata for older versions. This does not mean all new metadata will be usable by older versions but it does mean older versions will not see regressions. For example, 1.2.0 added support for JDBC backed tables. 1.1.x servers do not understand these new tables but the prior tables will continue to be operational.

Impact on upgrades

This guarantee allows having two different versions sharing the same metadata. We recommend having two clusters, the older and newer simultaneously backed by the same RDBMS during the upgrade phase. When the upgrade is complete, the older version can be phased out.