dbdiagram.io Integration

One of the most powerful features of nself's database management is its seamless integration with dbdiagram.io, a popular visual database design tool. This integration enables a complete visual-to-code workflow, allowing you to design your database schema visually and synchronize it with your nself project.

What is dbdiagram.io?

dbdiagram.io is a free, simple tool to draw entity-relationship (ER) diagrams by just writing code. Created by Holistics (the same team behind DBML), it provides:

  • Visual database design with drag-and-drop interface
  • Real-time collaboration for team design sessions
  • Export capabilities to multiple formats
  • Public and private diagrams for sharing
  • Integration with popular databases and ORMs

Integration Benefits

The nself + dbdiagram.io integration provides:

Visual Design Workflow

  • Design your database schema visually using dbdiagram.io's intuitive interface
  • See relationships and structure at a glance
  • Collaborate with team members in real-time
  • Export diagrams for documentation

Bidirectional Sync

  • Import from dbdiagram.io: Pull your visual design into your nself project
  • Export to dbdiagram.io: Share your DBML schema visually
  • Continuous sync: Keep your visual design and code in sync

Getting Started

Create a dbdiagram.io Account

  1. Visit dbdiagram.io
  2. Sign up for a free account
  3. Create a new diagram

Import Existing Schema

Import your current nself schema into dbdiagram.io:

# Export your schema to dbdiagram.io format
nself db export --format dbdiagram

# Copy the output and paste it into dbdiagram.io

Sync from dbdiagram.io

Pull changes from your dbdiagram.io design:

# Sync from dbdiagram.io URL
nself db sync --from https://dbdiagram.io/d/your-diagram-id

# Or sync from exported DBML file
nself db sync --from schema.dbml

Workflow Examples

Team Collaboration Workflow

  1. Initial Design: Create your schema visually in dbdiagram.io
  2. Team Review: Share the diagram for team feedback
  3. Import to nself: Sync the approved design to your project
  4. Generate Migrations: Create SQL migrations from the schema
  5. Iterate: Make changes in dbdiagram.io and resync

Documentation Workflow

  1. Export Schema: Push your current schema to dbdiagram.io
  2. Generate Visuals: Create documentation-ready diagrams
  3. Share with Stakeholders: Use visual diagrams for non-technical audiences
  4. Keep Updated: Regularly sync for accurate documentation

Advanced Features

Automatic Sync

Set up automatic synchronization with your CI/CD pipeline:

# In your CI/CD pipeline
nself db sync --from $DBDIAGRAM_URL --auto-commit

# Generate and apply migrations if changes detected
nself db run --auto-apply

Version Control Integration

Keep your visual designs versioned alongside your code:

# Export and commit diagram snapshots
nself db export --format dbdiagram --output diagrams/schema-v1.2.dbml
git add diagrams/schema-v1.2.dbml
git commit -m "Update schema diagram to v1.2"

Best Practices

Design Principles

  • Start Visual: Begin complex schemas in dbdiagram.io for better overview
  • Regular Sync: Keep visual and code representations in sync
  • Team Standards: Establish naming conventions for shared diagrams
  • Documentation: Use diagram notes and comments extensively

Collaboration Tips

  • Shared Workspace: Use team accounts for better collaboration
  • Change Management: Discuss major changes before implementation
  • Version Tagging: Tag important versions in your diagrams
  • Export Backups: Regularly backup your diagrams as DBML files

Troubleshooting

Common Issues

Sync Conflicts

# Resolve conflicts by choosing source
nself db sync --from dbdiagram --force  # Use dbdiagram as source
nself db sync --to dbdiagram --force    # Use local schema as source

Format Differences

# Validate schema after sync
nself db validate --verbose

# Fix common issues automatically
nself db sync --fix-format

Next Steps

Now that you understand dbdiagram.io integration:

The dbdiagram.io integration makes database design a collaborative, visual process while maintaining all the benefits of code-based schema management.