meadow-integration 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "meadow-integration",
-    "version": "1.0.15",
+    "version": "1.0.17",
     "description": "Meadow Data Integration",
     "bin": {
         "mdwint": "source/cli/Meadow-Integration-CLI-Run.js"
@@ -16,7 +16,7 @@
     "author": "steven velozo <steven@velozo.com>",
     "license": "MIT",
     "devDependencies": {
-        "quackage": "^1.0.63"
+        "quackage": "^1.0.64"
     },
     "mocha": {
         "diff": true,

package/source/services/clone/Meadow-Service-Sync-Entity-Initial.js

@@ -41,6 +41,7 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 		this.PageSize = this.options.PageSize || 100;
 		this.SyncDeletedRecords = this.options.SyncDeletedRecords || false;
 		this.MaxRecordsPerEntity = this.options.MaxRecordsPerEntity || 0;
+		this.UseAdvancedIDPagination = this.options.UseAdvancedIDPagination || false;
 
 		this.Meadow = false;
 
@@ -459,14 +460,21 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 					this.operation.createProgressTracker(tmpSyncState.EstimatedRecordCount, `FullSync-${this.EntitySchema.TableName}`);
 					this.operation.printProgressTrackerStatus(`FullSync-${this.EntitySchema.TableName}`);
 
-					// Generate paginated URL partials
-					tmpSyncState.URLPartials = [];
-					for (let i = 0; i < tmpRecordCap; i += this.PageSize)
+					if (this.UseAdvancedIDPagination)
 					{
-						tmpSyncState.URLPartials.push(`${this.EntitySchema.TableName}s/FilteredTo/FBV~${this.DefaultIdentifier}~GT~${tmpSyncState.Local.MaxIDEntity}~FSF~${this.DefaultIdentifier}~ASC~ASC/${i}/${this.PageSize}`);
+						this.fable.log.info(`${this.EntitySchema.TableName}: using advanced ID pagination (local: ${tmpSyncState.Local.RecordCount}/${tmpSyncState.Local.MaxIDEntity}, server: ${tmpSyncState.Server.RecordCount}/${tmpSyncState.Server.MaxIDEntity}, estimated new: ${tmpSyncState.EstimatedRecordCount}${this.MaxRecordsPerEntity > 0 ? `, capped at ${this.MaxRecordsPerEntity}` : ''})`);
 					}
+					else
+					{
+						// Generate paginated URL partials
+						tmpSyncState.URLPartials = [];
+						for (let i = 0; i < tmpRecordCap; i += this.PageSize)
+						{
+							tmpSyncState.URLPartials.push(`${this.EntitySchema.TableName}s/FilteredTo/FBV~${this.DefaultIdentifier}~GT~${tmpSyncState.Local.MaxIDEntity}~FSF~${this.DefaultIdentifier}~ASC~ASC/${i}/${this.PageSize}`);
+						}
 
-					this.fable.log.info(`${this.EntitySchema.TableName}: downloading ${tmpSyncState.URLPartials.length} pages (local: ${tmpSyncState.Local.RecordCount}/${tmpSyncState.Local.MaxIDEntity}, server: ${tmpSyncState.Server.RecordCount}/${tmpSyncState.Server.MaxIDEntity}, estimated new: ${tmpSyncState.EstimatedRecordCount}${this.MaxRecordsPerEntity > 0 ? `, capped at ${this.MaxRecordsPerEntity}` : ''})`);
+						this.fable.log.info(`${this.EntitySchema.TableName}: downloading ${tmpSyncState.URLPartials.length} pages (local: ${tmpSyncState.Local.RecordCount}/${tmpSyncState.Local.MaxIDEntity}, server: ${tmpSyncState.Server.RecordCount}/${tmpSyncState.Server.MaxIDEntity}, estimated new: ${tmpSyncState.EstimatedRecordCount}${this.MaxRecordsPerEntity > 0 ? `, capped at ${this.MaxRecordsPerEntity}` : ''})`);
+					}
 
 					return fStageComplete();
 				},
@@ -477,149 +485,216 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 					let tmpRecordsSkipped = 0;
 					let tmpRecordsErrored = 0;
 
-					this.fable.Utility.eachLimit(tmpSyncState.URLPartials, 1,
-						(pURLPartial, fDownloadComplete) =>
-						{
-							tmpPageIndex++;
+					// Shared record-processing function used by both pagination modes
+					const fProcessPageRecords = (pBody, fPageProcessComplete) =>
+					{
+						this.fable.Utility.eachLimit(pBody, 5,
+							(pEntityRecord, fEntitySyncComplete) =>
+							{
+								const tmpRecord = pEntityRecord;
+								const tmpQuery = this.Meadow.query;
 
-							this.fable.MeadowCloneRestClient.getJSON(pURLPartial,
-								(pDownloadError, pResponse, pBody) =>
+								if ((typeof(tmpRecord[this.DefaultIdentifier]) !== 'undefined') && (tmpRecord[this.DefaultIdentifier] > 0))
 								{
-									if (pDownloadError)
-									{
-										this.fable.log.error(`${this.EntitySchema.TableName}: page ${tmpPageIndex} download error: ${pDownloadError}`);
-										return fDownloadComplete();
-									}
-									if (pBody && Array.isArray(pBody) && pBody.length > 0)
-									{
-										this.fable.Utility.eachLimit(pBody, 5,
-											(pEntityRecord, fEntitySyncComplete) =>
-											{
-												const tmpRecord = pEntityRecord;
-												const tmpQuery = this.Meadow.query;
-
-												if ((typeof(tmpRecord[this.DefaultIdentifier]) !== 'undefined') && (tmpRecord[this.DefaultIdentifier] > 0))
-												{
-													tmpQuery.addFilter(this.DefaultIdentifier, tmpRecord[this.DefaultIdentifier]);
-												}
+									tmpQuery.addFilter(this.DefaultIdentifier, tmpRecord[this.DefaultIdentifier]);
+								}
 
-												if (!tmpSyncState.HasDeletedColumn)
-												{
-													tmpQuery.setDisableDeleteTracking(true);
-												}
+								if (!tmpSyncState.HasDeletedColumn)
+								{
+									tmpQuery.setDisableDeleteTracking(true);
+								}
 
-												this.Meadow.doRead(tmpQuery,
-													(pReadError, pQuery, pRecord) =>
-													{
-														if (pReadError)
-														{
-															tmpRecordsErrored++;
-															return fEntitySyncComplete();
-														}
-														if (!pRecord)
-														{
-															// Record not found -- create it
-															const tmpRecordToCommit = this.marshalRecord(tmpRecord);
+								this.Meadow.doRead(tmpQuery,
+									(pReadError, pQuery, pRecord) =>
+									{
+										if (pReadError)
+										{
+											tmpRecordsErrored++;
+											return fEntitySyncComplete();
+										}
+										if (!pRecord)
+										{
+											// Record not found -- create it
+											const tmpRecordToCommit = this.marshalRecord(tmpRecord);
 
-															const tmpCreateQuery = this.Meadow.query.addRecord(tmpRecordToCommit);
+											const tmpCreateQuery = this.Meadow.query.addRecord(tmpRecordToCommit);
 
-															tmpCreateQuery.setDisableAutoIdentity(true);
-															tmpCreateQuery.setDisableAutoDateStamp(true);
-															tmpCreateQuery.setDisableAutoUserStamp(true);
-															tmpCreateQuery.setDisableDeleteTracking(true);
+											tmpCreateQuery.setDisableAutoIdentity(true);
+											tmpCreateQuery.setDisableAutoDateStamp(true);
+											tmpCreateQuery.setDisableAutoUserStamp(true);
+											tmpCreateQuery.setDisableDeleteTracking(true);
 
-															tmpCreateQuery.AllowIdentityInsert = true;
+											tmpCreateQuery.AllowIdentityInsert = true;
 
-															this.Meadow.doCreate(tmpCreateQuery,
-																(pCreateError) =>
+											this.Meadow.doCreate(tmpCreateQuery,
+												(pCreateError) =>
+												{
+													if (pCreateError)
+													{
+														let tmpErrorStr = (typeof(pCreateError) === 'string') ? pCreateError : JSON.stringify(pCreateError);
+														if (tmpErrorStr.toLowerCase().indexOf('duplicate') > -1 || tmpErrorStr.toLowerCase().indexOf('unique') > -1)
+														{
+															// Duplicate key (likely GUID conflict) -- fall back to update
+															this.log.warn(`${this.EntitySchema.TableName}: duplicate key on create for ID ${tmpRecord[this.DefaultIdentifier]}; falling back to update.`);
+															const tmpUpdateQuery = this.Meadow.query.addRecord(tmpRecordToCommit);
+															tmpUpdateQuery.setDisableAutoIdentity(true);
+															tmpUpdateQuery.setDisableAutoDateStamp(true);
+															tmpUpdateQuery.setDisableAutoUserStamp(true);
+															tmpUpdateQuery.setDisableDeleteTracking(true);
+															this.Meadow.doUpdate(tmpUpdateQuery,
+																(pUpdateError) =>
 																{
-																	if (pCreateError)
+																	if (pUpdateError)
 																	{
-																		let tmpErrorStr = (typeof(pCreateError) === 'string') ? pCreateError : JSON.stringify(pCreateError);
-																		if (tmpErrorStr.toLowerCase().indexOf('duplicate') > -1 || tmpErrorStr.toLowerCase().indexOf('unique') > -1)
-																		{
-																			// Duplicate key (likely GUID conflict) -- fall back to update
-																			this.log.warn(`${this.EntitySchema.TableName}: duplicate key on create for ID ${tmpRecord[this.DefaultIdentifier]}; falling back to update.`);
-																			const tmpUpdateQuery = this.Meadow.query.addRecord(tmpRecordToCommit);
-																			tmpUpdateQuery.setDisableAutoIdentity(true);
-																			tmpUpdateQuery.setDisableAutoDateStamp(true);
-																			tmpUpdateQuery.setDisableAutoUserStamp(true);
-																			tmpUpdateQuery.setDisableDeleteTracking(true);
-																			this.Meadow.doUpdate(tmpUpdateQuery,
-																				(pUpdateError) =>
-																				{
-																					if (pUpdateError)
-																					{
-																						tmpRecordsErrored++;
-																						this.log.error(`${this.EntitySchema.TableName}: fallback update also failed for ID ${tmpRecord[this.DefaultIdentifier]}: ${pUpdateError}`);
-																						return fEntitySyncComplete();
-																					}
-																					tmpRecordsCreated++;
-																					this.operation.incrementProgressTrackerStatus(`FullSync-${this.EntitySchema.TableName}`, 1);
-																					return fEntitySyncComplete();
-																				});
-																			return;
-																		}
 																		tmpRecordsErrored++;
-																		this.log.error(`${this.EntitySchema.TableName}: doCreate error for ID ${tmpRecord[this.DefaultIdentifier]}: ${pCreateError}`);
+																		this.log.error(`${this.EntitySchema.TableName}: fallback update also failed for ID ${tmpRecord[this.DefaultIdentifier]}: ${pUpdateError}`);
 																		return fEntitySyncComplete();
 																	}
 																	tmpRecordsCreated++;
 																	this.operation.incrementProgressTrackerStatus(`FullSync-${this.EntitySchema.TableName}`, 1);
 																	return fEntitySyncComplete();
 																});
+															return;
 														}
-														else
-														{
-															tmpRecordsSkipped++;
-															return fEntitySyncComplete();
-														}
-													});
-											},
-											(pEntitySyncError) =>
-											{
-												this.operation.printProgressTrackerStatus(`FullSync-${this.EntitySchema.TableName}`);
-												if (pEntitySyncError)
-												{
-													this.log.error(`Problem or early completion syncing entity ${this.EntitySchema.TableName}: ${pEntitySyncError}`, pEntitySyncError);
-												}
-												return fDownloadComplete();
-											});
-									}
-									else
-									{
-										if (Array.isArray(pBody) && pBody.length == 0)
+														tmpRecordsErrored++;
+														this.log.error(`${this.EntitySchema.TableName}: doCreate error for ID ${tmpRecord[this.DefaultIdentifier]}: ${pCreateError}`);
+														return fEntitySyncComplete();
+													}
+													tmpRecordsCreated++;
+													this.operation.incrementProgressTrackerStatus(`FullSync-${this.EntitySchema.TableName}`, 1);
+													return fEntitySyncComplete();
+												});
+										}
+										else
 										{
-											return fDownloadComplete(new Error('Records depleted!'));
+											tmpRecordsSkipped++;
+											return fEntitySyncComplete();
 										}
-										return fDownloadComplete();
-									}
-								});
-						},
-						(pDownloadError) =>
+									});
+							},
+							(pEntitySyncError) =>
+							{
+								this.operation.printProgressTrackerStatus(`FullSync-${this.EntitySchema.TableName}`);
+								if (pEntitySyncError)
+								{
+									this.log.error(`Problem or early completion syncing entity ${this.EntitySchema.TableName}: ${pEntitySyncError}`, pEntitySyncError);
+								}
+								return fPageProcessComplete(pEntitySyncError);
+							});
+					};
+
+					const fSyncComplete = (pDownloadError) =>
+					{
+						this.fable.log.info(`${this.EntitySchema.TableName}: sync complete — created: ${tmpRecordsCreated}, skipped: ${tmpRecordsSkipped}, errors: ${tmpRecordsErrored}`);
+						if (pDownloadError)
+						{
+							this.fable.log.error(`Error returned URL Partial .. this may not be an error: ${pDownloadError}`);
+						}
+
+						// Store sync results on the entity so callers can inspect the breakdown
+						this.syncResults = (
+							{
+								Created: tmpRecordsCreated,
+								Skipped: tmpRecordsSkipped,
+								Errors: tmpRecordsErrored,
+								Deleted: 0,
+								ServerRecordCount: tmpSyncState.Server.RecordCount,
+								LocalRecordCount: tmpSyncState.Local.RecordCount,
+								ServerMaxID: tmpSyncState.Server.MaxIDEntity,
+								LocalMaxID: tmpSyncState.Local.MaxIDEntity,
+								EstimatedNew: tmpSyncState.EstimatedRecordCount
+							});
+
+						fStageComplete();
+					};
+
+					if (this.UseAdvancedIDPagination)
+					{
+						// Advanced ID pagination: use keyset pagination (WHERE ID > lastMaxID)
+						// instead of OFFSET to avoid progressive table scan slowdown on large datasets.
+						let tmpLastMaxID = tmpSyncState.Local.MaxIDEntity;
+						let tmpTotalFetched = 0;
+
+						const fFetchPage = () =>
 						{
-							this.fable.log.info(`${this.EntitySchema.TableName}: sync complete — created: ${tmpRecordsCreated}, skipped: ${tmpRecordsSkipped}, errors: ${tmpRecordsErrored}`);
-							if (pDownloadError)
+							if (tmpTotalFetched >= tmpRecordCap)
 							{
-								this.fable.log.error(`Error returned URL Partial .. this may not be an error: ${pDownloadError}`);
+								return fSyncComplete();
 							}
 
-							// Store sync results on the entity so callers can inspect the breakdown
-							this.syncResults = (
+							tmpPageIndex++;
+							let tmpURL = `${this.EntitySchema.TableName}s/FilteredTo/FBV~${this.DefaultIdentifier}~GT~${tmpLastMaxID}~FSF~${this.DefaultIdentifier}~ASC~ASC/0/${this.PageSize}`;
+
+							this.fable.MeadowCloneRestClient.getJSON(tmpURL,
+								(pDownloadError, pResponse, pBody) =>
 								{
-									Created: tmpRecordsCreated,
-									Skipped: tmpRecordsSkipped,
-									Errors: tmpRecordsErrored,
-									Deleted: 0,
-									ServerRecordCount: tmpSyncState.Server.RecordCount,
-									LocalRecordCount: tmpSyncState.Local.RecordCount,
-									ServerMaxID: tmpSyncState.Server.MaxIDEntity,
-									LocalMaxID: tmpSyncState.Local.MaxIDEntity,
-									EstimatedNew: tmpSyncState.EstimatedRecordCount
+									if (pDownloadError)
+									{
+										this.fable.log.error(`${this.EntitySchema.TableName}: page ${tmpPageIndex} download error: ${pDownloadError}`);
+										return fSyncComplete(pDownloadError);
+									}
+									if (pBody && Array.isArray(pBody) && pBody.length > 0)
+									{
+										// Track the max ID from this page for the next page filter
+										for (let r = 0; r < pBody.length; r++)
+										{
+											if (pBody[r][this.DefaultIdentifier] > tmpLastMaxID)
+											{
+												tmpLastMaxID = pBody[r][this.DefaultIdentifier];
+											}
+										}
+										tmpTotalFetched += pBody.length;
+
+										fProcessPageRecords(pBody, (pProcessError) =>
+										{
+											if (pProcessError)
+											{
+												return fSyncComplete(pProcessError);
+											}
+											return setImmediate(fFetchPage);
+										});
+									}
+									else
+									{
+										// No more records
+										return fSyncComplete();
+									}
 								});
+						};
+						fFetchPage();
+					}
+					else
+					{
+						// Standard offset-based pagination
+						this.fable.Utility.eachLimit(tmpSyncState.URLPartials, 1,
+							(pURLPartial, fDownloadComplete) =>
+							{
+								tmpPageIndex++;
 
-							fStageComplete();
-						});
+								this.fable.MeadowCloneRestClient.getJSON(pURLPartial,
+									(pDownloadError, pResponse, pBody) =>
+									{
+										if (pDownloadError)
+										{
+											this.fable.log.error(`${this.EntitySchema.TableName}: page ${tmpPageIndex} download error: ${pDownloadError}`);
+											return fDownloadComplete();
+										}
+										if (pBody && Array.isArray(pBody) && pBody.length > 0)
+										{
+											fProcessPageRecords(pBody, fDownloadComplete);
+										}
+										else
+										{
+											if (Array.isArray(pBody) && pBody.length == 0)
+											{
+												return fDownloadComplete(new Error('Records depleted!'));
+											}
+											return fDownloadComplete();
+										}
+									});
+							},
+							fSyncComplete);
+					}
 				},
 			],
 			(pError) =>

package/source/services/clone/Meadow-Service-Sync-Entity-Ongoing.js

@@ -372,6 +372,10 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 											{
 												this.log.error(`Fallback update also failed for ${this.EntitySchema.TableName} ID ${pServerRecord[this.DefaultIdentifier]}: ${pUpdateError}`);
 											}
+											else
+											{
+												this._recordsUpdated++;
+											}
 											return fCallback();
 										});
 									return;
@@ -379,6 +383,10 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 								this.log.error(`Error creating record ${this.EntitySchema.TableName}: ${pCreateError}`, pCreateError);
 								return fCallback();
 							}
+							else
+							{
+								this._recordsCreated++;
+							}
 							return fCallback();
 						});
 				}
@@ -392,6 +400,10 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 							{
 								this.log.error(`Error updating record ${this.EntitySchema.TableName}: ${pUpdateError}`, pUpdateError);
 							}
+							else
+							{
+								this._recordsUpdated++;
+							}
 							return fCallback();
 						});
 				}
@@ -407,12 +419,22 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 			return fCallback(null, 0);
 		}
 
+		// Check the global cap before starting -- if we have already synced
+		// MaxRecordsPerEntity records across all stages, stop immediately.
+		if (this.MaxRecordsPerEntity > 0 && this._totalSyncedThisSync >= this.MaxRecordsPerEntity)
+		{
+			this.fable.log.info(`${this.EntitySchema.TableName}: global record cap reached (${this._totalSyncedThisSync}/${this.MaxRecordsPerEntity}); skipping pull.`);
+			return fCallback(null, 0);
+		}
+
 		let tmpSyncedCount = 0;
 		let tmpOffset = 0;
 		let tmpDone = false;
 
+		// Apply per-call cap based on estimated count, then further limit by
+		// how many records remain before hitting the global MaxRecordsPerEntity.
 		let tmpRecordCap = (this.MaxRecordsPerEntity > 0)
-			? Math.min(pEstimatedCount, this.MaxRecordsPerEntity)
+			? Math.min(pEstimatedCount, this.MaxRecordsPerEntity - this._totalSyncedThisSync)
 			: pEstimatedCount;
 
 		const fFetchPage = () =>
@@ -443,6 +465,7 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 								() =>
 								{
 									tmpSyncedCount++;
+									this._totalSyncedThisSync++;
 									// Use setImmediate to yield the event loop and prevent
 									// stack overflow when SQLite callbacks complete synchronously
 									return setImmediate(fRecordDone);
@@ -485,6 +508,12 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 	// the range from the server to bring local in sync.
 	_bisectRange(pMinID, pMaxID, pDepth, fCallback)
 	{
+		// If the global record cap has been reached, stop bisecting
+		if (this.MaxRecordsPerEntity > 0 && this._totalSyncedThisSync >= this.MaxRecordsPerEntity)
+		{
+			return fCallback();
+		}
+
 		const tmpRangeSize = pMaxID - pMinID + 1;
 		const tmpIDCol = this.DefaultIdentifier;
 		const tmpRangeFilter = `FBV~${tmpIDCol}~GE~${pMinID}~FBV~${tmpIDCol}~LE~${pMaxID}`;
@@ -768,7 +797,7 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 			{
 				if (pReadError)
 				{
-					let tmpErrorStr = (typeof(pReadError) === 'string') ? pReadError : JSON.stringify(pReadError);
+					let tmpErrorStr = (typeof(pReadError) === 'string') ? pReadError : String(pReadError);
 					if (tmpErrorStr.indexOf('Invalid column') > -1 || tmpErrorStr.indexOf('Invalid object') > -1 || tmpErrorStr.indexOf('no such column') > -1 || tmpErrorStr.indexOf('no such table') > -1)
 					{
 						this.log.warn(`${this.EntitySchema.TableName}: local table schema mismatch (${pReadError}); skipping sync.`);
@@ -783,6 +812,13 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 	{
 		this.operation.createTimeStamp('EntityOngoingSync');
 
+		// Track total records synced across all stages to enforce MaxRecordsPerEntity globally
+		this._totalSyncedThisSync = 0;
+
+		// Track per-record create vs update counts for the sync report
+		this._recordsCreated = 0;
+		this._recordsUpdated = 0;
+
 		const tmpSyncState = (
 			{
 				Local: { MaxIDEntity: -1, RecordCount: 0 },
@@ -941,7 +977,10 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 					// Create a progress tracker so callers (e.g. data-cloner UI) can see Total/Synced
 				(fStageComplete) =>
 				{
-					this.operation.createProgressTracker(tmpSyncState.Server.RecordCount, `FullSync-${this.EntitySchema.TableName}`);
+					let tmpTrackerTotal = (this.MaxRecordsPerEntity > 0)
+					? Math.min(tmpSyncState.Server.RecordCount, this.MaxRecordsPerEntity)
+					: tmpSyncState.Server.RecordCount;
+				this.operation.createProgressTracker(tmpTrackerTotal, `FullSync-${this.EntitySchema.TableName}`);
 					return fStageComplete();
 				},
 
@@ -1126,6 +1165,15 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 
 				this.fable.log.info(`${this.EntitySchema.TableName}: ongoing sync complete.`);
 
+		// Store sync results so callers can inspect the breakdown
+		this.syncResults = {
+			Created: this._recordsCreated,
+			Updated: this._recordsUpdated,
+			Deleted: 0,
+			ServerRecordCount: tmpSyncState.Server.RecordCount,
+			LocalRecordCount: tmpSyncState.Local.RecordCount
+		};
+
 				if (this.SyncDeletedRecords)
 				{
 					return this.syncDeletedRecords(() => { return fCallback(); });

package/source/services/clone/Meadow-Service-Sync.js

@@ -65,6 +65,18 @@ class MeadowSync extends libFableServiceProviderBase
 			this.MaxRecordsPerEntity = parseInt(this.options.MaxRecordsPerEntity, 10) || 0;
 		}
 
+		// When true, use ID-based keyset pagination instead of OFFSET pagination.
+		// This avoids table scans on large datasets by filtering WHERE ID > lastMaxID.
+		this.UseAdvancedIDPagination = false;
+		if (this.fable.ProgramConfiguration.hasOwnProperty('UseAdvancedIDPagination'))
+		{
+			this.UseAdvancedIDPagination = !!this.fable.ProgramConfiguration.UseAdvancedIDPagination;
+		}
+		else if (this.options.hasOwnProperty('UseAdvancedIDPagination'))
+		{
+			this.UseAdvancedIDPagination = !!this.options.UseAdvancedIDPagination;
+		}
+
 		// Tolerance window in milliseconds for cross-database timestamp precision differences.
 		// Passed through to Ongoing sync entities for bisection date comparison.
 		this.DateTimePrecisionMS = 1000;
@@ -114,6 +126,7 @@ class MeadowSync extends libFableServiceProviderBase
 						SyncDeletedRecords: this.SyncDeletedRecords,
 						MaxRecordsPerEntity: this.MaxRecordsPerEntity,
 						DateTimePrecisionMS: this.DateTimePrecisionMS,
+						UseAdvancedIDPagination: this.UseAdvancedIDPagination,
 					};
 
 					let tmpSyncEntity;