Adonis Integration

DevDb Pro provides zero-config database discovery for AdonisJS projects using Lucid ORM, automatically reading your .env configuration to connect to your database.

Zero-Config Discovery

DevDb automatically detects Adonis databases from your project configuration.

How It Works

1. Open an Adonis project in VS Code
2. DevDb reads .env file
3. Extracts database config for Lucid ORM
4. Auto-connects to your database

Requirements

• AdonisJS project with Lucid ORM
• .env file with database configuration
• Database server running and accessible

Supported Databases

DevDb works with these Adonis database connections:

• MySQL (DB_CONNECTION=mysql)
• PostgreSQL (DB_CONNECTION=pg)

SQLite Support

SQLite support for Adonis projects is coming soon.

Configuration Examples

MySQL

.env:

DB_CONNECTION=mysql

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=secret
MYSQL_DB_NAME=adonis_app

DevDb reads these variables and connects to MySQL automatically.

PostgreSQL

.env:

DB_CONNECTION=pg

PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=secret
PG_DB_NAME=adonis_app

DevDb connects to PostgreSQL using these credentials.

Environment Files

Adonis supports multiple environment files:

• .env - Main environment file
• .env.local - Local overrides (takes precedence)
• .env.testing - Test environment

DevDb reads in this order:

1. .env.local (if exists)
2. .env

Multiple Connections

Adonis supports multiple database connections:

config/database.ts:

{
  connection: Env.get('DB_CONNECTION'),

  connections: {
    mysql: {
      client: 'mysql2',
      connection: {
        host: Env.get('MYSQL_HOST'),
        port: Env.get('MYSQL_PORT'),
        user: Env.get('MYSQL_USER'),
        password: Env.get('MYSQL_PASSWORD'),
        database: Env.get('MYSQL_DB_NAME'),
      },
    },

    analytics: {
      client: 'mysql2',
      connection: {
        host: Env.get('ANALYTICS_HOST'),
        port: Env.get('ANALYTICS_PORT'),
        user: Env.get('ANALYTICS_USER'),
        password: Env.get('ANALYTICS_PASSWORD'),
        database: Env.get('ANALYTICS_DB_NAME'),
      },
    },
  },
}

.env:

DB_CONNECTION=mysql

# Primary database
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=secret
MYSQL_DB_NAME=adonis_app

# Analytics database
ANALYTICS_HOST=127.0.0.1
ANALYTICS_PORT=3306
ANALYTICS_USER=root
ANALYTICS_PASSWORD=secret
ANALYTICS_DB_NAME=analytics

DevDb detects and lists both databases in the sidebar.

Features

Database Client

Full Database Client features:

• Browse tables and data
• Inline editing
• Schema viewer
• JSON preview

Quick Table Access

Use Cmd+K Cmd+G (Mac) or Ctrl+K Ctrl+G (Windows/Linux):

• Quickly open any Lucid model table
• Search across all databases
• Instant navigation

Context Menu

Right-click table/model names in code:

• "Open table at cursor" - View table in DevDb
• Works with model class names
• Works with custom table names

Example:

// Right-click "User" and select "DevDb > Open table at cursor"
export default class User extends BaseModel {
  // ...
}

// Also works with custom table names
export default class Product extends BaseModel {
  public static table = 'inventory_items'
}

Data Export

Export table data:

• JSON format - For seeders or testing
• SQL format - For migrations or backups
• Copy to clipboard or save to file

Workflow Examples

Example 1: Inspect Models

After creating models and running migrations:

1. Run migrations: node ace migration:run
2. Open DevDb (Cmd+K Cmd+D or Ctrl+K Ctrl+D)
3. Browse tables to verify schema
4. Check indexes in Schema tab
5. Add test data directly

Example 2: Debug Data Issues

When investigating data problems:

1. Open relevant model in code
2. Right-click model name → "Open table at cursor"
3. Browse actual data in database
4. Edit test records to reproduce issue
5. Verify fix by refreshing data

Example 3: Create Seed Data

Generate seed data:

1. Create test data in DevDb
2. Export as JSON using Data Export
3. Add to seeder:

// database/seeders/User.ts
import User from 'App/Models/User'

export default class UserSeeder extends BaseSeeder {
  public async run () {
    const data = [
      // ... paste exported JSON
    ]
    await User.createMany(data)
  }
}

4. Run: node ace db:seed

Example 4: Migration Verification

After writing migrations:

1. Apply migration: node ace migration:run
2. Refresh DevDb connection
3. View schema changes in Schema tab
4. Verify constraints and indexes
5. Test with sample data

Adonis-Specific Features

Lucid Model Table Names

DevDb handles Lucid's table naming conventions:

Default naming (snake_case plural):

export default class User extends BaseModel {
  // Table: users
}

export default class BlogPost extends BaseModel {
  // Table: blog_posts
}

Custom naming:

export default class User extends BaseModel {
  public static table = 'app_users'  // Table: app_users
}

DevDb recognizes both patterns.

Migration History

View migration history:

• Open adonis_schema table
• See applied migrations
• Check batch numbers
• Verify migration order

Timestamps

View Lucid's automatic timestamps:

• created_at
• updated_at
• Preview in DevDb's date format

Troubleshooting

Database Not Detected

If DevDb doesn't find your Adonis database:

1. Check .env file exists in workspace root
2. Verify DB_CONNECTION is set
3. Check database credentials are correct
4. Ensure database is running
5. Reload VS Code window

Connection Fails

If connection doesn't work:

1. Test Adonis connection: node ace repl then await Database.rawQuery('SELECT 1')
2. Check credentials in .env
3. Verify database server is accessible
4. Review environment variables are loaded

Multiple Environment Files

If using .env.local:

1. DevDb prioritizes .env.local
2. Ensure credentials are consistent
3. Check which file Adonis is using

Docker/Container Setup

For containerized Adonis:

1. Expose database port in docker-compose.yml:

services:
  mysql:
    ports:
      - "3306:3306"

2. Use host port in .env:

MYSQL_HOST=localhost
MYSQL_PORT=3306

3. DevDb connects to exposed port

Best Practices

Development

1. Use .env.local for local overrides
2. Keep .env.example updated for team
3. Add database dumps to .gitignore
4. Export fixtures for test data

Team Collaboration

1. Document database setup in README
2. Share .env.example in version control
3. Never commit .env with credentials
4. Use consistent database versions

Security

1. Never commit .env to git
2. Use strong passwords in development
3. Exclude .devdbrc from version control
4. Sanitize exports before sharing

Integration with Other Tools

Adonis REPL

Use DevDb alongside REPL:

• DevDb for visual inspection
• REPL for complex queries
• Export from DevDb for scripting

Example REPL usage:

// In node ace repl
const users = await User.all()
// Then verify in DevDb

Ace Commands

Combine with Ace commands:

1. Generate migration: node ace make:migration
2. Run migration: node ace migration:run
3. Verify in DevDb

Testing

Use DevDb for test data:

1. Create test data in DevDb
2. Export as JSON
3. Use in tests:

// tests/functional/users.spec.ts
test('list users', async ({ client }) => {
  // Create from exported data
  await User.createMany(exportedData)

  const response = await client.get('/users')
  // Verify in DevDb if needed
})

Environment-Specific Tips

Development

• Use DevDb for quick data inspection
• Edit seed data directly
• Test relationships by browsing data

Testing

• Verify test database schema
• Check seeders load correctly
• Debug test failures visually

Staging

• Use database dump for local inspection:

mysqldump staging_db > staging_dump.sql
mysql local_staging < staging_dump.sql

• Browse safely in DevDb

Next Steps

• Database Client - Master the interface
• Quick Table Access - Navigate efficiently
• Data Export - Export fixtures
• Configuration - Manual setup if needed