Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions intro/examples.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@
- [Yjs CRDT Text Collaboration Demo](https://github.com/powersync-ja/powersync-js/tree/main/demos/yjs-react-supabase-text-collab#readme)
- [Vite + React + TS + PowerSync + Supabase](https://github.com/powersync-community/vite-react-ts-powersync-supabase#readme)
- [E2EE Chat App](https://github.com/powersync-community/react-supabase-chat-e2ee#readme) - End-to-end encrypted group chat demo
- [Time-Based Sync Demo](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-supabase-time-based-sync) - Dynamically control which data is synced to the client based on a date

#### Framework Integration Examples

Expand Down Expand Up @@ -214,7 +215,7 @@
<Accordion title="Flutter Projects" icon="flutter">
- [Flutter Instagram Clone with Supabase + Firebase by @Gambley1](https://github.com/Gambley1/flutter-instagram-offline-first-clone)
- [Jepsen PowerSync Testing - Formal consistency validation framework by @nurturenature](https://github.com/nurturenature/jepsen-powersync)
- [Bavard -An Eloquent-inspired ORM for Dart/Flutter by @ILDaviz](https://ildaviz.github.io/bavard/)

Check warning on line 218 in intro/examples.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

intro/examples.mdx#L218

Did you really mean 'Bavard'?
</Accordion>
<Accordion title="JavaScript & TypeScript Projects" icon="js">
- [SolidJS Hooks for PowerSync Queries by @aboviq](https://github.com/aboviq/powersync-solid)
Expand Down
2 changes: 2 additions & 0 deletions sync/advanced/sync-data-by-time.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
```sql
ALTER TABLE issues ADD COLUMN updated_this_week BOOLEAN DEFAULT false;
```
Update it periodically using a cron job (e.g., with pg_cron):

Check warning on line 48 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L48

Did you really mean 'pg_cron'?

```sql
UPDATE issues SET updated_this_week = (updated_at > now() - interval '7 days');
Expand All @@ -57,9 +57,9 @@
config:
edition: 3
streams:
recent_issues:

Check warning on line 60 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L60

Did you really mean 'recent_issues'?
auto_subscribe: true

Check warning on line 61 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L61

Did you really mean 'auto_subscribe'?
query: SELECT * FROM issues WHERE updated_this_week = true

Check warning on line 62 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L62

Did you really mean 'updated_this_week'?
```

For multiple time ranges, define a stream per range and let the client subscribe to the one it needs:
Expand All @@ -86,10 +86,10 @@
</Tab>
<Tab title="Sync Rules (Legacy)">
```yaml
bucket_definitions:

Check warning on line 89 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L89

Did you really mean 'bucket_definitions'?
recent_issues:

Check warning on line 90 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L90

Did you really mean 'recent_issues'?
data:
- SELECT * FROM issues WHERE updated_this_week = true

Check warning on line 92 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L92

Did you really mean 'updated_this_week'?
```

For multiple time ranges, add multiple bucket definitions and let the client choose which bucket to sync:
Expand Down Expand Up @@ -122,7 +122,7 @@
This approach works well when you have a small, fixed set of time ranges. However, it requires schema changes and a scheduled job to keep the columns updated.

<Warning>
This approach requires schema changes and scheduled jobs (e.g., pg_cron). Limited to pre-defined time ranges.

Check warning on line 125 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L125

Did you really mean 'pg_cron'?
</Warning>

If you need more flexibility like letting users pick arbitrary date ranges, see Workaround 2 below.
Expand All @@ -133,13 +133,15 @@

Use `substring` to extract the date portion from a timestamp and match it with `=`:

For a complete working example, see the [PowerSync + Supabase: Time-Based Sync demo](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-supabase-time-based-sync).

<Tabs>
<Tab title="Sync Streams">
```yaml
config:
edition: 3
streams:
issues_by_date:

Check warning on line 144 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L144

Did you really mean 'issues_by_date'?
query: SELECT * FROM issues WHERE substring(updated_at, 1, 10) = subscription.parameter('date')
```

Expand All @@ -155,8 +157,8 @@
</Tab>
<Tab title="Sync Rules (Legacy)">
```yaml
bucket_definitions:

Check warning on line 160 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L160

Did you really mean 'bucket_definitions'?
issues_by_update_at:

Check warning on line 161 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L161

Did you really mean 'issues_by_update_at'?
parameters: SELECT value as date FROM json_each(request.parameters() ->> 'dates')
data:
- SELECT * FROM issues WHERE substring(updated_at, 1, 10) = bucket.date
Expand Down Expand Up @@ -184,9 +186,9 @@

You have to pick a granularity and stick with it. If that's a problem—say, you want hourly precision for recent data but don't want hundreds of buckets when syncing a full month, see Workaround 3 below.

## 3: Multiple Granularities

Check warning on line 189 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L189

Did you really mean 'Granularities'?

Combine multiple granularities in a single definition. This lets you use larger buckets (days) for older data and smaller buckets (hours, minutes) for recent data.

Check warning on line 191 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L191

Did you really mean 'granularities'?

<Tabs>
<Tab title="Sync Streams">
Expand All @@ -194,7 +196,7 @@
config:
edition: 3
streams:
issues_by_partition:

Check warning on line 199 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L199

Did you really mean 'issues_by_partition'?
queries:
# By day (e.g., "2026-01-07")
- SELECT * FROM issues WHERE substring(updated_at, 1, 10) = subscription.parameter('partition')
Expand All @@ -220,8 +222,8 @@
</Tab>
<Tab title="Sync Rules (Legacy)">
```yaml
bucket_definitions:

Check warning on line 225 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L225

Did you really mean 'bucket_definitions'?
issues_by_time:

Check warning on line 226 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L226

Did you really mean 'issues_by_time'?
parameters: SELECT value as partition FROM json_each(request.parameters() ->> 'partitions')
data:
# By day (e.g., "2026-01-07")
Expand Down Expand Up @@ -257,11 +259,11 @@
The trade-off is complexity. The client must decide which granularity to use for each time segment, and each row belongs to multiple buckets, which increases replication overhead.

<Note>
When using multiple time granularities (e.g., monthly, daily, hourly), rows move between buckets as time passes. Since each granularity creates a different bucket ID, the client must re-download the row from the new bucket even if it already has the data. This re-download overhead can nullify the benefits of granular filtering. For this reason, in some cases it may be better to sync entire months avoiding the re-sync overhead, even if you sync more data initially.

Check warning on line 262 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L262

Did you really mean 'granularities'?
</Note>

<Warning>
Each row belongs to multiple buckets (replication overhead). Re-sync overhead when rows move between bucket granularities. Added complexity may not justify the gains over Workaround 2.

Check warning on line 266 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L266

Did you really mean 'granularities'?
</Warning>

# Conclusion
Expand All @@ -271,6 +273,6 @@

- **Pre-defined time ranges** — Simplest option. Use when you have a fixed set of time ranges and don't mind schema changes.
- **Buckets Per Date** — More flexible. Use when you need arbitrary date ranges but can live with a single granularity.
- **Multiple Granularities** — Most flexible. Use when you need precision for recent data without syncing hundreds of buckets. Be mindful of the re-sync overhead.

Check warning on line 276 in sync/advanced/sync-data-by-time.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

sync/advanced/sync-data-by-time.mdx#L276

Did you really mean 'Granularities'?

We're working on a more elegant solution. This guide will be updated when it's ready.