dbdiagram.io Integration

Updated for nself v0.4.8

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

Design to Database Workflow

Design your schema visually at dbdiagram.io, then import:

# Import DBML and create SQL migration
nself db schema import schema.dbml

# This creates:
# - nself/migrations/20260122_imported_schema.up.sql
# - nself/migrations/20260122_imported_schema.down.sql

Database to Design Workflow

Generate DBML from your existing database:

# Export current database schema to DBML
nself db schema diagram > schema.dbml

# Open the generated file at dbdiagram.io to visualize

Full Workflow (One Command)

# Apply everything: import -> migrate -> seed
nself db schema apply schema.dbml

# This automatically:
# 1. Imports DBML -> creates SQL migration
# 2. Runs migration
# 3. Generates mock data (local/staging only)
# 4. Seeds sample users

Schema Templates

nself v0.4.8 provides pre-built schema templates to get started quickly:

# Create starter schema from template
nself db schema scaffold basic      # Users, profiles, posts
nself db schema scaffold ecommerce  # Products, orders, cart
nself db schema scaffold saas       # Organizations, members, projects
nself db schema scaffold blog       # Posts, categories, comments

# Each creates a schema.dbml file you can:
# 1. Open at dbdiagram.io for visual editing
# 2. Customize to your needs
# 3. Apply with: nself db schema apply 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: nself db schema import schema.dbml
  4. Apply Migrations: nself db migrate up
  5. Iterate: Make changes in dbdiagram.io and re-import

Documentation Workflow

  1. Export Schema: nself db schema diagram > schema.dbml
  2. Generate Visuals: Open at dbdiagram.io
  3. Share with Stakeholders: Use visual diagrams for non-technical audiences
  4. Keep Updated: Re-export after schema changes

Schema Diff Between Environments

Compare your local schema with another environment:

nself db schema diff staging

# Example output:
# Schema Differences (local vs staging)
# ────────────────────────────────────
# + Table: user_preferences (missing in staging)
# ~ Column: users.last_login (different type)
# - Index: idx_orders_date (missing in local)

Index Recommendations

Get index suggestions based on your schema:

nself db schema indexes

# Example output:
# Index Recommendations
# ─────────────────────
# [HIGH] orders.user_id - Frequently joined, no index
# [MEDIUM] products.category_id - Used in WHERE clauses
# [LOW] users.created_at - Occasional range queries

Version Control Integration

Keep your visual designs versioned alongside your code:

# Export and commit diagram snapshots
nself db schema diagram > schema.dbml
git add schema.dbml
git commit -m "Update schema diagram"

Best Practices

Design Principles

  • Start Visual: Begin complex schemas in dbdiagram.io for better overview
  • Use Templates: Start from a scaffold, customize from there
  • Keep DBML in Sync: Re-export after manual migrations
  • 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 Control: Commit schema.dbml changes with your code
  • Test in Staging: Always test schema changes in staging first

Troubleshooting

DBML Import Errors

# Problem: Import fails with parse error
# Solution: Check DBML syntax:
# - Column names must be valid identifiers
# - Types must be supported
# - Brackets must be balanced

# Tip: Validate at dbdiagram.io before importing

Migration Conflicts

# Check status and repair if needed
nself db migrate status
nself db migrate repair   # Fix tracking table

Quick Reference

# Schema commands (v0.4.8)
nself db schema scaffold basic     # Create from template
nself db schema import file.dbml   # DBML to SQL migration
nself db schema apply file.dbml    # Full workflow: import + migrate + seed
nself db schema diagram            # Database to DBML
nself db schema diff staging       # Compare schemas
nself db schema indexes            # Suggest indexes

# After changes in dbdiagram.io:
# 1. Export DBML from dbdiagram.io
# 2. nself db schema import schema.dbml --name my_changes
# 3. nself db migrate up

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.