# dbgate

**Repository Path**: kylin87/dbgate

## Basic Information

- **Project Name**: dbgate
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DBGate

DBGate is an internal platform for database operation approval and serial SQL scheduling. The current implementation includes local authentication, mandatory TOTP MFA, RBAC, append-only audit logs, encrypted target MySQL instance configuration, and an Aliyun DMS-backed SQL approval MVP.

## Requirements

- PHP 8.3, invoked as `php83`
- Composer 2, invoked as `composer83`
- MySQL 8 for DBGate platform data
- Redis for sessions and login rate limiting

## Setup

1. Create a platform MySQL database and separate runtime and migration accounts.
2. Copy `.env.example` to `.env` and set all database, Redis, initial-admin, and credential-key values.
3. Generate a credential key with the command documented in `.env.example`.
4. Run migrations with `php bin/migrate.php`. It uses `DB_*` by default; if `DB_MIGRATION_*` is configured, the migration script uses that account. The migration creates append-only audit triggers.
5. Switch `.env` to the restricted runtime account, which needs only `SELECT` and `INSERT` on `dbgate_audit_logs`.
6. Seed roles and the initial administrator with `php83 bin/seed-foundation.php`.
7. Start Webman with `php83 start.php start`.

The health endpoint is available at `GET /health`.

### Migration Account

The web runtime account should stay restricted. To run DDL without editing runtime credentials, set migration-only variables and enable the migration switch:

```bash
php bin/migrate.php
```

The migration connection reads `DB_MIGRATION_HOST`, `DB_MIGRATION_PORT`, `DB_MIGRATION_USERNAME`, and `DB_MIGRATION_PASSWORD`.

### Aliyun DMS Integration

SQL approval uses Aliyun DMS Enterprise OpenAPI:

- `CreateDataCorrectOrder` creates a DMS data correction order after DBGate local review passes.
- `ListDataCorrectPreCheckSQL` syncs DMS precheck status and SQL-level findings.
- `ExecuteDataCorrect` submits execution, including optional scheduled execution window.
- `GetOrderBaseInfo` and `GetDataCorrectOrderDetail` sync DMS order status back to DBGate.

Configure DMS credentials in `.env`, then edit each database instance and fill either DMS Database ID or DMS Instance ID. Prefer DMS Database ID for normal SQL approvals.

DBGate also starts a lightweight background sync process with Webman. It only reads open DMS orders and updates local progress. Tune it with `DMS_SYNC_ENABLED`, `DMS_SYNC_INTERVAL_SECONDS`, and `DMS_SYNC_LIMIT`.

### Production Configuration

DBGate has two kinds of database configuration:

1. Platform database: DBGate's own MySQL database, configured only in `.env` with `DB_*` and `DB_MIGRATION_*`.
2. Target databases: business databases that developers submit SQL against. Configure them after login under `目标数据库`.

For Aliyun DMS-managed databases, prefer using `目标数据库` → `从 DMS 选择数据库`. Global DMS credentials live in `.env`; per-database DMS IDs are stored in DBGate after import, not in `.env`.

Do not commit `.env`. For production, copy `.env.example` to `.env` on the internal server, fill real values there, run migrations, then create/import target databases from the admin UI.

### Kubernetes / Shared Runtime Directory

When running multiple Pods that share the same project or `runtime` directory, set:

```env
RUN_ENV=docker
```

Following the same approach as Wind's other Webman services, DBGate uses `gethostname()` when `RUN_ENV=docker`.
In Kubernetes, the container hostname is normally the Pod name, so `pid`, `status`, stdout, Workerman logs, and application logs will be separated by Pod/container name and will not overwrite each other in a shared directory.

### Notifications

Optional DingTalk robot notifications can be enabled with `DINGTALK_ROBOT_WEBHOOK` and `DINGTALK_ROBOT_SECRET`. When configured, DBGate sends SQL lifecycle messages for submission, precheck results, rejection, execution submission, and final execution results. Notification failures are logged and never change the SQL request state.

## Safety Rules

- Never commit `.env`, database passwords, the credential key, temporary passwords, or TOTP secrets.
- The platform database account must not receive `UPDATE` or `DELETE` on `dbgate_audit_logs`.
- Database instances are retained and can only be enabled or disabled; they are not deleted.
- User SQL must not be executed locally by controllers or approval services; the current approval MVP delegates precheck and execution to Aliyun DMS.
- Production must use `APP_DEBUG=false` and `SESSION_SECURE_COOKIE=true`.

## Project Documentation

- [Project guide](PROJECT_GUIDE.md)
- [Foundation design](docs/superpowers/specs/2026-07-26-dbgate-foundation-design.md)
- [Implementation plan](docs/superpowers/plans/2026-07-26-dbgate-foundation-implementation.md)