DatabaseSchemaReaderModule Migration Guide

Overview

DatabaseSchemaReaderModule is a retired compatibility shell. Version 1.0 accepted a caller-controlled JDBC URL plus plaintext username and password, loaded any driver-supported destination from the workflow worker, and returned database catalogs, schemas, tables, columns, keys, indexes, default values, and remarks without provider, row, table, response-size, or destination bounds. Provider exceptions could also expose connection details.

Version 2.0 keeps the Java class and Spring bean loadable so saved workflows can be inspected and migrated, but hides the module from new Workflow Studio catalogs. Execution now fails closed with MODULE_RETIRED, performs no credential, driver, DNS, socket, database, or metadata operation, and returns governed provider-specific migration targets.

Usage

1. Find saved tasks whose module type is DatabaseSchemaReaderModule.
2. Remove legacy jdbc_url, username, and password values. Rotate credentials if version 1.0 could have executed them from an untrusted workflow.
3. Identify the actual provider and required read-only metadata operation.
4. Replace the task with a governed provider-specific module such as SnowflakeModule, GoogleBigQueryModule, or MongoDBModule when that connector supports the required operation.
5. Bind a least-privilege IntegrationAccount in exact READY state. Do not copy raw credentials or provider endpoints into module data.
6. Select the smallest provider operation and bounded result limit. Review the returned metadata classification before sending it to another module.

Inputs

The compatibility shell accepts legacy fields only so their names remain visible during migration. It ignores every value.

Input	Type	Active behavior
jdbc_url	string	Ignored; never parsed, resolved, or contacted.
username	string	Ignored; never used or emitted.
password	string	Ignored; never used or emitted.
mode	string	Ignored; tables, columns, keys, and all are no longer executed.
schema_name	string	Ignored; no schema pattern is queried.
table_pattern	string	Ignored; no table pattern is queried.

Replacement inputs depend on the provider. Use fixed provider destinations, allowlisted operations and identifiers, and explicit page or row bounds.

Outputs

The retired module always returns:

Output	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, retryable:false, migration targets, and required action.

It never returns catalogs, table names, columns, keys, indexes, default values, remarks, connection properties, credentials, JDBC errors, or driver messages.

IntegrationAccount Requirements

DatabaseSchemaReaderModule never resolves an IntegrationAccount; no account can re-enable it.

For the replacement:

• bind a provider-specific account in exact READY state;
• use read-only metadata or query permissions scoped to the required database and schemas;
• keep credentials in IntegrationAccount SecureFields;
• fix the provider destination in the connector rather than accepting a workflow-controlled JDBC URL;
• separate metadata discovery from mutation privileges whenever the provider permits it.

Configuration

The retired module has no active configuration. Saved JDBC URLs, usernames, passwords, modes, schema names, and table patterns are ignored.

A governed replacement configuration resembles:

{
  "operation": "list_tables",
  "database": "ANALYTICS",
  "schema": "PUBLIC",
  "maxRows": 100
}

The exact fields vary by provider. Bind the account through the module's integrationAccount configuration field and use the repository's canonical provider guide.

Operations

DatabaseSchemaReaderModule supports one compatibility operation: reject execution and identify migration targets. It does not load a JDBC driver, connect, authenticate, enumerate metadata, retry, paginate, cache, or mutate data.

Provider-specific replacements expose only their documented allowlisted operations. For example, SnowflakeModule supports bounded list_databases, list_schemas, list_tables, and describe_table operations through the fixed Snowflake SQL API destination.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace the task; retries cannot restore JDBC access.
Saved raw credential	The value is ignored and not emitted.	Remove it and rotate it if prior execution is uncertain.
Unknown database provider	No generic JDBC fallback is attempted.	Add or harden a provider-specific connector with IntegrationAccount support.
Replacement account is not READY	Provider module fails before connecting.	Repair or reauthorize the account.
Replacement metadata response is too large	Provider module must fail at its documented bound.	Narrow database, schema, table, page, or row filters.
Provider response is ambiguous	Do not assume success or replay blindly.	Reconcile the provider request or statement receipt first.

Example

A saved legacy task reaches the compatibility shell:

{
  "jdbc_url": "jdbc:postgresql://db.internal/app",
  "username": "workflow_reader",
  "password": "redacted",
  "mode": "all",
  "table_pattern": "%"
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "DatabaseSchemaReaderModule is retired; use an approved provider-specific database module",
    "retryable": false,
    "migrationTargets": [
      "SnowflakeModule",
      "GoogleBigQueryModule",
      "MongoDBModule"
    ]
  }
}

Notes

• Pagination: the compatibility shell never paginates because it performs no read. Configure provider pagination or row bounds explicitly on the replacement.
• Limits: the shell returns a two-field response immediately and never materializes metadata collections.
• Idempotency: the retired response is deterministic and side-effect free. Version 1.0's read-only label did not make arbitrary credential use or destination access safe.
• API constraints: generic JDBC destinations are no longer accepted. Each replacement must fix or strictly derive the provider origin and disable redirects or driver-specific escape paths.
• Destructive behavior: the shell cannot run SQL or mutate data. Choose a read-only replacement operation; mutation-capable connectors require their own confirmations and idempotency controls.
• Sensitive metadata: schemas can reveal tenant structure, security controls, business entities, and secret-bearing column names. Treat replacement output as internal unless a stricter classification applies.
• Runtime deployment: source, tests, and documentation can be merged and published independently, but live Workflow Studio continues to show version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, secret non-disclosure, repeatability, discovery exclusion, and direct compatibility lookup. No live database test is needed because the retired module intentionally performs no provider behavior.