Release Notes

:::tip For all versions, please see GitHub Releases. :::

Version number {#version-number}

JuiceFS Community Edition uses semantic versioning to label its releases. Each version number consists of three numbers in the format x.y.z, representing the major version number (x), the minor version number (y), and the patch number (z).

1. Major version number (x): When the major version number is greater than or equal to 1, it indicates that the version is suitable for production environments. When the major version number changes, it indicates that this version may have added major features, architectural changes, or data format changes that are not backward compatible. For example, v0.8.3 → v1.0.0 means production-ready, v1.0.0 → v2.0.0 represents an architectural or functional change.
2. Minor version number (y): The minor version number indicates that the version adds some new features, performance optimizations, bug fixes, etc. that can be backward compatible. For example, v1.0.0 → v1.1.0.
3. Patch version number (z): The patch version number indicates a minor update or bug fix for the software, which is only some minor changes or fixes to existing features and will not affect the compatibility of the softwares. For example, v1.0.3 → v1.0.4.

Upgrade {#changes}

JuiceFS client has only one binary file, so usually you only need to replace the old binary with the new one when upgrading JuiceFS.

JuiceFS v1.1

:::tip If you are using JuiceFS version prior to v1.0, please upgrade to v1.0 first. :::

In v1.1 (specifically, v1.1.0-beta2) JuiceFS added Directory Statistics and Directory Quota. These two features were not available in older versions of the client, and writing with the old client when they were turned on would result in large deviations in the statistics. When upgrading to v1.1, if you do not intend to enable these two new features, you can simply replace the client without additional action. If you do, it is recommended that you read the following content before upgrading.

Default configuration

The default configurations for these two features are:

• For newly created filesystems they are automatically enabled.

• For existing filesystems, they are disabled.

  • Directory statistics can be enabled independently by juicefs config command.
  • When setting directory quotas the directory statistics will be enabled automatically.

Recommended Upgrade Steps

1. Upgrade all client binaries to v1.1 version.
2. Deny re-connections from versions prior to v1.1: juicefs config META-URL --min-client-version 1.1.0-A.
3. Restart the service at a proper time (remount, restart gateway, etc.)
4. Make sure that all online clients are version v1.1 or higher: juicefs status META-URL | grep -w Version
5. Enable the new features, see Directory Statistics and Directory Quota.

JuiceFS v1.0

JuiceFS has two compatibility changes in version v1.0 (specifically, v1.0.0-beta3). If you are using an older version of the client, it is recommended that you read the following content before upgrading.

SQL: Update table schema to support encoding other than UTF-8

JuiceFS v1.0 has changed the table schema to support encoding other than UTF-8. For existing file systems, you need to upgrade the table schema manually to support that. It's recommended to upgrade all clients first and then the table schema.

:::note Table schema upgrades are optional, and they are required only if you need to use non-UTF-8 characters. In addition, database performance may degrade when upgrading SQL table schemas, affecting running services. :::

MySQL/MariaDB

alter table jfs_edge
    modify name varbinary(255) not null;
alter table jfs_symlink
    modify target varbinary(4096) not null;

PostgreSQL

alter table jfs_edge
    alter column name type bytea using name::bytea;
alter table jfs_symlink
    alter column target type bytea using target::bytea;

SQLite

SQLite does not support modifying columns, but you can migrate columns by dump and load commands, refer to JuiceFS Metadata Backup and Recovery for details.

New session management format

JuiceFS v1.0 uses a new session management format. The previous versions of clients cannot see the sessions generated by v1.0 clients via juicefs status or juicefs destroy, whereas the new versions are able to see all the sessions.