DbGate Server - Web Interface

7.1.9 · active · verified Wed Apr 22

DbGate Server (dbgate-serve) is the open-source community edition of a cross-platform database administration tool, providing a web-based user interface for managing various databases. It supports MySQL, PostgreSQL, SQL Server, MongoDB, Redis, SQLite, CockroachDB, MariaDB, and ClickHouse, with premium versions offering additional support for Amazon Redshift and CosmosDB. The current stable version is 7.1.9, with a frequent release cadence evidenced by numerous patches and minor versions in its recent history. Key differentiators include its broad database support, schema comparison, visual query designer, chart visualization, and robust batch export/import functionalities. It operates primarily as a command-line executable, configured via environment variables or `.env` files, and serves a local web application.

Common errors

```
Address already in use :::3000
```
cause Another application (or another instance of dbgate-serve) is already using port 3000.

fix Stop the conflicting application or configure `dbgate-serve` to use a different port by setting the `PORT` environment variable (e.g., `PORT=4000 dbgate-serve`).
```
Error: Cannot find module 'dbgate-plugin-mysql'
```
cause A database plugin specified in your `.env` file (e.g., `STORAGE_ENGINE=mysql@dbgate-plugin-mysql`) is not installed or incorrectly referenced.

fix Ensure the required database plugin package is correctly installed (e.g., `npm install dbgate-plugin-mysql`) and spelled correctly in your configuration.
```
Error connecting to database: Handshake inactivity timeout
```
cause The DbGate server could not establish a connection to the configured database within the allowed timeout period, often due to incorrect credentials, firewall rules, or the database server not running/being inaccessible.

fix Verify database credentials, host, and port in your `.env` file or connection settings. Check firewall rules on both the DbGate server and database server. Ensure the database server is running and accessible from where `dbgate-serve` is hosted.

Warnings

breaking Public DbGate cloud infrastructure has been migrated. Endpoints are now on new infrastructure.
Fix: No direct code fix needed for `dbgate-serve` CLI users, but be aware of potential changes if integrating with DbGate cloud services or premium features. Ensure your network allows connections to the new infrastructure if applicable.
gotcha Security vulnerability fixed related to validation of function and file names.
Fix: Upgrade to version 7.1.9 or later to receive the security patch. Regularly update `dbgate-serve` to benefit from the latest security improvements and bug fixes.
gotcha Oracle Instant Client (thick mode) requires specific configuration and external binaries.
Fix: For Oracle database users requiring features only supported in thick mode, download and unpack the Oracle Instant Client and set the `ORACLE_INSTANT_CLIENT` environment variable to its directory path. Refer to the DbGate documentation and Oracle's `node-oracledb` guide for detailed setup instructions.
gotcha This package (`dbgate-serve`) is a CLI application, not a library for programmatic import.
Fix: To run the application, use the `dbgate-serve` command in your terminal. For programmatic interactions with DbGate's features (e.g., managing connections, executing queries), use the `dbgate-api` package instead.

Install

npm install dbgate-serve npm
yarn add dbgate-serve yarn
pnpm add dbgate-serve pnpm

Imports

dbgate-serve
wrong:
```
import dbgateServe from 'dbgate-serve';
import { startServer } from 'dbgate-serve';
const dbgateServe = require('dbgate-serve');
```
correct:
```
This package is not designed for programmatic import. Run it as a CLI tool.
```
The `dbgate-serve` package provides a command-line executable (`dbgate-serve`) to start the web server. It is an application, not a library meant for direct JavaScript/TypeScript imports. For programmatic interaction with DbGate's functionality, consider using the `dbgate-api` package instead.
DbGate API (recommendation)
wrong:
```
import { openDatabase } from 'dbgate-serve';
```
correct:
```
import { openDatabase } from 'dbgate-api';
```
If you intend to interact with DbGate's database functionalities from your JavaScript/TypeScript code (e.g., opening connections, querying), the `dbgate-api` package is the correct entry point, not `dbgate-serve`.
CLI Execution
wrong:
```
node -e "require('dbgate-serve').start()"
```
correct:
```
dbgate-serve
```
The primary method of using `dbgate-serve` is by executing its installed command-line interface. Direct programmatic execution via `node` and `require()` is not supported as it's an application entry point, not an exportable module function.

Quickstart

This quickstart demonstrates how to install `dbgate-serve` globally, optionally configure it using a `.env` file for various database settings, and then run the server to access the web interface.

npm install -g dbgate-serve

# Create a .env file for configuration (optional)
# Example .env content for local storage (Premium feature, but demonstrates pattern):
# STORAGE_SERVER=localhost
# STORAGE_USER=root
# STORAGE_PASSWORD=mypassword
# STORAGE_DATABASE=dbname
# STORAGE_ENGINE=mysql@dbgate-plugin-mysql

# Run the DbGate server
dbgate-serve

# Then open http://localhost:3000 in your browser

view raw JSON →