126 lines
7.0 KiB
Markdown
126 lines
7.0 KiB
Markdown
## v0.23.0-rc
|
||
|
||
> [!CAUTION]
|
||
> **This is a prerelease intended for test and experimental purposes only!**
|
||
>
|
||
> It introduces many Go/JSVM breaking changes and requires manual migration steps.
|
||
>
|
||
> All new features will be reflected in the new website documentation with the final v0.23.0 release.
|
||
|
||
> [!NOTE]
|
||
> Please note that you don't have to upgrade to PocketBase v0.23.0 if you are not planning further developing
|
||
> your existing app and/or are satisfied with the v0.22.x features set. There are no identified critical issues
|
||
> with PocketBase v0.22.x yet and in the case of critical bugs and security vulnerabilities, the fixes
|
||
> will be backported for at least until Q1 of 2025 (_if not longer_).
|
||
>
|
||
> If you don't plan upgrading just make sure to pin the SDKs version to their latest PocketBase v0.22.x compatible:
|
||
> - JS SDK: `<0.22.0`
|
||
> - Dart SDK: `<0.19.0`
|
||
|
||
PocketBase v0.23.0-rc is a major refactor of the internals with the overall goal of making PocketBase an easier to use Go framework.
|
||
|
||
There are many changes but to highlight some of the most notable ones:
|
||
|
||
- Replaced `echo` with a new router built on top of the Go 1.22 `net/http` mux enhancements.
|
||
- Merged `daos` packages in `core.App` to simplify the DB operations (_the `models` package structs are also migrated in `core`_).
|
||
- Option to specify custom `DBConnect` function as part of the app configuration to allow different `database/sql` SQLite drivers (_turso/libsql, sqlcipher, etc._) and custom builds.
|
||
- New hooks allowing better control over the execution chain and error handling (_including wrapping an entire hook chain in a single DB transaction_).
|
||
- Various `Record` model improvements (_support for get/set modifiers, simplfied file upload by treating the file(s) as regular field value like `record.Set("document", file)`, etc._).
|
||
- Dedicated fields structs with safer defaults to make it easier creating/updating collections programmatically.
|
||
- Option to mark field as Private/Hidden, disallowing regular users to read or modify it (_there is also a dedicated Record hook to hide/unhide Record fields progrommatically from a single place_).
|
||
- Option to customize the default system collection fields (`id`, `email`, `password`, etc.).
|
||
- Admins are now system `_superusers` auth records.
|
||
- Builtin rate limiter (_supports tags, wildcards and exact routes matching_).
|
||
- Batch/transactional Web API endpoint.
|
||
- Impersonate Web API endpoint (_it could be also used for generating fixed/non-refreshable superuser tokens, aka. "API keys"_).
|
||
- Support for custom user request activity log attributes.
|
||
- One-Time Password (OTP) auth method (_via email code_).
|
||
- Multi-Factor Authentication (MFA) support (_currently requires any 2 different auth methods to be used_).
|
||
- Support for Record "proxy/projection" in preparation for the planned autogeneration of typed Go record models.
|
||
- Various minor UI improvements (_recursive `Presentable` view, slightly different collection options organization, zoom/pan for the logs chart, etc._)
|
||
- and many more...
|
||
|
||
In terms of performance, the Go standard router mux is known to be slightly slower compared to Gin, Echo, etc. implementations, but based on my local tests the difference is negliable.
|
||
The [benchmarks repo](https://github.com/pocketbase/benchmarks) will be updated with the final v0.23.0 release (_currently there seems to be ~10% memory consumption increase which I'll have to investigate to see whether it is from the router change or from the new hooks_).
|
||
|
||
#### Go/JSVM APIs changes
|
||
|
||
For upgrading to PocketBase v0.23.0, please refer to:
|
||
|
||
- Go: https://pocketbase.io/v023upgrade/go/.
|
||
- JSVM: https://pocketbase.io/v023upgrade/jsvm/.
|
||
|
||
#### SDKs changes
|
||
|
||
- [JS SDK v0.22.0-rc](https://github.com/pocketbase/js-sdk/blob/develop/CHANGELOG.md)
|
||
- [Dart SDK v0.19.0-rc](https://github.com/pocketbase/dart-sdk/blob/develop/CHANGELOG.md)
|
||
|
||
#### Web APIs changes
|
||
|
||
- New `POST /api/batch` endpoint.
|
||
|
||
- New `GET /api/collections/meta/scaffolds` endpoint.
|
||
|
||
- New `DELETE /api/collections/{collection}/truncate` endpoint.
|
||
|
||
- New `POST /api/collections/{collection}/request-otp` endpoint.
|
||
|
||
- New `POST /api/collections/{collection}/auth-with-otp` endpoint.
|
||
|
||
- New `POST /api/collections/{collection}/impersonate/{id}` endpoint.
|
||
|
||
- ⚠️ Previously when uploading new files to a multiple `file` field, new files were automatically appended to the existing field values.
|
||
This behaviour has changed with v0.23+ and for consistency with the other multi-valued fields when uploading new files they will replace the old ones. If you want to prepend or append new files to an existing multiple `file` field value you can use the `+` prefix or suffix:
|
||
```js
|
||
"documents": [file1, file2] // => [file1_name, file2_name]
|
||
"+documents": [file1, file2] // => [file1_name, file2_name, old1_name, old2_name]
|
||
"documents+": [file1, file2] // => [old1_name, old2_name, file1_name, file2_name]
|
||
```
|
||
|
||
- ⚠️ Removed `GET /records/{id}/external-auths` and `DELETE /records/{id}/external-auths/{provider}` endpoints because this is now handled by sending list and delete requests to the `_externalAuths` collection.
|
||
|
||
- ⚠️ Changes to the app settings model fields and response (+new options such as `trustedProxy`, `rateLimits`, `batch`, etc.). The app settings Web APIs are mostly used by the Dashboard UI and rarely by the end users, but if you want to check all settings changes please refer to the [Settings Go struct](https://github.com/pocketbase/pocketbase/blob/develop/core/settings_model.go#L121).
|
||
|
||
- ⚠️ New flatten Collection model and fields structure. The Collection model Web APIs are mostly used by the Dashboard UI and rarely by the end users, but if you want to check all changes please refer to the [Collection Go struct](https://github.com/pocketbase/pocketbase/blob/develop/core/collection_model.go#L308).
|
||
|
||
- ⚠️ The top level error response `code` key was renamed to `status` for consistency with the Go APIs.
|
||
The error field key remains `code`:
|
||
```js
|
||
{
|
||
"status": 400, // <-- old: "code"
|
||
"message": "Failed to create record.",
|
||
"data": {
|
||
"title": {
|
||
"code": "validation_required",
|
||
"message": "Missing required value."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- ⚠️ New fields in the `GET /api/collections/{collection}/auth-methods` response.
|
||
_The old `authProviders`, `usernamePassword`, `emailPassword` fields are still returned in the response but are considered deprecated and will be removed in the future._
|
||
```js
|
||
{
|
||
"mfa": {
|
||
"duration": 100,
|
||
"enabled": true
|
||
},
|
||
"otp": {
|
||
"duration": 0,
|
||
"enabled": false
|
||
},
|
||
"password": {
|
||
"enabled": true,
|
||
"identityFields": ["email", "username"]
|
||
},
|
||
"oauth2": {
|
||
"enabled": true,
|
||
"providers": [{"name": "gitlab", ...}, {"name": "google", ...}]
|
||
},
|
||
// old fields...
|
||
}
|
||
```
|
||
|
||
- ⚠️ Soft-deprecated the OAuth2 auth success `meta.avatarUrl` field in favour of `meta.avatarURL`.
|