databasement - Moses Yebei

Abstract

Self-hosted database backup manager with a web UI. Schedule, backup, and restore MySQL, PostgreSQL, MariaDB, Microsoft SQL Server, MongoDB, SQLite & Redis to S3, SFTP, Samba or local storage. SSH Tunnel support.

The Problem

Enterprises that run many heterogeneous databases need a single, auditable place to schedule dumps, store them off‑site, and restore on demand. Doing this manually (cron + scp + ad‑hoc scripts) is error‑prone, hard to monitor, and provides no role‑based access control.

What This Does

databasement is a Laravel + React application that centralises backup/restore orchestration for MySQL, PostgreSQL, MariaDB, MSSQL, MongoDB, SQLite, Firebird and Redis. The backend lives under app/ – e.g. app/Http/Controllers/Api/V1/BackupJobController.php receives API calls, validates them with request classes such as SaveBackupScheduleRequest.php, and dispatches Laravel jobs (ProcessBackupJob.php). The frontend entry point is resources/js/app.js, compiled by the bundled Vite/React stack.

Storage back‑ends are abstracted in the app/Livewire/Volume components (S3, SFTP, Azure, SMB, local). Compression/encryption choices are defined in app/Enums/CompressionType.php and applied in the dump pipeline inside app/Actions/Fortify/* and the agent command app/Console/Commands/AgentRunCommand.php. The optional remote agent runs as a lightweight Go/Node process (not in this PHP tree) and pushes dumps to the server via HTTPS.

How It Is Wired

Entry point – HTTP requests hit Laravel’s front controller (public/index.php, not listed but standard). Routes are defined in routes/api.php and point to controllers such as BackupJobController.
Controller → Request → Service – BackupJobController::store() uses SaveBackupScheduleRequest for validation, then calls BackupJob::create() (model in app/Models/BackupJob.php).
Job dispatch – The controller queues ProcessBackupJob (app/Jobs/ProcessBackupJob.php). Laravel’s queue worker (started by php artisan queue:work inside the Docker image) picks it up.
Backup pipeline – ProcessBackupJob::handle() invokes AgentRunCommand (via Symfony\Component\Process) to spin up the local dump tool, streams output through CompressionType (gzip/zstd/AES‑256), and writes the file to a Volume implementation (app/Livewire/Volume/Connectors/S3Config.php, etc.).
Storage & Metadata – After upload, BackupJob record is updated, a Snapshot model (app/Models/Snapshot.php) is created, and a BackupLogger implementation logs progress to the DB (app/Contracts/BackupLogger.php).
Restore path – SnapshotController::restore() triggers ProcessRestoreJob which pulls the snapshot from the chosen volume, runs the appropriate DB client (mysqldump, pg_dump, etc.), and streams data back into the target server, optionally via SSH tunnel (app/Exceptions/SshTunnelException.php).

The most critical hub is the Laravel queue worker: any change to ProcessBackupJob or its downstream helpers can affect all backup schedules. The volume connectors are isolated – swapping S3 for SFTP only touches the corresponding *Config.php class.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/databasement.git
cd databasement

# Copy example env and edit required keys (DB_HOST, S3_ACCESS_KEY, etc.)
cp .env.example .env
# Edit .env – see docs/self-hosting/docker-compose.md for required vars

# Build and start containers
docker compose up -d --build

# Run migrations and seed default data
docker exec -it databasement-php php artisan migrate --seed

# Access UI
open http://localhost:8000

The Dockerfile builds a PHP 8.2 image with Composer dependencies (composer.json). docker-compose.yml defines three services: php (Laravel app + queue worker), nginx (static assets), and db (MariaDB for the app’s own metadata). The Makefile offers shortcuts such as make test (runs PHPUnit in tests/).

Real‑World Use

A SaaS provider can deploy databasement behind its internal network, register each customer’s MySQL instance via the UI, set a daily 03:00 UTC schedule, and choose S3‑compatible storage in a separate AWS account. The provider’s CI pipeline can call the REST endpoint (POST /api/v1/backup-jobs) to trigger ad‑hoc backups before a major release.

Code Health & Issues

Low – .env file present – a template .env is tracked; if populated with real secrets it would expose credentials.
No explicit license file in the root (only LICENSE placeholder); legal compliance may need confirmation.
Test suite exists (tests/), but CI workflow (.github/workflows/tests.yml) does not enforce coverage thresholds.

No static analysis warnings beyond the above were reported.

The Bottom Line

databasement delivers a full‑stack, Docker‑ready backup manager with a clean Laravel/React separation and extensible storage plugins. It is production‑ready for teams comfortable with Laravel queues and Docker, but the presence of a tracked .env and missing licence details require careful handling before public deployment. Suitable for organisations that need multi‑DB scheduling, role‑based UI, and API‑driven automation.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

783 files

PHP641
Markdown30
YAML23
JSON14
Shell7
SQL4

ReactExpressLaravelDockerKubernetes

Dependencies

1 of 67 declared dependencies are a major version behind. Resolved 24 of 67 against the registry.

Package	Declared	Latest	Behind
`typescript`	~5.8.3	7.0.2	2 major

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them .env

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical3

high3

medium3

low1

Rotate the credentials in the committed environment filecritical

.env

APP_KEY hold generated values

These values are loaded by the application at boot, so a generated value here is a working credential for something that runs.

Fix: Rotate each named credential, remove the file from the index, and replace it with a keys-only example.

Do not check out pull request code in a privileged workflowcritical

.github/workflows/coverage-and-quality.yml

privileged trigger checks out the untrusted ref

This is the most reliably exploited Actions pattern: anyone opening a pull request gets code execution with your repository secrets.

Fix: Split into an unprivileged pull_request build and a workflow_run job that only consumes its artifact.

Keep secrets out of workflows a fork can triggercritical2 occurrences

.github/workflows/coverage-and-quality.yml

CODECOV_TOKEN, SONAR_TOKEN (publish or cloud scope)

Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration.

Fix: Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.

Pin third-party GitHub Actions to a commit SHAhigh9 occurrences

.github/workflows

codecov/codecov-action@v7, SonarSource/sonarqube-scan-action@v8, dorny/paths-filter@v4, docker/metadata-action@v6

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Remove the committed .env and rotate what it holdshigh

.env

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/coverage-and-quality.yml

line 54 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Pin the container base image by digestmedium

Dockerfile

node:22-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Set persist-credentials: false on checkoutmedium

.github/workflows/tests.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/coverage-and-quality.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.