# DevDb
<p align="center">
<a href="https://github.com/damms005/devdb-vscode/actions"><img alt="Tests passing" src="https://img.shields.io/github/actions/workflow/status/damms005/devdb-vscode/deploy.yml?style=for-the-badge&logo=github&label=TESTS"></a>
<a href="https://marketplace.visualstudio.com/items?itemName=damms005.devdb"><img alt="VS Code Marketplace Installs" src="https://img.shields.io/visual-studio-marketplace/i/damms005.devdb?style=for-the-badge&cacheSeconds=10800"></a>
<a href="https://marketplace.visualstudio.com/items?itemName=damms005.devdb&ssr=false#review-details"><img alt="VS Code Marketplace Rating" src="https://img.shields.io/visual-studio-marketplace/r/damms005.devdb?style=for-the-badge&cacheSeconds=10800"></a>
<a href="https://github.com/sponsors/damms005"><img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-%23db61a2.svg?&logo=github&logoColor=white&labelColor=181717&style=for-the-badge"></a>
</p>
<p align="center">
<a href="https://marketplace.visualstudio.com/items?itemName=damms005.devdb">VS Code Marketplace page</a>
⋅
<a href="https://open-vsx.org/extension/damms005/devdb">Open VSX Registry page</a>
</p>
A lightweight VS Code extension that auto-loads your database and provides affordances from your database to aid development and debugging.
Built with 💖 for developers.
## Featured In
<table>
<tr><td>
<a title="Laravel News" href="https://laravel-news.com/devdb">
<img alt="Laravel News" height="40" src="resources/featured/laravel-new.png" /></a>
</td>
<td>
<a title="DDEV documentation" href="https://ddev.readthedocs.io/en/latest/users/usage/database-management/#database-guis">
<img alt="DDEV documentation" height="40" src="resources/featured/ddev.png" />
</a>
</td>
<td>
<a title="Daily dev" href="https://app.daily.dev/posts/JAhlsLY2E">
<img alt="Daily dev" height="20" src="resources/featured/daily-dev.png" />
</a>
</td>
<td>
<a title="TestDevTools" href="https://testdev.tools/dev-db">
<img alt="TestDevTools" height="40" src="resources/featured/test-dev-tools.png" />
</a>
</td>
</tr>
</table>
## Latest Features
1. Zero-config auto-detection for local Supabase projects
1. Fix issues with Django projects zero-config support
1. Correctly report MariaDB in DDEV projects
1. **[Pro]** MongoDB support with automatic schema inference
1. **[Pro]** MySQL/MariaDB over SSH tunnel
1. **[Pro]** PostgreSQL over SSH tunnel
## Sponsors
We are genuinely grateful to the following sponsors of DevDb:
- [DevWorkspace Pro](https://devworkspacepro.com) - Easily build and manage web apps, with conveniences that supercharge your productivity
- [Traycer AI](https://traycer.ai) - A Powerful AI assistance, natively integrated into your VS Code workflow.
## Features
- **MCP Server:** Provide your database information to AI-powered IDEs and MCP clients like Cursor, Windsurf, etc.
- **Quick table open command:** Press `Cmd+K Cmd+G` (Mac) or `Ctrl+K Ctrl+G` (Windows/Linux) to quickly open any table.
- **Zero-config Database Auto-discovery:** Automatically discover and load your database ― no manual configuration required. Supports environments like DDEV, Adonis, Laravel, containerized setups (Laravel Sail), etc.
- **Database affordances for Local Development:** Because of a deep understanding of your database schema, DevDb is able to provide affordances that aid development and debugging, such as one-click generation of Eloquent Model factories, etc.
- **Powerful IDE Integrations:** DevDb nicely integrates your database with your IDE to provide very useful IDE-powered features like Context Menu & CodeLens Integrations directly in your editor, providing features like opening tables from code, invoking [SQL query explainer](https://mysqlexplain.com) when working on query optimization tasks, etc.
- **Rich Database Client with Intuitive UX:** Dedicated database client view with one-click data browsing, inline editing, deletion, one-click reconnection, etc. Easily modify, set values to null, preview complex JSON data, all within a responsive interface.
- **Data Export:** Export table data as well-formatted JSON or SQL INSERT statements copied to your clipboard or saved to file.
- **Comprehensive Multi-database Support:** Seamlessly interface with SQLite, MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, and MongoDB. Connect to remote databases securely via SSH tunnels.
- **Intuitive Configuration System:** In environments where automatic [zero-config](#1-zero-config-automatic-database-loading) is unavailable, DevDb provides quick snippets that produce well-formatted templates, as well as JSON Schema validation IntelliSense, which altogether makes creating configuration file for connecting to your database an awesome experience.
- **Integrated Framework & Tool Support:** Tailored support for popular frameworks and tools including Laravel, DDEV, Ruby on Rails, and Adonis ensures a seamless development experience. Need special feature(s) for your environment? [We're listening!](https://github.com/damms005/devdb-vscode/discussions/new?category=ideas).
- **Cross-platform Compatibility:** Engineered to perform consistently on Linux, macOS, and Windows, ensuring maximum flexibility as you can carry on your work across all these platforms.
## Screenshots
## Requirements
- VS Code 1.83 or newer
- A VS Code project using any of the [supported databases](#supported-databases)
## OS/Platform Support
- Linux \*(Linux-x64, Linux-arm64, Linux-arm, Alpine-x64)
- macOS (Darwin-x64, Darwin-arm64 Apple Silicon)
- Windows (Win32-x64)
---
<small>
Ubuntu 20.04 (including equivalent distors) and below are not supported because they have reached EOL and no longer supported runners in GitHub Actions. See https://github.com/actions/runner-images/issues/11101
</small>
---
## Quick Start
- In a VS Code project using any of the [supported databases](#supported-databases), ensure your database is properly configured and accessible from your application code.
- For [zero-config environments](#1-zero-config-automatic-database-loading), DevDb automatically discovers and [auto-loads your database](#loading-databases). View your database by opening the DevDb view like in the screenshot shown, or by [using the shortcut](#keybinding).
> [!NOTE]
> DevDb also provides several [Language and Framework Integrations](#language-and-framework-integrations)
### UI Actions and Key Map
- `Cmd + K + D` to toggle the view panel
- `Cmd + K + G` to go to a table
- `Cmd + Click` table name in the sidebar to open the table in the current tab
- `Cmd + Click` on a database value to edit it
- Click any value to preview it in the pane (useful for viewing prettified JSON string values)
- The right pane offers options to view the current table schema or selected value
- During edit sessions (activated during data edit/delete), the control box appears as shown in the screenshot
- During edit sessions: `Cmd + Z` to undo changes, `Cmd + Y` to redo changes, and `Cmd + S` to save changes
- Added new "Suggest New Feature" button
### One-click Actions (Data Manipulation)
- Click the trash icon on a table row to delete it
- Click the `Set null` button on a database value to set the value to `null`
## Supported Databases
Currently supported databases:
- SQLite
- MySQL
- MariaDB
- PostgreSQL
- Microsoft SQL Server
- Supabase
- MongoDB **[Pro]**
- MySQL over SSH **[Pro]** (also supports MariaDB)
- PostgreSQL over SSH **[Pro]**
- Supabase Cloud **[Pro]**
## Loading Databases
DevDb can automatically discover and load your database using connection details from your VS Code workspace ([zero-config](#1-zero-config-automatic-database-loading) mode). When this zero-config auto-discovery isn't available, a [configuration file](#2-config-based-database-loading) option is provided.
### 1. Zero-config (Automatic Database Discovery)
No [configuration file](#2-config-based-database-loading) is needed when the workspace root contains any of the following:
1. Applications managed by [DDEV](https://ddev.com)
1. Local [Supabase](https://supabase.com) projects (detected via `supabase/config.toml`)
1. [Adonis](https://adonisjs.com) using default .env config for MySQL and PostgreSQL (with Lucid ORM)
1. [Django](https://www.djangoproject.com) with settings.py for SQLite, MySQL, and PostgreSQL
1. [Ruby on Rails](https://rubyonrails.org) with config/database.yml for SQLite, MySQL, and PostgreSQL
1. [Laravel](https://laravel.com) with default local SQLite database
1. Laravel with default .env config for MySQL/MariaDB, PostgreSQL, and Microsoft SQL Server
1. Containerized Laravel MySQL (Laravel Sail) with default .env/docker-compose.yml config (including [dev containers](https://code.visualstudio.com/docs/devcontainers/containers) support)
### 2. Config-based Database Loading
If [zero-config](#1-zero-config-automatic-database-loading) support isn't available for your environment, create a `.devdbrc` file in your project root with your database connection details.
> [!WARNING]
> Exclude the `.devdbrc` config file from version control by adding it to `.gitignore`. This protects sensitive information and allows team members to use different database configurations.
The configuration file should contain a single array of database connection objects. DevDb provides rich editing features for `.devdbrc`:
- **JSON Schema Validation**: Automatic configuration validation
- **IntelliSense**: Autocompletion for all fields, including `type`
- **Snippets**: Quick configuration templates:
- `devdb mysql`: MySQL configuration
- `devdb mariadb`: MariaDB configuration
- `devdb postgres`: PostgreSQL configuration
- `devdb sqlite`: SQLite configuration
- `devdb mssql`: Microsoft SQL Server configuration
#### Configuration File Example
```json
[
{
"name": "My test MySQL database",
"type": "mysql",
"host": "127.0.0.1",
"port": "3306",
"username": "root",
"password": "12345",
"database": "test" // <-- the database to show in VS Code DevDb view
},
{
"type": "sqlite",
"path": "/path/to/database.sqlite"
},
{
"name": "My MSSQL database",
"type": "mssql",
"host": "localhost",
"port": "1433",
"username": "sa",
"password": "YourPassword123",
"database": "master",
"options": {
"trustServerCertificate": true
}
}
]
```
### 3. Remote & NoSQL Connections [Pro]
With DevDb Pro License, you can connect to remote databases and NoSQL databases directly from your editor.
#### SSH Tunnel Connections (MySQL/MariaDB & PostgreSQL)
Connects to a remote database by forwarding traffic through an SSH tunnel. Authentication supports:
- **Private key** (recommended): Provide the path to your SSH private key (e.g. `~/.ssh/id_rsa` or `~/.ssh/id_ed25519`). If the key is passphrase-protected, you will be prompted for it on first connection.
- **Password**: If no private key is provided, you will be prompted for the SSH password.
> [!NOTE]
> The remote server's SSH daemon must have `AllowTcpForwarding` set to `yes` (or `local`) in `/etc/ssh/sshd_config`. Without this, the SSH tunnel will fail to establish. The remote database host/port default to `127.0.0.1:3306` (MySQL) or `127.0.0.1:5432` (PostgreSQL) — change these if your database binds to a different address or port on the remote machine.
#### MongoDB
Connects via either individual fields (host, port, username, database) or a full connection string URI (`mongodb://...` or `mongodb+srv://...`). When using authentication, provide credentials and set the `authSource` (defaults to `admin`).
#### Supabase Cloud
Connect to your Supabase cloud project using the **Direct Connection** type. Use the connection details from your Supabase dashboard (Settings > Database):
- **Host**: Your project's database host (e.g. `db.<project-ref>.supabase.co`)
- **Port**: `5432`
- **Username**: `postgres`
- **Password**: Your database password
- **Database**: `postgres`
## Troubleshooting Remote Connections
### SSH Tunnels
- `AllowTcpForwarding` must be `yes` or `local` in `/etc/ssh/sshd_config` on the remote server
- You may need to change private key permissions to `600` (e.g. `chmod 600 ~/.ssh/id_rsa`)
- DB host/port fields refer to the address **on the remote machine** (e.g. `127.0.0.1:3306`), not your local machine
- SSH logs: `/var/log/auth.log` (Debian/Ubuntu) or `/var/log/secure` (RHEL/CentOS)
### MongoDB
- `authSource` must match the database where the user was created (typically `admin`)
- Credentials in connection string URIs must be [URL-encoded](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-standard-connection-string-format) if they contain special characters
### Supabase Cloud
- Use **Direct Connection** details from Supabase dashboard, not the connection pooler
- Check Settings > Database > Network Bans if connections are refused
## Tools and Framework Integrations
### Context Menu Entry
Open any database table in DevDb by right-clicking its name/model/entity from the editor in **any** framework/programming language.
Example from a Node.js app
### Laravel
#### Eloquent Model Code Lens
DevDb provides Code Lens features for:
- Viewing the underlying table for the Eloquent model
- Generating a factory for the model (automatically pre-filled with real data from the underlying table)
> [!NOTE]
> Factory Generation is also available via the context menu
#### Query Explainer
The Query Explainer integrates with [MySQL Visual Explain](https://mysqlexplain.com) to optimize SQL queries by analyzing MySQL's query execution plan. Usage:
1. Open a Laravel PHP file containing SQL query (Eloquent or `DB` facade)
2. Select the SQL query to analyze
3. Click the `Explain query` Code Lens or select `Explain query` from the context menu
4. View the explanation in your browser or copy the URL
> [!NOTE]
> VS Code [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) support is in development. Track progress [here](https://github.com/damms005/devdb-vscode/issues/68).
<!-- TODO: update when completed -->
### MCP Integration
DevDb exposes your database to AI-powered IDEs and MCP clients. You only need to configure once, and then you can query your database naturally through AI.
#### For Claude Code
1. Open your project in VS Code with DevDb active
2. Click the hammer icon in DevDb view to copy the server script path
3. Add the MCP server using CLI (substitute the path you copied in step 2):
```bash
claude mcp add --transport stdio devdb-mcp-server node "<paste-script-path-here>"
```
4. Claude Code can now query your database using tools like `get-tables`, `get-schema`, `get-database-type`, and `run-query`
#### For VS Code-based IDEs (Cursor, Windsurf, Cline, etc.)
1. Click the hammer icon in DevDb view to copy the MCP configuration JSON
2. Open your IDE's MCP config file:
- **[VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_other-options-to-add-an-mcp-server)**: `.vscode/mcp.json`
- **[Cursor](https://cursor.com/docs/context/mcp#configuration-locations)**: `~/.cursor/mcp.json`
- **[Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp_config-json)**: `~/.codeium/windsurf/mcp_config.json`
3. Paste the copied JSON under the appropriate key and reload your IDE
Your AI assistant can now access your database schema and run queries.
> [!NOTE]
> You should update the config when you update to a new version of DevDb because the version number may change.
## URI Handler
DevDb provides a custom URI handler that allows you to open specific database tables directly from external applications or links. This is useful for integrating DevDb with other tools or creating shortcuts to frequently accessed tables.
### URI Format
The URI format follows this pattern:
```
vscode://devdb/open/table?connectionId=123&database=main&table=users&workspace=...
```
Parameters:
- `connectionId`: The ID of the database connection
- `database`: The database name
- `table`: The table name to open
- `workspace`: (Optional) The workspace path
## Support
You can support the development of DevDb by [contributing](#contribution) features and submitting PRs, or by [sponsoring the development](https://github.com/sponsors/damms005). We appreciate your DevDb sponsorships with perks and you can check the [sponsorship page](https://github.com/sponsors/damms005) for available sponsorship options.
You can also support this project by using the services offered by our sponsors:
- [Traycer AI](https://traycer.ai/#pricing1)
- [DevWorkspace Pro](https://devworkspacepro.com)
Please do check out [other projects](https://damms005.dev/projects) by Damilola Olowookere for other sponsorship options.
## Contribution
> [!IMPORTANT]
> Contributions are currently limited to the extension core code. UI code is not available for public contribution.
1. Fork this repository and clone your fork locally
1. Run `bun install` to install dependencies
1. Make your contributions to the codebase
1. Press `F5` to launch the debugger and test changes locally
1. Run test suites with `bun run test-services` and ensure all tests pass
1. Push changes to your fork
1. Open a PR to this repository
1. Take your flowers! 💐🌺🌹
