offset=-1 does not return existing data (snapshot) as documented

[schickling]

Description

ElectricSQL's HTTP API is not returning existing data when requesting with offset=-1, contrary to what the documentation states.

Expected Behavior

According to the Electric documentation:

"When a shape is first requested, Electric queries Postgres for the data and populates the log by turning the query results into insert operations."

When making a GET request to /v1/shape?table=my_table&offset=-1, Electric should:

1. Query the PostgreSQL table for all existing rows
2. Convert those rows into insert operations in the shape log
3. Return them in the response

Actual Behavior

Electric returns an empty array [] despite the table containing data.

Reproduction

I've created a minimal reproduction here: https://github.com/schickling-repros/2025-08-electric-offset-bug

Steps:

1. Create a table in PostgreSQL with some data
2. Make a GET request to Electric: /v1/shape?table=test_table&offset=-1
3. Observe that Electric returns [] instead of the existing data

Evidence

From testing with LiveStore integration:

• PostgreSQL table contains data (verified by direct query)
• Electric receives changes via logical replication (seen in logs: "Received transaction 735 (1 changes)")
• But Electric returns empty array when requesting with offset=-1

Impact

This makes Electric unsuitable for initial client synchronization - it can only sync changes that occur after a client starts listening, not existing data.

Environment

• ElectricSQL: latest Docker image
• PostgreSQL: 16-alpine
• Tested with Node.js client

Related Code

The issue was discovered while implementing a sync provider: https://github.com/livestore/livestore

Is this expected behavior or a bug? If expected, the documentation should be updated to clarify that offset=-1 does not return existing data.

[KyleAMathews]

If the shape is created before there's data in the table, offset=-1 will always return an empty array as the initial chunk electric returns is the initial query. Did you try subsequent offsets?

[schickling]

After further investigation, I've discovered that this is actually the expected behavior of Electric, not a bug.

Key Finding

Electric's offset=-1 behavior works as designed:

• First request: Electric queries PostgreSQL and returns all existing data as a snapshot
• Subsequent requests: Electric returns the same initial snapshot, not any new data added after

This makes sense for Electric's use case as a real-time sync engine - it establishes a shape/snapshot at a point in time, then streams changes from that point forward.

The Issue in Our Tests

Our test was failing because:

1. We were creating an empty table before Electric first saw it
2. Electric cached this empty snapshot
3. When we inserted data and requested with offset=-1 again, Electric returned the cached empty snapshot

Solution

We fixed this by ensuring Electric only sees tables that already contain data, preventing it from caching empty snapshots.

Conclusion

This is working as intended - Electric is designed for real-time change streaming, not for re-reading historical data with offset=-1. Once a shape is established, you need to use the handle/offset from that shape to continue syncing.

Thanks for the quick response! The behavior makes sense now that I understand Electric's architecture better. Closing this issue.