Troubleshooting Common Issues in Embarcadero DB Change ManagerEmbarcadero DB Change Manager is a powerful tool for managing database schema changes, versioning, and deployments. Like any sophisticated tool that touches production databases, it can encounter problems ranging from configuration issues to deployment failures. This article walks through common problems, diagnostic steps, and practical fixes to get your DB Change Manager workflows back on track.
1. Installation and Licensing Problems
Symptoms
- Installation fails or hangs.
- The application opens but features are disabled.
- Licensing errors or “license not found” messages.
Checks and fixes
- Verify system requirements: ensure supported Windows version, .NET framework (if required), and sufficient disk space.
- Run the installer as Administrator. Right-click the installer and choose “Run as administrator.”
- Check antivirus or endpoint protection: temporarily disable or add an exclusion for the installer and DB Change Manager program files.
- Licensing: confirm your license key, check expiration, and ensure the machine can reach the Embarcadero licensing server (if online activation is required). If using a license server, confirm network connectivity and that the license server service is running.
- Logs: review installer logs and the application logs (usually in ProgramData or AppData) for specific error codes and messages; search Embarcadero support for those codes.
2. Connection Failures to Target Databases
Symptoms
- “Unable to connect” errors when testing or executing change deployments.
- Timeouts, authentication errors, or network-related exceptions.
Checks and fixes
- Validate connection parameters: host, port, database name, username, and password. Test the same credentials using a database client (SQL*Plus, SQL Server Management Studio, pgAdmin, etc.).
- Network and firewall: ensure the DB server accepts inbound connections on the configured port and that there are no network routes or VPN restrictions blocking access.
- Drivers and providers: confirm the correct database client libraries or ODBC/JDBC drivers are installed and supported by DB Change Manager. Update drivers to compatible versions if necessary.
- Authentication method: check whether the database requires Windows/Integrated authentication, Kerberos, or other mechanisms; configure DB Change Manager accordingly.
- TLS/SSL: if the database requires encrypted connections, ensure certificates are trusted on the machine running DB Change Manager and that encryption settings match.
- Connection pooling/timeouts: increase timeouts for slow networks or large initial queries; clear or adjust pooling settings if persistent connections fail.
3. Schema Comparison Produces Unexpected Differences
Symptoms
- Schema comparison shows differences you didn’t expect (e.g., permissions, default values, or ordering differences).
- Frequent false positives on repeated comparisons.
Checks and fixes
- Comparison options: review and adjust comparison settings (ignore whitespace, ignore object owner/schema, ignore comments, or specific object types such as permissions or statistics).
- Snapshot timing: ensure both source and target snapshots were taken at comparable times; schema changes during snapshotting can produce spurious diffs.
- Collation/locale and case sensitivity: differences in database collation or case-sensitivity settings can surface as differences—normalize comparison rules or convert names to a common case when comparing.
- Filter objects: use object filters to exclude volatile or irrelevant objects (like statistics or specific system tables) from comparisons.
- Normalize defaults and computed columns: DB Change Manager may treat functionally equivalent defaults differently; manually inspect DDL and adjust comparison settings if available.
4. Change Script Generation Problems
Symptoms
- Generated deployment script fails when executed.
- Script misses dependent objects or executes in wrong order.
- Script contains vendor-specific syntax not supported on the target.
Checks and fixes
- Preview SQL: always preview generated SQL and run it in a development database before deploying to production.
- Dependency ordering: ensure DB Change Manager’s object dependency detection is enabled; for complex dependencies, break into multiple migration steps or hand-edit the script to enforce order.
- Vendor/version compatibility: confirm the target database version and SQL dialect; adjust generation settings or use manual edits for version-specific syntax.
- Transaction boundaries: if the script is large or contains operations that cannot run inside a single transaction (e.g., certain DDL in some DB engines), split the script or configure transactional behavior appropriately.
- Test rollback: ensure there is a tested rollback path—either generated undo scripts or a tested database backup/restore strategy.
5. Deployment Failures and Partial Deployments
Symptoms
- Deployment stops midway due to an error, leaving schema in an inconsistent state.
- No clear rollback or undo available.
Checks and fixes
- Transactional execution: configure DB Change Manager to run scripts inside transactions where possible. Note some DDL operations are auto-committed by the database and cannot be rolled back.
- Pre-deployment validation: enable checks for object existence, permissions, or preconditions before executing changes.
- Backups and restore plan: always take a full backup or snapshot of the target database before applying schema changes. Test restore procedures regularly.
- Idempotent scripts: prefer scripts that can be re-run safely (check for existence and only create when absent).
- Error handling and logging: enable verbose logging and capture error messages and line numbers. If a partial deployment occurs, use logs to identify which changes applied and reverse them manually or with a restore.
- Staged deployment: for large or risky changes, deploy in smaller stages (e.g., add new columns with nullability, backfill data, then switch applications).
6. Permission and Access Errors During Deployment
Symptoms
- “Insufficient privileges” or permission-denied errors when executing migration steps.
Checks and fixes
- Account privileges: use a database account with the required DDL/DCL privileges to perform schema changes. Avoid deploying with overly privileged accounts in production unless necessary.
- Separate roles: use a dedicated deployment role with only needed permissions for safer operations and easier auditing.
- Ownership and schema: ensure the account’s default schema and object ownership expectations align with the deployment scripts.
- Grant statements: include explicit GRANT statements in scripts where necessary rather than relying on implicit inheritance.
7. Performance Issues and Timeouts
Symptoms
- Long-running comparisons or deployments; timeouts during operations.
Checks and fixes
- Resource bottlenecks: check CPU, memory, and disk I/O on the machine running DB Change Manager and the database server. Large schemas or massive object counts increase comparison time.
- Use snapshots: work from saved schema snapshots rather than live comparisons when performance or stability is a concern.
- Filter and limit: compare only necessary schemas or object types; exclude large numbers of irrelevant objects.
- Increase timeouts: configure longer timeouts for operations performed over slow networks.
- Run during maintenance windows: schedule heavy comparisons and deployments during off-peak hours.
8. Integration with CI/CD and Automation Failures
Symptoms
- Automated pipelines fail when invoking DB Change Manager tasks.
- Environment differences cause unpredictable results.
Checks and fixes
- Command-line options: ensure you’re using supported CLI commands and that CI agents have the necessary environment (drivers, credentials, network).
- Environment parity: match database client libraries, DB Change Manager versions, and configuration between CI agents and local/dev environments.
- Secrets management: store DB credentials securely (secret managers, CI built-in secrets) and avoid hardcoding in scripts.
- Idempotency and locking: prevent parallel runs against the same database (use locks or coordination), and make scripts idempotent to allow safe re-runs.
- Exit codes and logging: ensure CI checks exit codes and captures logs for debugging.
9. Incorrect or Missing Object Mappings
Symptoms
- Objects map to wrong schemas or names after deployment.
- Cross-database or cross-schema references break.
Checks and fixes
- Mapping configuration: review object mapping settings—ensure source-to-target schema mappings are correct.
- Namespace and owner normalization: align naming conventions and ownership expectations between environments.
- Cross-reference resolution: ensure DB Change Manager is configured to handle cross-schema dependencies and that the target environment has necessary synonyms, links, or qualified names.
10. Unexpected Data Loss or Corruption
Symptoms
- Data missing after deployment or data types truncated/modified.
Checks and fixes
- Backups first: always take backups prior to schema changes.
- Data-type changes: review scripts that alter column data types—ensure safe conversions or add migration steps to copy and transform data safely.
- Nullable and default changes: when changing nullability or defaults, explicitly handle existing rows (UPDATE, backfill) to avoid unintended nulls or constraint violations.
- Validate post-deployment: run integrity checks and sample queries to confirm data correctness after applying changes.
11. Logging, Diagnostics, and Support
Best practices
- Enable verbose logging for troubleshooting and collect logs from DB Change Manager and database server.
- Use saved snapshots and sample DDL to reproduce issues in a non-production environment.
- Keep DB Change Manager and database client drivers up to date with supported versions.
- Reach out to Embarcadero support with detailed logs, screenshots, environment details (versions, OS, DB engines), and reproduction steps.
Example Troubleshooting Workflow (Concise)
- Reproduce the issue in a development environment using the same inputs.
- Increase logging and save the deployment/compare output.
- Verify credentials, drivers, and network connectivity.
- Inspect generated SQL; run it manually to observe database errors.
- Adjust comparison/generation options or split the script into smaller steps.
- Backup target, test corrected script in staging, then redeploy during maintenance.
Troubleshooting DB Change Manager involves systematic checks across configuration, connectivity, permissions, and script generation. With good backups, careful previewing, and staged deployments, most problems can be prevented or safely resolved.
Leave a Reply