docs/versioned_docs/version-3.0.0-LTS/setup/upgrade-to-v3.md
ToolJet 3.0 is a new major version, including breaking changes that require you to adjust your applications accordingly. We will guide you through this process and mention a few important changes.
:::tip Before upgrading Before upgrading, we recommend reviewing your existing applications for any usage of deprecated features. Addressing these ahead of time will help reduce the work needed to upgrade to ToolJet 3.0.
For complex applications, we also recommend setting up thorough testing procedures to ensure your apps function correctly after the upgrade. :::
Before attempting to upgrade to the ToolJet 3.0:
To upgrade, checkout the latest docker image here.
The following changes are breaking and require immediate action to ensure your applications continue to function correctly after the upgrade.
You can no longer dynamically change references to component names.
The following patterns are no longer supported:
Using variables to construct component names:
// This will no longer work
{{components[variables.componentNameVariable].value}}
Dynamically referencing components:
// This is not supported
{{components['textinput' + components.tabs1.currentTab].value}}
Dynamically accessing nested properties:
// This dynamic property access is not allowed
{{components.table1[components.textinput1.value]}}
Instead, use static references to components:
{{components.textinput1.value}}
{{components.table1.selectedRow}}
{{queries.query1.data}}
:::note This is only an issue during the upgrade process. Once your application is running on ToolJet 3.0, you can use identical names for components and queries without any problems. :::
When upgrading, if a component is referencing a query with the same name, the upgrade process may break that mapping. This occurs because ToolJet previously used a global ID-to-name map for both components and queries, which is now split in 3.0.
Example scenario: If a table component named userData is referencing a query also named userData, this reference may break during the upgrade process.
There are changes to how you can access and check for the existence of variables in the property panel:
component/query/page keywordvariables keyword// Supported formats
components.textinput1.value
components?.textinput1?.value
components["textinput1"].value
queries.restapi1.data
page.variables.name
variables["name"]
variables.name
// No longer supported
{{'name' in variables}}
{{Object.keys(variables).includes('name')}}
{{variables.hasOwnProperty('name')}}
// Recommended approach for checking existence
{{variables['name'] ?? false}}
:::caution These changes may affect how your application interacts with variables and components. Be sure to test thoroughly after making these updates. :::
When the same component name exists on multiple pages and is linked to queries, the query will only work correctly on the page where the component was originally associated with it.
Example scenario:
page1 and page2, each containing a component named textinput1page1 that is linked to textinput1page1page2, the query will not work as expected, even though there's a component with the same name:::tip When building multi-page applications, it's recommended to use unique component names across all pages to avoid any potential issues with query bindings. :::
Future resolution: We will be adding functionality to enforce unique component names across all pages in upcoming releases.
The old deprecated Kanban Board component will cease functioning entirely. Applications using this component will crash after the upgrade if not updated.
<div style={{textAlign: 'center'}}> </div>:::caution After the 3.0 upgrade, applications with the old Kanban Board component will crash and become unusable. Make sure to replace all instances of the old component with the new Kanban component before upgrading. :::
If you haven't migrated your local data sources to global data sources, you will encounter an error message indicating that local data sources are no longer supported. For detailed instructions on migrating from Local Data Sources to the new Data Sources, please refer to our Local Data Sources Migration Guide.
Workspace Constants are designed to be resolved on the server-side only, ensuring a high level of security. You can assign users to a specific role and provide create, update, and delete access to Workspace Constants.
For detailed instructions on migrating from Workspace Variables to Workspace Constants, please refer to our Workspace Variables Migration Guide.
We've introduced a capability to expose additional information through metadata for all datasources. Previously, this was only available for REST API and GraphQL data sources.
Before, you could access response headers like this:
{{queries.<queryName>.responseHeaders}}
Now, you should use:
{{queries.<queryName>.metadata}}
The metadata object will contain detailed information about the request and response, including request URL, method, headers, parameters, response status code, and headers. You can read more about metadata here.
ToolJet Database is now a core requirement for the ToolJet 3.0. To use ToolJet Database, you'd have to set up and deploy PostgREST server which helps querying ToolJet Database.
Please check the environment variables that you need to configure to set up: