467 lines
12 KiB
Markdown
467 lines
12 KiB
Markdown
# c77_dep Usage Guide
|
|
|
|
This guide provides comprehensive information on using the c77_dep PostgreSQL extension for database dependency management.
|
|
|
|
## Table of Contents
|
|
1. [Getting Started](#getting-started)
|
|
2. [Core Views](#core-views)
|
|
3. [Analysis Views](#analysis-views)
|
|
4. [Analysis Functions](#analysis-functions)
|
|
5. [Common Workflows](#common-workflows)
|
|
6. [Use Cases](#use-cases)
|
|
7. [Performance Optimization](#performance-optimization)
|
|
8. [Integration with Laravel](#integration-with-laravel)
|
|
9. [Troubleshooting](#troubleshooting)
|
|
|
|
## Getting Started
|
|
|
|
After installation, the extension provides immediate access to dependency information through views and functions.
|
|
|
|
### Verifying Installation
|
|
|
|
```sql
|
|
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_dep';
|
|
```
|
|
|
|
### Initial Inspection
|
|
|
|
Get a quick overview of your database dependencies:
|
|
|
|
```sql
|
|
-- Summary of object types and their dependency characteristics
|
|
SELECT * FROM c77_dep_object_type_summary;
|
|
|
|
-- Top objects with many dependencies
|
|
SELECT * FROM c77_dep_hub_objects LIMIT 10;
|
|
```
|
|
|
|
## Core Views
|
|
|
|
### c77_dep_dependencies_map
|
|
|
|
The base view that maps dependencies between tables, views, and materialized views.
|
|
|
|
```sql
|
|
SELECT * FROM c77_dep_dependencies_map WHERE relation = 'schema.object_name';
|
|
```
|
|
|
|
Key columns:
|
|
- `relation`: Object name (schema.name)
|
|
- `object_type`: Type of database object (TABLE, VIEW, MATV)
|
|
- `deps`: Number of direct dependencies
|
|
- `add_deps`: Number of indirect dependencies
|
|
- `dependents`: List of objects that depend on this object
|
|
- `requirements`: List of objects this object depends on
|
|
|
|
### c77_dep_dependencies_map_with_foreign
|
|
|
|
Enhanced version that also includes foreign tables.
|
|
|
|
```sql
|
|
SELECT * FROM c77_dep_dependencies_map_with_foreign
|
|
WHERE object_type = 'FOREIGN TABLE';
|
|
```
|
|
|
|
## Analysis Views
|
|
|
|
### c77_dep_orphaned_objects
|
|
|
|
Displays objects with no dependencies.
|
|
|
|
```sql
|
|
-- Find all orphaned views
|
|
SELECT * FROM c77_dep_orphaned_objects
|
|
WHERE object_type = 'VIEW';
|
|
```
|
|
|
|
### c77_dep_schema_complexity
|
|
|
|
Provides metrics on schema complexity.
|
|
|
|
```sql
|
|
-- Identify the most complex schemas
|
|
SELECT * FROM c77_dep_schema_complexity
|
|
ORDER BY total_dependencies DESC;
|
|
```
|
|
|
|
### c77_dep_object_type_summary
|
|
|
|
Statistical summary of object types and their dependency characteristics.
|
|
|
|
```sql
|
|
-- See distribution of object types
|
|
SELECT * FROM c77_dep_object_type_summary;
|
|
```
|
|
|
|
### c77_dep_risk_assessment
|
|
|
|
Assesses risk of modifying database objects.
|
|
|
|
```sql
|
|
-- Find high-risk objects
|
|
SELECT * FROM c77_dep_risk_assessment
|
|
WHERE risk_level = 'HIGH';
|
|
```
|
|
|
|
### c77_dep_hub_objects
|
|
|
|
Lists objects with many dependencies (dependency hubs).
|
|
|
|
```sql
|
|
-- Find key dependency hubs
|
|
SELECT * FROM c77_dep_hub_objects;
|
|
```
|
|
|
|
### c77_dep_cleanup_candidates
|
|
|
|
Identifies objects that may be candidates for cleanup.
|
|
|
|
```sql
|
|
-- Find cleanup candidates
|
|
SELECT * FROM c77_dep_cleanup_candidates;
|
|
```
|
|
|
|
## Analysis Functions
|
|
|
|
### c77_dep_analyze_drop_impact
|
|
|
|
Analyzes the impact of dropping a specific object.
|
|
|
|
```sql
|
|
-- What would happen if we dropped this table?
|
|
SELECT * FROM c77_dep_analyze_drop_impact('myschema.mytable');
|
|
```
|
|
|
|
### c77_dep_detect_circular_dependencies
|
|
|
|
Identifies circular dependency relationships.
|
|
|
|
```sql
|
|
-- Find all circular dependencies
|
|
SELECT * FROM c77_dep_detect_circular_dependencies();
|
|
|
|
-- Find circular dependencies in a specific schema
|
|
SELECT * FROM c77_dep_detect_circular_dependencies()
|
|
WHERE object1 LIKE 'myschema.%';
|
|
```
|
|
|
|
### c77_dep_export_dependency_graph
|
|
|
|
Generates a DOT-format graph for visualization with Graphviz.
|
|
|
|
```sql
|
|
-- Export dependencies for a specific schema
|
|
SELECT c77_dep_export_dependency_graph('myschema');
|
|
```
|
|
|
|
Sample workflow for visualization:
|
|
1. Run the function and save output to a file (e.g., `dependencies.dot`)
|
|
2. Use Graphviz to create a visual graph:
|
|
```bash
|
|
dot -Tpng dependencies.dot -o dependencies.png
|
|
```
|
|
|
|
### c77_dep_simulate_schema_change
|
|
|
|
Simulates the impact of schema changes.
|
|
|
|
```sql
|
|
-- What would be affected by renaming this schema?
|
|
SELECT * FROM c77_dep_simulate_schema_change('old_schema', 'new_schema');
|
|
```
|
|
|
|
### c77_dep_generate_migration_order
|
|
|
|
Suggests a migration order based on dependencies.
|
|
|
|
```sql
|
|
-- Get a dependency-based migration plan
|
|
SELECT * FROM c77_dep_generate_migration_order();
|
|
```
|
|
|
|
### c77_dep_generate_report
|
|
|
|
Creates a comprehensive dependency analysis report.
|
|
|
|
```sql
|
|
-- Generate a full report
|
|
SELECT c77_dep_generate_report();
|
|
|
|
-- Generate a report for a specific schema
|
|
SELECT c77_dep_generate_report('myschema');
|
|
```
|
|
|
|
## Common Workflows
|
|
|
|
### Database Refactoring Planning
|
|
|
|
1. Generate an overview report:
|
|
```sql
|
|
SELECT c77_dep_generate_report();
|
|
```
|
|
|
|
2. Identify complex schemas for potential splitting:
|
|
```sql
|
|
SELECT * FROM c77_dep_schema_complexity
|
|
ORDER BY total_dependencies DESC LIMIT 5;
|
|
```
|
|
|
|
3. Find circular dependencies that need resolving:
|
|
```sql
|
|
SELECT * FROM c77_dep_detect_circular_dependencies();
|
|
```
|
|
|
|
4. Identify possible cleanup candidates:
|
|
```sql
|
|
SELECT * FROM c77_dep_cleanup_candidates;
|
|
```
|
|
|
|
### Schema Migration Planning
|
|
|
|
1. Determine migration order to preserve dependencies:
|
|
```sql
|
|
SELECT * FROM c77_dep_generate_migration_order();
|
|
```
|
|
|
|
2. For each phase, analyze specific object impacts:
|
|
```sql
|
|
SELECT * FROM c77_dep_analyze_drop_impact('schema.object');
|
|
```
|
|
|
|
3. Visualize the schema dependencies:
|
|
```sql
|
|
SELECT c77_dep_export_dependency_graph('schema_name');
|
|
```
|
|
|
|
## Use Cases
|
|
|
|
### Database Documentation
|
|
|
|
Generate detailed dependency documentation for your database:
|
|
|
|
```sql
|
|
-- Create comprehensive report
|
|
SELECT c77_dep_generate_report();
|
|
|
|
-- Export visualization
|
|
SELECT c77_dep_export_dependency_graph();
|
|
```
|
|
|
|
### Impact Analysis Before Changes
|
|
|
|
Before modifying a database object:
|
|
|
|
```sql
|
|
-- Check what would be affected
|
|
SELECT * FROM c77_dep_analyze_drop_impact('schema.object_name');
|
|
|
|
-- Assess the risk
|
|
SELECT * FROM c77_dep_risk_assessment
|
|
WHERE relation = 'schema.object_name';
|
|
```
|
|
|
|
### Clean-up Operations
|
|
|
|
Identify unused or problematic objects:
|
|
|
|
```sql
|
|
-- Find objects with no dependencies
|
|
SELECT * FROM c77_dep_orphaned_objects;
|
|
|
|
-- Find circular dependencies to resolve
|
|
SELECT * FROM c77_dep_detect_circular_dependencies();
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
For large databases, consider these performance tips:
|
|
|
|
1. **Schema-specific analysis**: Filter by schema instead of analyzing the entire database
|
|
```sql
|
|
SELECT * FROM c77_dep_schema_complexity WHERE schema_name = 'myschema';
|
|
```
|
|
|
|
2. **Targeted object analysis**: Focus on specific objects rather than complete scans
|
|
```sql
|
|
SELECT * FROM c77_dep_analyze_drop_impact('schema.object');
|
|
```
|
|
|
|
3. **Scheduled analysis**: Run comprehensive analysis during off-peak hours
|
|
|
|
4. **Progressive analysis**: Analyze one schema at a time if full database analysis is too intensive
|
|
|
|
## Integration with Laravel
|
|
|
|
Laravel applications can benefit from the c77_dep extension for database management, migrations, and monitoring.
|
|
|
|
### Setting Up Laravel with c77_dep
|
|
|
|
1. Ensure the extension is installed on your PostgreSQL database:
|
|
```sql
|
|
CREATE EXTENSION c77_dep;
|
|
```
|
|
|
|
2. Create a custom Artisan command to interact with c77_dep:
|
|
|
|
```php
|
|
<?php
|
|
// app/Console/Commands/AnalyzeDatabaseDependencies.php
|
|
|
|
namespace App\Console\Commands;
|
|
|
|
use Illuminate\Console\Command;
|
|
use Illuminate\Support\Facades\DB;
|
|
|
|
class AnalyzeDatabaseDependencies extends Command
|
|
{
|
|
protected $signature = 'db:analyze-dependencies {action} {--schema=} {--object=}';
|
|
protected $description = 'Analyze database dependencies using c77_dep extension';
|
|
|
|
public function handle()
|
|
{
|
|
$action = $this->argument('action');
|
|
$schema = $this->option('schema');
|
|
$object = $this->option('object');
|
|
|
|
switch ($action) {
|
|
case 'report':
|
|
$this->generateReport($schema);
|
|
break;
|
|
case 'orphaned':
|
|
$this->findOrphanedObjects($schema);
|
|
break;
|
|
case 'impact':
|
|
if (!$object) {
|
|
$this->error('Please specify an object with --object option');
|
|
return 1;
|
|
}
|
|
$this->analyzeImpact($object);
|
|
break;
|
|
case 'circular':
|
|
$this->findCircularDependencies($schema);
|
|
break;
|
|
default:
|
|
$this->error('Unknown action. Available actions: report, orphaned, impact, circular');
|
|
return 1;
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
|
|
protected function generateReport($schema = null)
|
|
{
|
|
$sql = "SELECT c77_dep_generate_report(" . ($schema ? "'$schema'" : "NULL") . ")";
|
|
$report = DB::select($sql)[0]->c77_dep_generate_report;
|
|
$this->line($report);
|
|
}
|
|
|
|
protected function findOrphanedObjects($schema = null)
|
|
{
|
|
$sql = "SELECT * FROM c77_dep_orphaned_objects";
|
|
if ($schema) {
|
|
$sql .= " WHERE relation LIKE '$schema.%'";
|
|
}
|
|
$results = DB::select($sql);
|
|
$this->table(['Relation', 'Object Type', 'Owner'], collect($results)->map(function ($item) {
|
|
return (array) $item;
|
|
}));
|
|
}
|
|
|
|
protected function analyzeImpact($object)
|
|
{
|
|
$sql = "SELECT * FROM c77_dep_analyze_drop_impact('$object')";
|
|
$results = DB::select($sql);
|
|
$this->table(['Affected Object', 'Object Type', 'Impact Level', 'Dependency Path'], collect($results)->map(function ($item) {
|
|
return (array) $item;
|
|
}));
|
|
}
|
|
|
|
protected function findCircularDependencies($schema = null)
|
|
{
|
|
$sql = "SELECT * FROM c77_dep_detect_circular_dependencies()";
|
|
if ($schema) {
|
|
$sql .= " WHERE object1 LIKE '$schema.%'";
|
|
}
|
|
$results = DB::select($sql);
|
|
$this->table(['Object 1', 'Object 2', 'Dependency Type'], collect($results)->map(function ($item) {
|
|
return (array) $item;
|
|
}));
|
|
}
|
|
}
|
|
```
|
|
|
|
3. Register the command in `app/Console/Kernel.php`:
|
|
|
|
```php
|
|
protected $commands = [
|
|
// ...
|
|
\App\Console\Commands\AnalyzeDatabaseDependencies::class,
|
|
];
|
|
```
|
|
|
|
### Using with Laravel Migrations
|
|
|
|
1. Use dependency information to plan migrations:
|
|
|
|
```bash
|
|
php artisan db:analyze-dependencies report
|
|
```
|
|
|
|
2. Check for circular dependencies before creating migrations:
|
|
|
|
```bash
|
|
php artisan db:analyze-dependencies circular
|
|
```
|
|
|
|
3. Analyze impact before modifying a table:
|
|
|
|
```bash
|
|
php artisan db:analyze-dependencies impact --object=schema.table_name
|
|
```
|
|
|
|
### Incorporating into Laravel Projects
|
|
|
|
1. **Schema Changes Review**: Before implementing schema changes, analyze dependencies
|
|
|
|
2. **Migration Automation**: Use dependency information to generate migrations in the correct order
|
|
|
|
3. **Database Documentation**: Generate dependency reports as part of your application documentation
|
|
|
|
4. **CI/CD Integration**: Include dependency checks in your continuous integration pipeline:
|
|
|
|
```yaml
|
|
# In your CI/CD pipeline configuration
|
|
database-dependency-check:
|
|
stage: test
|
|
script:
|
|
- php artisan db:analyze-dependencies circular
|
|
- php artisan db:analyze-dependencies orphaned
|
|
only:
|
|
changes:
|
|
- database/migrations/*
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Performance Problems**:
|
|
- Limit analysis to specific schemas
|
|
- Use targeted functions instead of full database analysis
|
|
- Run during off-peak hours
|
|
|
|
2. **Incomplete Results**:
|
|
- Some logical dependencies might not be captured
|
|
- Check permission issues if certain objects are missing
|
|
|
|
3. **Missing Dependencies**:
|
|
- Certain dynamic dependencies created through SQL in functions might not be detected
|
|
- Dependencies created through dynamic SQL might not be visible
|
|
|
|
### Getting Help
|
|
|
|
For additional help, consult:
|
|
- PostgreSQL documentation on system catalogs
|
|
- Extension README.md file
|
|
- GitHub repository issues (if available)
|
|
- PostgreSQL community forums |