Diagnostic Command

Use TDK’s built-in diagnostic tools to quickly identify and resolve issues.

Overview

The diagnostic command checks:

  • Database connectivity

  • Configuration validity

  • Schema access

  • Foreign key relationships

  • Performance metrics

Running Diagnostics

CLI Mode

tdk diagnostic \
  --config-file workflow.yaml \
  --inventory-file inventory.yaml

Specific Checks

# Check database connection only
tdk diagnostic --check-connection

# Check configuration validity
tdk diagnostic --check-config

# Check schema metadata
tdk diagnostic --check-schema

# Run all checks
tdk diagnostic --check-all

Diagnostic Output

Successful Output

✓ Database connection: OK
✓ Configuration valid: OK
✓ Schema accessible: 15 tables found
✓ Foreign keys: 23 relationships detected
✓ Permissions: READ/WRITE access confirmed

Summary: All checks passed

Error Output

✗ Database connection: FAILED
  Error: Connection refused (Connection refused)
  Solution: Verify database is running and accessible

✓ Configuration valid: OK

⚠ Schema accessible: WARNING
  Warning: 3 tables not accessible
  Tables: private.secrets, admin.config, internal.logs
  Solution: Grant SELECT permission or exclude from workflow

✓ Foreign keys: 20 relationships detected

Summary: 1 error, 1 warning

Connection Check Details

tdk diagnostic --check-connection --verbose

Output:

Testing connection to: jdbc:postgresql://localhost:5432/mydb
  Hostname resolution: ✓ localhost → 127.0.0.1
  Port accessibility: ✓ Port 5432 is open
  JDBC driver: ✓ org.postgresql.Driver loaded
  Authentication: ✓ Credentials accepted
  Database access: ✓ Can query system tables
  Connection time: 234ms

Result: Connection successful

Schema Check

tdk diagnostic --check-schema

Output:

Discovered tables: 15
  public.customers (10 columns, 50000 rows)
  public.orders (8 columns, 150000 rows)
  public.products (6 columns, 500 rows)
  ...

Foreign keys: 23
  orders.customer_id → customers.id
  order_items.order_id → orders.id
  order_items.product_id → products.id
  ...

Indexes: 45
  Primary keys: 15
  Foreign key indexes: 23
  Additional indexes: 7

Result: Schema analysis complete

Configuration Check

tdk diagnostic --check-config --config-file workflow.yaml

Output:

✓ YAML syntax: Valid
✓ Mode specified: MASKING
✓ Table patterns: 3 patterns defined
✓ Transformations: 12 transformations configured
✓ No circular dependencies detected

Warnings:
  ⚠ Table pattern "public.audit_*" matches no tables

Result: Configuration valid with 1 warning

Performance Check

tdk diagnostic --check-performance

Output:

Testing read performance...
  Rows read: 10000 in 2.1s (4762 rows/sec)

Testing write performance...
  Rows written: 10000 in 3.5s (2857 rows/sec)

Memory usage:
  Current: 512 MB
  Max: 2048 MB
  Available: 1536 MB

Result: Performance is acceptable

Troubleshooting with Diagnostics

Connection Issues

tdk diagnostic --check-connection 2>&1 | tee connection-test.log

Review connection-test.log for detailed error messages.

Permission Issues

tdk diagnostic --check-schema --verbose

Look for "Permission denied" or "Access denied" messages.

See Also