Skip to content

Cross reference attachments packages and use better docs link #337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 6, 2025
Merged

Cross reference attachments packages and use better docs link #337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/powersync_attachments_helper/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
>
> The `powersync_core/attachments` library is in alpha and brings improved APIs and functionality that is more in line with our other SDKs, such as the ability to write your own local storage implementation.
>
> Check out the [docs here](/packages/powersync_core/doc/attachments.md) to get started.
> Check out the [docs here](https://pub.dev/documentation/powersync_core/latest/topics/attachments-topic.html) to get started.
>
> While the `powersync_attachments_helper` package will still get bug fixes if you need them,
> new features will only be developed on `powersync_core/attachments`.
Expand Down
16 changes: 13 additions & 3 deletions packages/powersync_core/doc/attachments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,26 @@ PowerSync.
Embedding this data directly in your source databases is [inefficient and not recommended](https://docs.powersync.com/usage/use-case-examples/attachments).

Instead, the PowerSync SDK for Dart and Flutter provides utilities you can use to _reference_ this binary data
in your local database, and then download it from a secondary data store such as Supabase Storage or S3.
in your regular database schema, and then download it from a secondary data store such as Supabase Storage or S3.
Because binary data is not directly stored in the source database in this model, we call these files _attachments_.


> [!NOTE]
> These attachment utilities are recommended over our legacy [PowerSync Attachments Helper](https://pub.dev/packages/powersync_attachments_helper) package. The new utilities provide cleaner APIs that are more aligned with similar helpers in our other SDKs, and include improved features such as:
> - Support for writing your own local storage implementation
> - Support for dynamic nested directories and custom per-attachment file extensions out of the box
> - Ability to add optional `metaData` to attachments
> - No longer depends on `dart:io`
>
> If you are new to handling attachments, we recommend starting with these utilities. If you currently use the legacy `powersync_attachments_helper` package, a fairly simple migration would be to adopt the new utilities with a different table name and drop the legacy package. This means existing attachments are lost, but they should be downloaded again.

## Alpha release

The attachment helpers described in this document are currently in an alpha state, intended for testing.
The attachment utilities described in this document are currently in an alpha state, intended for testing.
Expect breaking changes and instability as development continues.
The attachments API is marked as `@experimental` for this reason.

Do not rely on these libraries for production use.
Do not rely on these utilities for production use.

## Usage

Expand Down