@powersync/service-module-mssql 0.5.0 → 0.6.1

package/src/utils/mssql.ts

@@ -1,14 +1,21 @@
 import sql from 'mssql';
 import { coerce, gte } from 'semver';
 import { logger } from '@powersync/lib-services-framework';
+import { retryOnDeadlock } from './deadlock.js';
 import { MSSQLConnectionManager } from '../replication/MSSQLConnectionManager.js';
 import { LSN } from '../common/LSN.js';
-import { CaptureInstance, MSSQLSourceTable } from '../common/MSSQLSourceTable.js';
+import { MSSQLSourceTable } from '../common/MSSQLSourceTable.js';
 import { MSSQLParameter } from '../types/mssql-data-types.js';
+import * as sync_rules from '@powersync/service-sync-rules';
 import { SqlSyncRules, TablePattern } from '@powersync/service-sync-rules';
-import { getReplicationIdentityColumns, ReplicationIdentityColumnsResult, ResolvedTable } from './schema.js';
+import {
+  getPendingSchemaChanges,
+  getReplicationIdentityColumns,
+  ReplicationIdentityColumnsResult,
+  ResolvedTable
+} from './schema.js';
 import * as service_types from '@powersync/service-types';
-import * as sync_rules from '@powersync/service-sync-rules';
+import { CaptureInstance } from '../common/CaptureInstance.js';
 
 export const POWERSYNC_CHECKPOINTS_TABLE = '_powersync_checkpoints';
 
@@ -78,16 +85,16 @@ export async function checkSourceConfiguration(connectionManager: MSSQLConnectio
   }
 
   // 4) Check if the _powersync_checkpoints table is correctly configured
-  const checkpointTableErrors = await ensurePowerSyncCheckpointsTable(connectionManager);
+  const checkpointTableErrors = await checkPowerSyncCheckpointsTable(connectionManager);
   errors.push(...checkpointTableErrors);
 
   return errors;
 }
 
-export async function ensurePowerSyncCheckpointsTable(connectionManager: MSSQLConnectionManager): Promise<string[]> {
+export async function checkPowerSyncCheckpointsTable(connectionManager: MSSQLConnectionManager): Promise<string[]> {
   const errors: string[] = [];
   try {
-    // check if the dbo_powersync_checkpoints table exists
+    // Check if the table exists
     const { recordset: checkpointsResult } = await connectionManager.query(
       `
     SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = @tableName;
@@ -97,45 +104,22 @@ export async function ensurePowerSyncCheckpointsTable(connectionManager: MSSQLCo
         { name: 'tableName', type: sql.VarChar(sql.MAX), value: POWERSYNC_CHECKPOINTS_TABLE }
       ]
     );
-    if (checkpointsResult.length > 0) {
-      // Table already exists, check if CDC is enabled
-      const isEnabled = await isTableEnabledForCDC({
-        connectionManager,
-        table: POWERSYNC_CHECKPOINTS_TABLE,
-        schema: connectionManager.schema
-      });
-      if (!isEnabled) {
-        // Enable CDC on the table
-        await enableCDCForTable({
-          connectionManager,
-          table: POWERSYNC_CHECKPOINTS_TABLE
-        });
-      }
-      return errors;
+    if (checkpointsResult.length === 0) {
+      throw new Error(`The ${POWERSYNC_CHECKPOINTS_TABLE} table does not exist. Please create it.`);
     }
-  } catch (error) {
-    errors.push(`Failed ensure ${POWERSYNC_CHECKPOINTS_TABLE} table is correctly configured: ${error}`);
-  }
-
-  // Try to create the table
-  try {
-    await connectionManager.query(`
-  CREATE TABLE ${toQualifiedTableName(connectionManager.schema, POWERSYNC_CHECKPOINTS_TABLE)} (
-    id INT IDENTITY PRIMARY KEY,
-    last_updated DATETIME NOT NULL DEFAULT (GETDATE())
-  )`);
-  } catch (error) {
-    errors.push(`Failed to create ${POWERSYNC_CHECKPOINTS_TABLE} table: ${error}`);
-  }
-
-  try {
-    // Enable CDC on the table if not already enabled
-    await enableCDCForTable({
+    // Check if CDC is enabled
+    const isEnabled = await isTableEnabledForCDC({
       connectionManager,
-      table: POWERSYNC_CHECKPOINTS_TABLE
+      table: POWERSYNC_CHECKPOINTS_TABLE,
+      schema: connectionManager.schema
     });
+    if (!isEnabled) {
+      throw new Error(
+        `The ${POWERSYNC_CHECKPOINTS_TABLE} table exists but is not enabled for CDC. Please enable CDC on this table.`
+      );
+    }
   } catch (error) {
-    errors.push(`Failed to enable CDC on ${POWERSYNC_CHECKPOINTS_TABLE} table: ${error}`);
+    errors.push(`Failed ensure ${POWERSYNC_CHECKPOINTS_TABLE} table is correctly configured: ${error}`);
   }
 
   return errors;
@@ -165,36 +149,9 @@ export interface IsTableEnabledForCDCOptions {
 export async function isTableEnabledForCDC(options: IsTableEnabledForCDCOptions): Promise<boolean> {
   const { connectionManager, table, schema } = options;
 
-  const { recordset: checkResult } = await connectionManager.query(
-    `
-      SELECT 1 FROM cdc.change_tables ct
-         JOIN sys.tables    AS tbl ON tbl.object_id = ct.source_object_id
-         JOIN sys.schemas   AS sch ON sch.schema_id = tbl.schema_id
-      WHERE sch.name = @schema
-        AND tbl.name = @tableName
-      `,
-    [
-      { name: 'schema', type: sql.VarChar(sql.MAX), value: schema },
-      { name: 'tableName', type: sql.VarChar(sql.MAX), value: table }
-    ]
-  );
-  return checkResult.length > 0;
-}
-
-export interface EnableCDCForTableOptions {
-  connectionManager: MSSQLConnectionManager;
-  table: string;
-}
-
-export async function enableCDCForTable(options: EnableCDCForTableOptions): Promise<void> {
-  const { connectionManager, table } = options;
+  const captureInstance = await getCaptureInstance({ connectionManager, table: { schema, name: table } });
 
-  await connectionManager.execute('sys.sp_cdc_enable_table', [
-    { name: 'source_schema', value: connectionManager.schema },
-    { name: 'source_name', value: table },
-    { name: 'role_name', value: 'NULL' },
-    { name: 'supports_net_changes', value: 1 }
-  ]);
+  return captureInstance != null;
 }
 
 /**
@@ -216,23 +173,28 @@ export interface IsWithinRetentionThresholdOptions {
 }
 
 /**
- *  Checks that CDC the specified checkpoint LSN is within the retention threshold for all specified tables.
+ *  Checks that the given checkpoint LSN is still within the retention threshold of the source table capture instances.
  *  CDC periodically cleans up old data up to the retention threshold. If replication has been stopped for too long it is
  *  possible for the checkpoint LSN to be older than the minimum LSN in the CDC tables. In such a case we need to perform a new snapshot.
  *  @param options
  */
-export async function isWithinRetentionThreshold(options: IsWithinRetentionThresholdOptions): Promise<boolean> {
+export async function checkRetentionThresholds(
+  options: IsWithinRetentionThresholdOptions
+): Promise<MSSQLSourceTable[]> {
   const { checkpointLSN, tables, connectionManager } = options;
+  const tablesOutsideRetentionThreshold: MSSQLSourceTable[] = [];
   for (const table of tables) {
-    const minLSN = await getMinLSN(connectionManager, table.captureInstance);
-    if (minLSN > checkpointLSN) {
-      logger.warn(
-        `The checkpoint LSN:[${checkpointLSN}] is older than the minimum LSN:[${minLSN}] for table ${table.sourceTable.qualifiedName}. This indicates that the checkpoint LSN is outside of the retention window.`
-      );
-      return false;
+    if (table.enabledForCDC()) {
+      const minLSN = await getMinLSN(connectionManager, table.captureInstance!.name);
+      if (minLSN > checkpointLSN) {
+        logger.warn(
+          `The checkpoint LSN:[${checkpointLSN}] is older than the minimum LSN:[${minLSN}] for table ${table.toQualifiedName()}. This indicates that the checkpoint LSN is outside of the retention window.`
+        );
+        tablesOutsideRetentionThreshold.push(table);
+      }
     }
   }
-  return true;
+  return tablesOutsideRetentionThreshold;
 }
 
 export async function getMinLSN(connectionManager: MSSQLConnectionManager, captureInstance: string): Promise<LSN> {
@@ -252,43 +214,6 @@ export async function incrementLSN(lsn: LSN, connectionManager: MSSQLConnectionM
   return LSN.fromBinary(result[0].incremented_lsn);
 }
 
-export interface GetCaptureInstanceOptions {
-  connectionManager: MSSQLConnectionManager;
-  tableName: string;
-  schema: string;
-}
-
-export async function getCaptureInstance(options: GetCaptureInstanceOptions): Promise<CaptureInstance | null> {
-  const { connectionManager, tableName, schema } = options;
-  const { recordset: result } = await connectionManager.query(
-    `
-      SELECT
-        ct.capture_instance,
-        OBJECT_SCHEMA_NAME(ct.[object_id]) AS cdc_schema
-      FROM
-        sys.tables tbl
-          INNER JOIN sys.schemas sch ON tbl.schema_id = sch.schema_id
-          INNER JOIN cdc.change_tables ct ON ct.source_object_id = tbl.object_id
-      WHERE sch.name = @schema
-        AND tbl.name = @tableName
-        AND ct.end_lsn IS NULL;
-      `,
-    [
-      { name: 'schema', type: sql.VarChar(sql.MAX), value: schema },
-      { name: 'tableName', type: sql.VarChar(sql.MAX), value: tableName }
-    ]
-  );
-
-  if (result.length === 0) {
-    return null;
-  }
-
-  return {
-    name: result[0].capture_instance,
-    schema: result[0].cdc_schema
-  };
-}
-
 /**
  *  Return the LSN of the latest transaction recorded in the transaction log
  *  @param connectionManager
@@ -406,18 +331,28 @@ export async function getDebugTableInfo(options: GetDebugTableInfoOptions): Prom
     selectError = { level: 'fatal', message: e.message };
   }
 
-  // Check if CDC is enabled for the table
   let cdcError: service_types.ReplicationError | null = null;
+  let schemaDriftError: service_types.ReplicationError | null = null;
   try {
-    const isEnabled = await isTableEnabledForCDC({
+    const captureInstanceDetails = await getCaptureInstance({
       connectionManager: connectionManager,
-      table: table.name,
-      schema: schema
+      table: {
+        schema: schema,
+        name: table.name
+      }
     });
-    if (!isEnabled) {
+    if (captureInstanceDetails == null) {
       cdcError = {
-        level: 'fatal',
-        message: `CDC is not enabled for table ${toQualifiedTableName(schema, table.name)}. Enable CDC with: sys.sp_cdc_enable_table @source_schema = '${schema}', @source_name = '${table.name}', @role_name = NULL, @supports_net_changes = 1`
+        level: 'warning',
+        message: `CDC is not enabled for table ${toQualifiedTableName(schema, table.name)}. Please enable CDC on the table to capture changes.`
+      };
+    }
+
+    if (captureInstanceDetails && captureInstanceDetails.instances[0].pendingSchemaChanges.length > 0) {
+      schemaDriftError = {
+        level: 'warning',
+        message: `Source table ${toQualifiedTableName(schema, table.name)} has schema changes not reflected in the CDC capture instance. Please disable and re-enable CDC on the source table to update the capture instance schema.
+        Pending schema changes: ${captureInstanceDetails.instances[0].pendingSchemaChanges.join(', \n')}`
       };
     }
   } catch (e) {
@@ -433,6 +368,106 @@ export async function getDebugTableInfo(options: GetDebugTableInfoOptions): Prom
     replication_id: idColumns.map((c) => c.name),
     data_queries: syncData,
     parameter_queries: syncParameters,
-    errors: [idColumnsError, selectError, cdcError].filter((error) => error != null) as service_types.ReplicationError[]
+    errors: [idColumnsError, selectError, cdcError, schemaDriftError].filter(
+      (error) => error != null
+    ) as service_types.ReplicationError[]
+  };
+}
+
+// Describes the capture instances linked to a source table.
+export interface CaptureInstanceDetails {
+  sourceTable: {
+    schema: string;
+    name: string;
+    objectId: number;
+  };
+
+  /**
+   *  The capture instances for the source table.
+   *  The instances are sorted by create date in descending order.
+   */
+  instances: CaptureInstance[];
+}
+
+export interface GetCaptureInstancesOptions {
+  connectionManager: MSSQLConnectionManager;
+  table?: {
+    schema: string;
+    name: string;
+  };
+}
+
+export async function getCaptureInstances(
+  options: GetCaptureInstancesOptions
+): Promise<Map<number, CaptureInstanceDetails>> {
+  return retryOnDeadlock(async () => {
+    const { connectionManager, table } = options;
+    const instances = new Map<number, CaptureInstanceDetails>();
+
+    const { recordset: results } = table
+      ? await connectionManager.execute('sys.sp_cdc_help_change_data_capture', [
+          { name: 'source_schema', value: table.schema },
+          { name: 'source_name', value: table.name }
+        ])
+      : await connectionManager.execute('sys.sp_cdc_help_change_data_capture', []);
+
+    if (results.length === 0) {
+      return new Map<number, CaptureInstanceDetails>();
+    }
+
+    for (const row of results) {
+      const instance: CaptureInstance = {
+        name: row.capture_instance,
+        objectId: row.object_id,
+        minLSN: LSN.fromBinary(row.start_lsn),
+        createDate: new Date(row.create_date),
+        pendingSchemaChanges: []
+      };
+
+      instance.pendingSchemaChanges = await getPendingSchemaChanges({
+        connectionManager: connectionManager,
+        captureInstanceName: instance.name
+      });
+
+      const sourceTable = {
+        schema: row.source_schema,
+        name: row.source_table,
+        objectId: row.source_object_id
+      };
+
+      // There can only ever be 2 capture instances active at any given time for a source table.
+      if (instances.has(row.source_object_id)) {
+        if (instance.createDate > instances.get(row.source_object_id)!.instances[0].createDate) {
+          instances.get(row.source_object_id)!.instances.unshift(instance);
+        } else {
+          instances.get(row.source_object_id)!.instances.push(instance);
+        }
+      } else {
+        instances.set(row.source_object_id, {
+          instances: [instance],
+          sourceTable
+        });
+      }
+    }
+
+    return instances;
+  }, 'getCaptureInstances');
+}
+
+export interface GetCaptureInstanceOptions {
+  connectionManager: MSSQLConnectionManager;
+  table: {
+    schema: string;
+    name: string;
   };
 }
+export async function getCaptureInstance(options: GetCaptureInstanceOptions): Promise<CaptureInstanceDetails | null> {
+  const { connectionManager, table } = options;
+  const instances = await getCaptureInstances({ connectionManager, table });
+
+  if (instances.size === 0) {
+    return null;
+  }
+
+  return instances.values().next().value!;
+}

package/src/utils/schema.ts

@@ -3,6 +3,7 @@ import { TablePattern } from '@powersync/service-sync-rules';
 import { MSSQLConnectionManager } from '../replication/MSSQLConnectionManager.js';
 import { MSSQLColumnDescriptor } from '../types/mssql-data-types.js';
 import sql from 'mssql';
+import { logger } from '@powersync/lib-services-framework';
 
 export interface GetColumnsOptions {
   connectionManager: MSSQLConnectionManager;
@@ -198,3 +199,45 @@ export async function getTablesFromPattern(
     });
   }
 }
+
+export interface GetPendingSchemaChangesOptions {
+  connectionManager: MSSQLConnectionManager;
+  captureInstanceName: string;
+}
+
+/**
+ *  Returns the DDL commands that have been applied to the source table since the capture instance was created.
+ */
+export async function getPendingSchemaChanges(options: GetPendingSchemaChangesOptions): Promise<string[]> {
+  const { connectionManager, captureInstanceName } = options;
+
+  try {
+    const { recordset: results } = await connectionManager.execute('sys.sp_cdc_get_ddl_history', [
+      { name: 'capture_instance', type: sql.VarChar(sql.MAX), value: captureInstanceName }
+    ]);
+    return results.map((row) => row.ddl_command);
+  } catch (e) {
+    if (isObjectNotExistError(e)) {
+      // Defensive check to cover the case where the capture instance metadata is temporarily unavailable.
+      logger.warn(`Unable to retrieve schema changes for capture instance: [${captureInstanceName}].`);
+      return [];
+    }
+    throw e;
+  }
+}
+
+function isObjectNotExistError(error: unknown): boolean {
+  if (error != null && typeof error === 'object' && 'number' in error) {
+    // SQL Server Object does not exist or access is denied error number.
+    return (error as { number: unknown }).number === 22981;
+  }
+  return false;
+}
+
+export async function tableExists(tableId: number, connectionManager: MSSQLConnectionManager): Promise<boolean> {
+  const { recordset: results } = await connectionManager.query(`SELECT 1 FROM sys.tables WHERE object_id = @tableId`, [
+    { name: 'tableId', type: sql.Int, value: tableId }
+  ]);
+
+  return results.length > 0;
+}

package/test/src/CDCStreamTestContext.ts

@@ -129,6 +129,7 @@ export class CDCStreamTestContext implements AsyncDisposable {
         pollingIntervalMs: 1000,
         trustServerCertificate: true
       },
+      schemaCheckIntervalMs: 500,
       ...this.cdcStreamOptions
     };
     this._cdcStream = new CDCStream(options);
@@ -140,7 +141,7 @@ export class CDCStreamTestContext implements AsyncDisposable {
    */
   async initializeReplication() {
     await this.replicateSnapshot();
-    // TODO: renable this.startStreaming();
+    await this.startStreaming();
     // Make sure we're up to date
     await this.getCheckpoint();
   }
@@ -150,11 +151,12 @@ export class CDCStreamTestContext implements AsyncDisposable {
     this.replicationDone = true;
   }
 
-  // TODO: Enable once streaming is implemented
   startStreaming() {
     if (!this.replicationDone) {
       throw new Error('Call replicateSnapshot() before startStreaming()');
     }
+
+    this.cdcStream.isStartingReplication = true;
     this.streamPromise = this.cdcStream.streamChanges();
     // Wait for the replication to start before returning.
     // This avoids a bunch of unpredictable race conditions that appear in testing
@@ -212,6 +214,11 @@ export class CDCStreamTestContext implements AsyncDisposable {
     return data;
   }
 
+  async getFinalBucketState(bucket: string) {
+    const data = await this.getBucketData(bucket);
+    return test_utils.reduceBucket(data).slice(1);
+  }
+
   /**
    * This does not wait for a client checkpoint.
    */

package/test/src/env.ts

@@ -5,7 +5,7 @@ export const env = utils.collectEnvironmentVariables({
   MONGO_TEST_URL: utils.type.string.default('mongodb://localhost:27017/powersync_test'),
   CI: utils.type.boolean.default('false'),
   SLOW_TESTS: utils.type.boolean.default('false'),
-  PG_STORAGE_TEST_URL: utils.type.string.default('postgres://postgres:postgres@localhost:5431/powersync_storage_test'),
+  PG_STORAGE_TEST_URL: utils.type.string.default('postgres://postgres:postgres@localhost:5432/powersync_storage_test'),
   TEST_MONGO_STORAGE: utils.type.boolean.default('true'),
   TEST_POSTGRES_STORAGE: utils.type.boolean.default('true')
 });

package/test/src/mssql-to-sqlite.test.ts

@@ -6,19 +6,24 @@ import {
   TimeValuePrecision
 } from '@powersync/service-sync-rules';
 import { afterAll, beforeEach, describe, expect, test } from 'vitest';
-import { clearTestDb, createUpperCaseUUID, TEST_CONNECTION_OPTIONS, waitForPendingCDCChanges } from './util.js';
+import {
+  clearTestDb,
+  createUpperCaseUUID,
+  enableCDCForTable,
+  TEST_CONNECTION_OPTIONS,
+  waitForPendingCDCChanges
+} from './util.js';
 import { CDCToSqliteRow, toSqliteInputRow } from '@module/common/mssqls-to-sqlite.js';
 import { MSSQLConnectionManager } from '@module/replication/MSSQLConnectionManager.js';
 import {
-  enableCDCForTable,
   escapeIdentifier,
-  getCaptureInstance,
+  getCaptureInstances,
   getLatestLSN,
   getLatestReplicatedLSN,
-  getMinLSN,
   toQualifiedTableName
 } from '@module/utils/mssql.js';
 import sql from 'mssql';
+import { CDC_SCHEMA } from '@module/common/MSSQLSourceTable.js';
 
 describe('MSSQL Data Types Tests', () => {
   const connectionManager = new MSSQLConnectionManager(TEST_CONNECTION_OPTIONS, {});
@@ -482,20 +487,23 @@ async function getReplicatedRows(
 ): Promise<SqliteInputRow[]> {
   const endLSN = await getLatestReplicatedLSN(connectionManager);
 
-  const captureInstance = await getCaptureInstance({
+  const captureInstances = await getCaptureInstances({
     connectionManager,
-    schema: connectionManager.schema,
-    tableName
+    table: {
+      schema: connectionManager.schema,
+      name: tableName
+    }
   });
-  if (!captureInstance) {
+  if (captureInstances.size === 0) {
     throw new Error(`No CDC capture instance found for table ${tableName}`);
   }
 
-  const startLSN = await getMinLSN(connectionManager, captureInstance.name);
+  const captureInstance = Array.from(captureInstances.values())[0].instances[0];
+  const startLSN = captureInstance.minLSN;
   // Query CDC changes
   const { recordset: results } = await connectionManager.query(
     `
-      SELECT * FROM ${captureInstance.schema}.fn_cdc_get_all_changes_${captureInstance.name}(@from_lsn, @to_lsn, 'all update old') ORDER BY __$start_lsn, __$seqval
+      SELECT * FROM ${CDC_SCHEMA}.fn_cdc_get_all_changes_${captureInstance.name}(@from_lsn, @to_lsn, 'all update old') ORDER BY __$start_lsn, __$seqval
   `,
     [
       { name: 'from_lsn', type: sql.VarBinary, value: startLSN.toBinary() },