Project Setup

Complete guide to setting up DBackup for development.

Prerequisites

Required

• Node.js 20 or higher
• pnpm (package manager)
• Git

For Testing

• Docker and Docker Compose
• Database CLI tools:
  • mysql / mysqldump (MySQL/MariaDB)
  • psql / pg_dump (PostgreSQL)
  • mongodump / mongorestore (MongoDB)
  • gbak / isql (Firebird)
  • sqlpackage (Azure SQL Database)

Use the setup script for your platform rather than installing these by hand. Several of them have non-obvious requirements that a plain brew install gets wrong.

macOS Installation

brew install node
npm install -g pnpm

# Installs every CLI tool the adapters need, and prints the PATH lines to add
./scripts/setup-dev-macos.sh

Then add this to ~/.zshrc. The script prints it too, but it is easy to skip past:

export PATH="/opt/homebrew/opt/mysql-client/bin:/opt/homebrew/opt/postgresql@18/bin:/opt/homebrew/opt/postgresql@16/bin:/opt/homebrew/opt/postgresql@14/bin:/opt/homebrew/firebird-client/bin:$PATH"

SqlPackage needs no entry of its own. The script installs it into $(brew --prefix)/bin, which is already on PATH, and wraps it so it finds the .NET runtime without a DOTNET_ROOT variable.

Do not install libpq for PostgreSQL

libpq ships a pg_dump compiled without LZ4 and ZSTD support. If its directory comes first on PATH, PostgreSQL backups with native compression fail. Install the full postgresql@XX packages instead, which the script does.

Restart the dev server after changing PATH

A running pnpm dev inherited its environment at launch, and an editor-launched terminal often carries a different one than your login shell. If an adapter reports a missing CLI tool that works in your terminal, this is almost always why.

Ubuntu/Debian Installation

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g pnpm

# Installs every CLI tool, including SqlPackage, and prints a summary of what resolved
sudo ./scripts/setup-dev-debian.sh

Clone and Install

# Clone repository
git clone https://github.com/Skyfay/DBackup.git
cd DBackup

# Install dependencies
pnpm install

Environment Configuration

# Copy example configuration
cp .env.example .env

Edit .env with your settings:

# Database
DATABASE_URL="file:./data/database.db"

# Encryption (generate with: openssl rand -hex 32)
ENCRYPTION_KEY="your-32-byte-hex-key"

# Authentication
BETTER_AUTH_SECRET="your-auth-secret"
BETTER_AUTH_URL="http://localhost:3000"

# Optional: Timezone
TZ="Europe/Berlin"

Generate Encryption Key

# macOS/Linux
openssl rand -hex 32

Database Setup

The dev server handles migrations automatically. pnpm dev runs prisma migrate deploy on every startup, so the local database is always in sync with the schema - no manual step needed after pulling changes.

# Start the dev server — migrations apply automatically
pnpm dev

Open http://localhost:3000 in your browser.

Never use prisma db push

prisma db push applies schema changes without creating a migration file. This causes the local _prisma_migrations table to diverge from the actual schema, breaking database:deploy in production and for every other developer. Always use prisma migrate dev to create a proper migration instead.

Schema changes require a stopped dev server

Never run prisma migrate dev while pnpm dev is running. The dev server holds an open SQLite connection. migrate dev can trigger an interactive DB reset (on schema drift), which conflicts with the file lock and crashes the Node process.

Safe workflow for schema changes:

1. Stop the dev server (Ctrl+C)
2. npx prisma migrate dev --name <migration-name>
3. Restart pnpm dev - the new migration applies automatically on startup

Test Database Setup

For integration testing, start the test database containers:

# Start test databases
docker-compose -f docker-compose.test.yml up -d

This starts:

• MySQL 8.0 on port 3306
• PostgreSQL 15 on port 5432
• MongoDB 6.0 on port 27017

Test Database Credentials

Database	Host	Port	User	Password
MySQL	localhost	3306	root	rootpassword
PostgreSQL	localhost	5432	testuser	testpassword
MongoDB	localhost	27017	-	-

Running Tests

# Run unit tests
pnpm test

# Run integration tests (requires test containers)
pnpm test:integration

# Seed test data for UI testing
pnpm test:ui

Useful Commands

Prisma

# Open database GUI
npx prisma studio

# Create a new migration (stop pnpm dev first!)
npx prisma migrate dev --name <description>

# Reset dev database from scratch (drops + recreates via all migrations)
pnpm run database:reset

WARNING

Always stop pnpm dev before running prisma migrate dev. See Database Setup for the full safe workflow.

Development

# Start development server
pnpm dev

# Build for production
pnpm run build

# Start production server
pnpm start

# Lint code
pnpm lint

IDE Setup

VS Code

Recommended extensions:

• ESLint
• Prettier
• Prisma
• Tailwind CSS IntelliSense

Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative"
}

Troubleshooting

Port Already in Use

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

Database Connection Issues

# Check if containers are running
docker ps

# View container logs
docker logs dbackup-mysql-test

CLI Tools Not Found

Ensure database CLI tools are in your PATH:

# Verify installation
which mysqldump
which pg_dump
which mongodump

Next Steps

• Architecture - Understand the system design
• Service Layer - Learn about business logic
• Adapter System - How to extend DBackup