diff --git a/.changeset/cold-bobcats-travel.md b/.changeset/cold-bobcats-travel.md
new file mode 100644
index 000000000..e6f6b9860
--- /dev/null
+++ b/.changeset/cold-bobcats-travel.md
@@ -0,0 +1,5 @@
+---
+'@electric-sql/pglite-sync': patch
+---
+
+shapeKey in syncShapeToTable is now mandatory but nullable; passing null will not persist the shape
diff --git a/docs/docs/sync.md b/docs/docs/sync.md
index d52a47bfc..83cfb92d4 100644
--- a/docs/docs/sync.md
+++ b/docs/docs/sync.md
@@ -88,8 +88,8 @@ It takes the following options as an object:
- `primaryKey: string[]`
An array of column names that form the primary key of the table you are syncing into. Used for updates and deletes.
-- `shapeKey: string`
- Optional identifier for the shape subscription - if provided the stream state will be persisted along with the data in order to allow resuming the stream between sessions.
+- `shapeKey: string | null`
+ Identifier for the shape subscription - If not null, stream state will be persisted along with the data in order to allow resuming the stream between sessions.
- `useCopy: boolean`
Whether to use the `COPY FROM` command to insert the initial data, defaults to `false`. This process may be faster than inserting row by row as it combines the inserts into a CSV to be passed to Postgres.
diff --git a/packages/pglite-sync/src/index.ts b/packages/pglite-sync/src/index.ts
index f3f8efe85..4bd8ce581 100644
--- a/packages/pglite-sync/src/index.ts
+++ b/packages/pglite-sync/src/index.ts
@@ -40,7 +40,7 @@ export interface SyncShapeToTableOptions {
schema?: string
mapColumns?: MapColumns
primaryKey: string[]
- shapeKey?: ShapeKey
+ shapeKey: ShapeKey | null
useCopy?: boolean
commitGranularity?: CommitGranularity
commitThrottle?: number
@@ -110,7 +110,7 @@ async function createPlugin(
shapePerTableLock.set(options.table)
let shapeSubState: ShapeSubscriptionState | null = null
- // if shapeKey is provided, ensure persistence of shape subscription
+ // if shapeKey is not null, ensure persistence of shape subscription
// state is possible and check if it is already persisted
if (options.shapeKey) {
shapeSubState = await getShapeSubscriptionState({
diff --git a/packages/pglite-sync/test/sync.test.ts b/packages/pglite-sync/test/sync.test.ts
index 60e209edc..5f6f4fe95 100644
--- a/packages/pglite-sync/test/sync.test.ts
+++ b/packages/pglite-sync/test/sync.test.ts
@@ -58,6 +58,7 @@ describe('pglite-sync', () => {
},
table: 'todo',
primaryKey: ['id'],
+ shapeKey: null,
})
// insert
@@ -130,6 +131,7 @@ describe('pglite-sync', () => {
},
table: 'todo',
primaryKey: ['id'],
+ shapeKey: null,
})
const numInserts = 10000
@@ -397,6 +399,7 @@ describe('pglite-sync', () => {
},
table: table,
primaryKey: ['id'],
+ shapeKey: null,
})
// should throw if syncing more shapes into same table
@@ -409,6 +412,7 @@ describe('pglite-sync', () => {
},
table: table,
primaryKey: ['id'],
+ shapeKey: null,
}),
).rejects.toThrowError(`Already syncing shape for table ${table}`)
@@ -420,6 +424,7 @@ describe('pglite-sync', () => {
},
table: altTable,
primaryKey: ['id'],
+ shapeKey: null,
})
altShape.unsubscribe()
@@ -434,6 +439,7 @@ describe('pglite-sync', () => {
},
table: table,
primaryKey: ['id'],
+ shapeKey: null,
})
shape2.unsubscribe()
})
@@ -454,6 +460,7 @@ describe('pglite-sync', () => {
},
table: 'todo',
primaryKey: ['id'],
+ shapeKey: null,
})
// insert
@@ -543,6 +550,7 @@ describe('pglite-sync', () => {
},
table: 'test_syncing',
primaryKey: ['id'],
+ shapeKey: null,
})
await feedMessage({
@@ -589,6 +597,7 @@ describe('pglite-sync', () => {
table: 'todo',
primaryKey: ['id'],
useCopy: true,
+ shapeKey: null,
})
// Create a batch of insert messages followed by an update
@@ -668,6 +677,7 @@ describe('pglite-sync', () => {
table: 'todo',
primaryKey: ['id'],
useCopy: true,
+ shapeKey: null,
})
const specialCharMessages: Message[] = [
@@ -765,6 +775,7 @@ describe('pglite-sync', () => {
table: 'todo',
primaryKey: ['id'],
commitGranularity: batchSize,
+ shapeKey: null,
})
// Create test messages - 7 total (should see batch of 5, then 2)
@@ -956,6 +967,7 @@ describe('pglite-sync', () => {
table: 'todo',
primaryKey: ['id'],
commitGranularity: 'up-to-date',
+ shapeKey: null,
})
// Send multiple messages
@@ -1035,6 +1047,7 @@ describe('pglite-sync', () => {
table: 'todo',
primaryKey: ['id'],
commitGranularity: 'operation',
+ shapeKey: null,
})
// Send multiple messages
@@ -1120,6 +1133,7 @@ describe('pglite-sync', () => {
primaryKey: ['id'],
commitGranularity: 'operation',
commitThrottle: throttleMs,
+ shapeKey: null,
})
// Send messages with 10ms delays between them
@@ -1209,6 +1223,7 @@ describe('pglite-sync', () => {
table: 'todo',
primaryKey: ['id'],
onInitialSync,
+ shapeKey: null,
})
// Send some initial data