@powersync/service-module-mssql 0.0.0-dev-20260803144812 → 0.0.0-dev-20260929095716

package/src/replication/MSSQLTableReconciliationContext.ts

@@ -0,0 +1,29 @@
+import type { SourceEntityDescriptor } from '@powersync/service-core';
+import type { CaptureInstance } from '../common/CaptureInstance.js';
+
+export enum MSSQLTableReconciliationState {
+  TABLE_MISSING = 'table_missing',
+  CDC_DISABLED = 'cdc_disabled',
+  READY = 'ready'
+}
+
+interface BaseMSSQLTableReconciliationContext {
+  source: SourceEntityDescriptor;
+}
+
+export type MSSQLUnavailableTableReconciliationContext =
+  | (BaseMSSQLTableReconciliationContext & {
+      state: MSSQLTableReconciliationState.TABLE_MISSING;
+    })
+  | (BaseMSSQLTableReconciliationContext & {
+      state: MSSQLTableReconciliationState.CDC_DISABLED;
+    });
+
+export type MSSQLReadyTableReconciliationContext = BaseMSSQLTableReconciliationContext & {
+  state: MSSQLTableReconciliationState.READY;
+  captureInstances: readonly CaptureInstance[];
+};
+
+export type MSSQLTableReconciliationContext =
+  | MSSQLUnavailableTableReconciliationContext
+  | MSSQLReadyTableReconciliationContext;

package/src/replication/SchemaChange.ts

@@ -0,0 +1,79 @@
+import { CaptureInstance } from '../common/CaptureInstance.js';
+import { MSSQLSourceTable } from '../common/MSSQLSourceTable.js';
+import { SourceTableChangeRef } from '../utils/schema.js';
+
+/**
+ * Schema changes are detected to warn or error on, not applied automatically. Polling cannot be
+ * made atomic with a commit, so the replicated schema stays fixed until the next deploy.
+ *
+ * Drops and renames fail the job because they have no known LSN. Continuing could skip unread
+ * changes. Existing replicated data is kept for the next deploy to clean up.
+ */
+export enum SchemaChangeType {
+  /**
+   * A replicated table was renamed.
+   */
+  TABLE_RENAME = 'table_rename',
+  /**
+   * A replicated table was dropped.
+   */
+  TABLE_DROP = 'table_drop',
+  /**
+   * The source columns changed. The pinned capture schema remains active.
+   */
+  TABLE_COLUMN_CHANGES = 'table_column_changes',
+  /**
+   * A newer capture instance exists, but the pinned one is still available.
+   */
+  NEW_CAPTURE_INSTANCE = 'new_capture_instance',
+  /**
+   * The pinned capture instance is no longer available.
+   */
+  MISSING_CAPTURE_INSTANCE = 'missing_capture_instance'
+}
+
+interface SchemaChangeBase<Type extends SchemaChangeType> {
+  type: Type;
+  /**
+   * The replicated table the change applies to.
+   */
+  table: MSSQLSourceTable;
+}
+
+export interface TableRenameChange extends SchemaChangeBase<SchemaChangeType.TABLE_RENAME> {
+  /**
+   * The name the table was renamed to. Only used in the error reported for the rename.
+   */
+  newTable: SourceTableChangeRef;
+}
+
+export type TableDropChange = SchemaChangeBase<SchemaChangeType.TABLE_DROP>;
+
+export interface TableColumnChanges extends SchemaChangeBase<SchemaChangeType.TABLE_COLUMN_CHANGES> {
+  /**
+   * The pinned capture instance the drift was observed against.
+   */
+  captureInstance: CaptureInstance;
+}
+
+export interface NewCaptureInstanceChange extends SchemaChangeBase<SchemaChangeType.NEW_CAPTURE_INSTANCE> {
+  /**
+   * The newer instance that is available but will not be adopted by this stream.
+   */
+  newCaptureInstance: CaptureInstance;
+}
+
+export interface MissingCaptureInstanceChange extends SchemaChangeBase<SchemaChangeType.MISSING_CAPTURE_INSTANCE> {
+  /**
+   * A newer instance that replaced the pinned one, if CDC is still enabled for the table. Only used
+   * to report the right recovery step.
+   */
+  replacementInstance?: CaptureInstance;
+}
+
+export type SchemaChange =
+  | TableRenameChange
+  | TableDropChange
+  | TableColumnChanges
+  | NewCaptureInstanceChange
+  | MissingCaptureInstanceChange;

package/src/types/types.ts

@@ -8,6 +8,10 @@ export const DEFAULT_POLLING_BATCH_SIZE = 10;
 export const DEFAULT_POLLING_INTERVAL_MS = 1000;
 export const MSSQL_CONNECTION_TYPE = 'mssql' as const;
 
+const DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 60;
+const MIN_HEARTBEAT_INTERVAL_SECONDS = 5;
+const MAX_HEARTBEAT_INTERVAL_SECONDS = 60;
+
 export const AzureActiveDirectoryServicePrincipalSecret = t.object({
   type: t.literal('azure-active-directory-service-principal-secret'),
   options: t.object({
@@ -89,11 +93,19 @@ export interface NormalizedMSSQLConnectionConfig {
   database: string;
   schema?: string;
 
+  /** PEM-encoded certificate authority used to validate the SQL Server certificate. */
+  cacert?: string;
+
+  /** Server name to use when validating the SQL Server certificate. */
+  tls_servername?: string;
+
   authentication?: Authentication;
 
   lookup?: LookupFunction;
 
   additionalConfig: AdditionalConfig;
+
+  heartbeat_interval_seconds: number;
 }
 
 export const MSSQLConnectionConfig = service_types.configFile.DataSourceConfig.and(
@@ -107,10 +119,20 @@ export const MSSQLConnectionConfig = service_types.configFile.DataSourceConfig.a
     hostname: t.string.optional(),
     port: service_types.configFile.portCodec.optional(),
 
+    /** PEM-encoded certificate authority used to validate the SQL Server certificate. */
+    cacert: t.string.optional(),
+
+    /** Server name to use when validating the SQL Server certificate. */
+    tls_servername: t.string.optional(),
+
     authentication: Authentication.optional(),
 
     reject_ip_ranges: t.array(t.string).optional(),
-    additionalConfig: AdditionalConfig.optional()
+    additionalConfig: AdditionalConfig.optional(),
+    /**
+     * Interval in seconds between source connection heartbeats. Null or omitted uses the default.
+     */
+    heartbeat_interval_seconds: service_types.orNull(t.number).optional()
   })
 );
 
@@ -169,6 +191,13 @@ export function normalizeConnectionConfig(options: MSSQLConnectionConfig): Norma
     throw new ServiceError(ErrorCode.PSYNC_S1105, `MSSQL connection: database required`);
   }
 
+  if (options.cacert && options.additionalConfig?.trustServerCertificate) {
+    throw new ServiceError(
+      ErrorCode.PSYNC_S1604,
+      'MSSQL connection: cacert cannot be used with trustServerCertificate because certificate validation would be disabled'
+    );
+  }
+
   const lookup = makeHostnameLookupFunction(hostname, { reject_ip_ranges: options.reject_ip_ranges ?? [] });
 
   return {
@@ -180,6 +209,8 @@ export function normalizeConnectionConfig(options: MSSQLConnectionConfig): Norma
     hostname,
     port,
     database,
+    cacert: options.cacert,
+    tls_servername: options.tls_servername,
 
     lookup,
     authentication: options.authentication,
@@ -188,10 +219,24 @@ export function normalizeConnectionConfig(options: MSSQLConnectionConfig): Norma
       pollingIntervalMs: options.additionalConfig?.pollingIntervalMs ?? DEFAULT_POLLING_INTERVAL_MS,
       pollingBatchSize: options.additionalConfig?.pollingBatchSize ?? DEFAULT_POLLING_BATCH_SIZE,
       trustServerCertificate: options.additionalConfig?.trustServerCertificate ?? false
-    }
+    },
+    heartbeat_interval_seconds: normalizeHeartbeatInterval(options.heartbeat_interval_seconds)
   } satisfies NormalizedMSSQLConnectionConfig;
 }
 
+function normalizeHeartbeatInterval(value: number | null | undefined): number {
+  if (value == null) {
+    return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
+  }
+  if (!Number.isFinite(value) || value < MIN_HEARTBEAT_INTERVAL_SECONDS || value > MAX_HEARTBEAT_INTERVAL_SECONDS) {
+    throw new ServiceError(
+      ErrorCode.PSYNC_S1109,
+      `MSSQL connection: heartbeat_interval_seconds must be between ${MIN_HEARTBEAT_INTERVAL_SECONDS} and ${MAX_HEARTBEAT_INTERVAL_SECONDS} seconds`
+    );
+  }
+  return value;
+}
+
 export function baseUri(config: ResolvedMSSQLConnectionConfig) {
   return `mssql://${config.hostname}:${config.port}/${config.database}`;
 }

package/src/utils/mssql.ts

@@ -351,7 +351,7 @@ export async function getDebugTableInfo(options: GetDebugTableInfoOptions): Prom
     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.
+        message: `Source table ${toQualifiedTableName(schema, table.name)} has schema changes not reflected in the CDC capture instance. Create a replacement CDC capture instance with the intended columns, update the sync config if needed, and deploy a new sync config. If the change requires disabling CDC, re-enable CDC before deploying.
         Pending schema changes: ${captureInstanceDetails.instances[0].pendingSchemaChanges.join(', \n')}`
       };
     }

package/src/utils/schema.ts

@@ -139,77 +139,76 @@ export async function getReplicationIdentityColumns(
 }
 
 export interface SourceTableChangeRef {
-  objectId: number | string | undefined;
+  /**
+   * `sys.tables.object_id`, which SQL Server always reports as an int. Narrower than
+   * `SourceEntityDescriptor.objectId`, which has to accommodate other source databases.
+   */
+  objectId: number;
   schema: string;
   name: string;
 }
 
 export type ResolvedTable = SourceTableChangeRef;
 
+export const SCHEMA_WILDCARD_MESSAGE =
+  'Schema wildcards ("%") in table patterns are not supported for SQL Server connections.';
+
+/**
+ * Wildcards would allow the replicated table set to change between polls, so they are rejected.
+ */
+export function tableWildcardMessage(tablePattern: TablePattern): string {
+  return (
+    `Table wildcards ("%") are not supported for SQL Server connections: "${tablePattern.tablePattern}". ` +
+    `List each table explicitly.`
+  );
+}
+
+/**
+ * Returns the reason this pattern cannot be replicated, or null if it is supported.
+ */
+export function unsupportedTablePatternMessage(tablePattern: TablePattern): string | null {
+  if (tablePattern.isSchemaWildcard) {
+    return SCHEMA_WILDCARD_MESSAGE;
+  }
+  if (tablePattern.isWildcard) {
+    return tableWildcardMessage(tablePattern);
+  }
+  return null;
+}
+
 export async function getTablesFromPattern(
   connectionManager: MSSQLConnectionManager,
   tablePattern: TablePattern
 ): Promise<ResolvedTable[]> {
-  if (tablePattern.isSchemaWildcard) {
-    throw new ServiceError(
-      ErrorCode.PSYNC_R2201,
-      'Schema wildcards ("%") in table patterns are not supported for SQL Server connections.'
-    );
+  const unsupported = unsupportedTablePatternMessage(tablePattern);
+  if (unsupported != null) {
+    throw new ServiceError(ErrorCode.PSYNC_R2201, unsupported);
   }
 
-  if (tablePattern.isWildcard) {
-    const { recordset: tableResults } = await connectionManager.query(
-      `
-        SELECT
-          tbl.name      AS [table],
-          sch.name      AS [schema],
-          tbl.object_id AS object_id
-        FROM sys.tables tbl
-          JOIN sys.schemas sch ON tbl.schema_id = sch.schema_id
+  const { recordset: tableResults } = await connectionManager.query(
+    `
+      SELECT
+        tbl.name      AS [table],
+        sch.name      AS [schema],
+        tbl.object_id AS object_id
+      FROM sys.tables tbl
+        JOIN sys.schemas sch ON tbl.schema_id = sch.schema_id
         WHERE sch.name = @schema
-          AND tbl.name LIKE @tablePattern
-      `,
-      [
-        { name: 'schema', type: sql.VarChar(sql.MAX), value: tablePattern.schema },
-        { name: 'tablePattern', type: sql.VarChar(sql.MAX), value: tablePattern.tablePattern }
-      ]
-    );
-
-    return tableResults
-      .map((row) => {
-        return {
-          objectId: row.object_id,
-          schema: row.schema,
-          name: row.table
-        };
-      })
-      .filter((table: ResolvedTable) => table.name.startsWith(tablePattern.tablePrefix));
-  } else {
-    const { recordset: tableResults } = await connectionManager.query(
-      `
-        SELECT
-          tbl.name      AS [table],
-          sch.name      AS [schema],
-          tbl.object_id AS object_id
-        FROM sys.tables tbl
-          JOIN sys.schemas sch ON tbl.schema_id = sch.schema_id
-          WHERE sch.name = @schema
-          AND tbl.name = @tablePattern
-      `,
-      [
-        { name: 'schema', type: sql.VarChar(sql.MAX), value: tablePattern.schema },
-        { name: 'tablePattern', type: sql.VarChar(sql.MAX), value: tablePattern.tablePattern }
-      ]
-    );
-
-    return tableResults.map((row) => {
-      return {
-        objectId: row.object_id,
-        schema: row.schema,
-        name: row.table
-      };
-    });
-  }
+        AND tbl.name = @tablePattern
+    `,
+    [
+      { name: 'schema', type: sql.VarChar(sql.MAX), value: tablePattern.schema },
+      { name: 'tablePattern', type: sql.VarChar(sql.MAX), value: tablePattern.tablePattern }
+    ]
+  );
+
+  return tableResults.map((row) => {
+    return {
+      objectId: row.object_id,
+      schema: row.schema,
+      name: row.table
+    };
+  });
 }
 
 export interface GetPendingSchemaChangesOptions {