Merge pull request #494 from databasus/develop

FEATURE (storages): Add uptime banner

.dockerignore

@@ -0,0 +1,73 @@
+# Git and GitHub
+.git
+.gitignore
+.github
+
+# Node modules everywhere
+node_modules
+**/node_modules
+
+# Backend - exclude everything except what's needed for build
+backend/tools
+backend/mysqldata
+backend/pgdata
+backend/mariadbdata
+backend/mongodbdata
+backend/temp
+backend/images
+backend/bin
+backend/*.exe
+
+# Scripts and data directories
+scripts
+postgresus-data
+databasus-data
+
+# IDE and editor files
+.idea
+.vscode
+.cursor
+**/*.swp
+**/*.swo
+
+# Documentation and articles (not needed for build)
+articles
+docs
+pages
+
+# Notifiers not needed in container
+notifiers
+
+# Dist (will be built fresh)
+frontend/dist
+
+# Environment files (handled separately)
+.env.local
+.env.development
+
+# Logs and temp files
+**/*.log
+tmp
+temp
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Helm charts and deployment configs
+deploy
+
+# License and other root files
+LICENSE
+CITATION.cff
+*.md
+
+# Assets - exclude SVGs but keep tools
+assets/*.svg
+assets/tools/download_postgresql.sh
+
+# Python cache
+**/__pycache__
+
+# Pre-commit config
+.pre-commit-config.yaml

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,102 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors and maintainers pledge to make participation in the Databasus community a friendly and welcoming experience for everyone, regardless of background, experience level or personal circumstances.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive and healthy community.
+
+## Our Standards
+
+### Examples of behavior that contributes to a positive environment
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+- Helping newcomers get started with contributions
+- Providing clear and constructive feedback on pull requests
+- Celebrating successes and acknowledging contributions
+
+### Examples of unacceptable behavior
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Publishing others' private information, such as physical or email addresses, without their explicit permission
+- Spam, self-promotion or off-topic content in project spaces
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Scope
+
+This Code of Conduct applies within all community spaces, including:
+
+- GitHub repositories (issues, pull requests, discussions, comments)
+- Telegram channels and direct messages related to Databasus
+- Social media interactions when representing the project
+- Community forums and online discussions
+- Any other spaces where Databasus community members interact
+
+This Code of Conduct also applies when an individual is officially representing the community in public spaces, such as using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive or unacceptable behavior may be reported to the community leaders responsible for enforcement:
+
+- **Email**: [info@databasus.com](mailto:info@databasus.com)
+- **Telegram**: [@rostislav_dugin](https://t.me/rostislav_dugin)
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Contributing with Respect
+
+When contributing to Databasus, please:
+
+- Be patient with maintainers and other contributors
+- Understand that everyone has different levels of experience
+- Ask questions in a respectful manner
+- Accept that your contribution may not be accepted, and be open to feedback
+- Follow the [contribution guidelines](https://databasus.com/contribute)
+
+For code contributions, remember to:
+
+- Discuss significant changes before implementing them
+- Be open to code review feedback
+- Help review others' contributions when possible
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq).

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior in Databasus
+labels: bug
+---
+
+## Databasus version (screenshot)
+
+It is displayed in the bottom left corner of the Databasus UI. Please attach screenshot, not just version text
+
+<!-- e.g. 1.4.2 -->
+
+## Operating system and architecture
+
+<!-- e.g. Ubuntu 22.04 x64, macOS 14 ARM, Windows 11 x64 -->
+
+## Database type and version (optional, for DB-related bugs)
+
+<!-- e.g. PostgreSQL 16 in Docker, MySQL 8.0 installed on server, MariaDB 11.4 in AWS Cloud -->
+
+## Describe the bug (please write manually, do not ask AI to summarize)
+
+**What happened:**
+
+**What I expected:**
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Have you asked AI how to solve the issue?
+
+<!-- Using AI to diagnose issues before filing a bug report helps narrow down root causes. -->
+
+- [ ] Claude Sonnet 4.6 or newer
+- [ ] ChatGPT 5.2 or newer
+- [ ] No
+
+
+## Additional context / logs
+
+<!-- Screenshots, error messages, relevant log output, etc. -->

.github/SECURITY.md

@@ -0,0 +1,66 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Databasus, please report it responsibly. **Do not create a public GitHub issue for security vulnerabilities.**
+
+### How to Report
+
+1. **Email** (preferred): Send details to [info@databasus.com](mailto:info@databasus.com)
+2. **Telegram**: Contact [@rostislav_dugin](https://t.me/rostislav_dugin)
+3. **GitHub Security Advisories**: Use the [private vulnerability reporting](https://github.com/databasus/databasus/security/advisories/new) feature
+
+### What to Include
+
+- Description of the vulnerability
+- Steps to reproduce the issue
+- Potential impact and severity assessment
+- Any suggested fixes (optional)
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| Latest  | Yes       |
+
+We recommend always using the latest version of Databasus. Security patches are applied to the most recent release.
+
+### PostgreSQL Compatibility
+
+Databasus supports PostgreSQL versions 12, 13, 14, 15, 16, 17 and 18.
+
+### MySQL Compatibility
+
+Databasus supports MySQL versions 5.7, 8 and 9.
+
+### MariaDB Compatibility
+
+Databasus supports MariaDB versions 10 and 11.
+
+### MongoDB Compatibility
+
+Databasus supports MongoDB versions 4, 5, 6, 7 and 8.
+
+## Response Timeline
+
+- **Acknowledgment**: Within 48-72 hours
+- **Initial Assessment**: Within 1 week
+- **Fix Timeline**: Depends on severity, but we aim to address critical issues as quickly as possible
+
+We follow a coordinated disclosure policy. We ask that you give us reasonable time to address the vulnerability before any public disclosure.
+
+## Security Features
+
+Databasus is designed with security in mind. For full details, see our [security documentation](https://databasus.com/security).
+
+Key features include:
+
+- **AES-256-GCM Encryption**: Enterprise-grade encryption for backup files and sensitive data
+- **Read-Only Database Access**: Databasus uses read-only access by default and warns if write permissions are detected
+- **Role-Based Access Control**: Assign viewer, member, admin or owner roles within workspaces
+- **Audit Logging**: Track all system activities and changes made by users
+- **Zero-Trust Storage**: Encrypted backups are safe even in shared cloud storage
+
+## License
+
+Databasus is licensed under [Apache 2.0](../LICENSE).

.github/workflows/ci-release.yml

@@ -2,36 +2,38 @@ name: CI and Release
 
 on:
   push:
-    branches: [main]
+    branches: ["**"]
   pull_request:
-    branches: [main]
+    branches: ["**"]
   workflow_dispatch:
 
 jobs:
   lint-backend:
-    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/develop'
+    runs-on: self-hosted
+    container:
+      image: golang:1.26.1
+      volumes:
+        - /runner-cache/go-pkg:/go/pkg/mod
+        - /runner-cache/go-build:/root/.cache/go-build
+        - /runner-cache/golangci-lint:/root/.cache/golangci-lint
+        - /runner-cache/apt-archives:/var/cache/apt/archives
     steps:
       - name: Check out code
         uses: actions/checkout@v4
 
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: "1.23.3"
+      - name: Configure Git for container
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
 
-      - name: Cache Go modules
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/go/pkg/mod
-            ~/.cache/go-build
-          key: ${{ runner.os }}-go-${{ hashFiles('backend/go.sum') }}
-          restore-keys: |
-            ${{ runner.os }}-go-
+      - name: Download Go modules
+        run: |
+          cd backend
+          go mod download
 
       - name: Install golangci-lint
         run: |
-          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.60.3
+          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.11.3
           echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
 
       - name: Install swag for swagger generation
@@ -54,6 +56,7 @@ jobs:
           git diff --exit-code go.mod go.sum || (echo "go mod tidy made changes, please run 'go mod tidy' and commit the changes" && exit 1)
 
   lint-frontend:
+    if: github.ref != 'refs/heads/develop'
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
@@ -63,8 +66,6 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "20"
-          cache: "npm"
-          cache-dependency-path: frontend/package-lock.json
 
       - name: Install dependencies
         run: |
@@ -82,9 +83,14 @@ jobs:
           cd frontend
           npm run lint
 
-  test-backend:
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm run build
+
+  lint-agent:
+    if: github.ref != 'refs/heads/develop'
     runs-on: ubuntu-latest
-    needs: [lint-backend]
     steps:
       - name: Check out code
         uses: actions/checkout@v4
@@ -92,51 +98,234 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.23.3"
+          go-version: "1.26.1"
+          cache-dependency-path: agent/go.sum
 
-      - name: Cache Go modules
-        uses: actions/cache@v4
+      - name: Download Go modules
+        run: |
+          cd agent
+          go mod download
+
+      - name: Install golangci-lint
+        run: |
+          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.11.3
+          echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+
+      - name: Run golangci-lint
+        run: |
+          cd agent
+          golangci-lint run
+
+      - name: Verify go mod tidy
+        run: |
+          cd agent
+          go mod tidy
+          git diff --exit-code go.mod go.sum || (echo "go mod tidy made changes, please run 'go mod tidy' and commit the changes" && exit 1)
+
+  test-frontend:
+    if: github.ref != 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    needs: [lint-frontend]
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
         with:
-          path: |
-            ~/go/pkg/mod
-            ~/.cache/go-build
-          key: ${{ runner.os }}-go-${{ hashFiles('backend/go.sum') }}
-          restore-keys: |
-            ${{ runner.os }}-go-
+          node-version: "20"
+
+      - name: Install dependencies
+        run: |
+          cd frontend
+          npm ci
+
+      - name: Run frontend tests
+        run: |
+          cd frontend
+          npm run test
+
+  test-agent:
+    if: github.ref != 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    needs: [lint-agent]
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.26.1"
+          cache-dependency-path: agent/go.sum
+
+      - name: Download Go modules
+        run: |
+          cd agent
+          go mod download
+
+      - name: Run Go tests
+        run: |
+          cd agent
+          go test -count=1 -failfast ./internal/...
+
+  e2e-agent:
+    if: github.ref != 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    needs: [lint-agent]
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Run e2e tests
+        run: |
+          cd agent
+          make e2e
+
+      - name: Cleanup
+        if: always()
+        run: |
+          cd agent/e2e
+          docker compose down -v --rmi local || true
+          rm -rf artifacts || true
+
+  e2e-agent-backup-restore:
+    if: github.ref != 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    needs: [lint-agent]
+    strategy:
+      matrix:
+        pg_version: [15, 16, 17, 18]
+      fail-fast: false
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Run backup-restore e2e (PG ${{ matrix.pg_version }})
+        run: |
+          cd agent
+          make e2e-backup-restore PG_VERSION=${{ matrix.pg_version }}
+
+      - name: Cleanup
+        if: always()
+        run: |
+          cd agent/e2e
+          docker compose -f docker-compose.backup-restore.yml down -v --rmi local || true
+          rm -rf artifacts || true
+
+  # Self-hosted: performant high-frequency CPU is used to start many containers and run tests fast. Tests
+  # step is bottle-neck, because we need a lot of containers and cannot parallelize tests due to shared resources
+  test-backend:
+    if: github.ref != 'refs/heads/develop'
+    runs-on: self-hosted
+    needs: [lint-backend]
+    container:
+      image: golang:1.26.1
+      options: --privileged -v /var/run/docker.sock:/var/run/docker.sock --add-host=host.docker.internal:host-gateway
+      volumes:
+        - /runner-cache/go-pkg:/go/pkg/mod
+        - /runner-cache/go-build:/root/.cache/go-build
+        - /runner-cache/apt-archives:/var/cache/apt/archives
+    steps:
+      - name: Install Docker CLI
+        run: |
+          apt-get update -qq
+          apt-get install -y -qq docker.io docker-compose netcat-openbsd wget
+
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Configure Git for container
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Download Go modules
+        run: |
+          cd backend
+          go mod download
 
       - name: Create .env file for testing
         run: |
           cd backend
           cat > .env << EOF
           # docker-compose.yml
-          DEV_DB_NAME=postgresus
+          DEV_DB_NAME=databasus
           DEV_DB_USERNAME=postgres
           DEV_DB_PASSWORD=Q1234567
           #app
           ENV_MODE=development
-          # db
-          DATABASE_DSN=host=localhost user=postgres password=Q1234567 dbname=postgresus port=5437 sslmode=disable
-          DATABASE_URL=postgres://postgres:Q1234567@localhost:5437/postgresus?sslmode=disable
+          # db - using 172.17.0.1 to access host from container
+          DATABASE_DSN=host=172.17.0.1 user=postgres password=Q1234567 dbname=databasus port=5437 sslmode=disable
+          DATABASE_URL=postgres://postgres:Q1234567@172.17.0.1:5437/databasus?sslmode=disable
           # migrations
           GOOSE_DRIVER=postgres
-          GOOSE_DBSTRING=postgres://postgres:Q1234567@localhost:5437/postgresus?sslmode=disable
+          GOOSE_DBSTRING=postgres://postgres:Q1234567@172.17.0.1:5437/databasus?sslmode=disable
           GOOSE_MIGRATION_DIR=./migrations
-          # testing
+          # testing 
+          TEST_LOCALHOST=172.17.0.1
+          IS_SKIP_EXTERNAL_RESOURCES_TESTS=true
           # to get Google Drive env variables: add storage in UI and copy data from added storage here 
           TEST_GOOGLE_DRIVE_CLIENT_ID=${{ secrets.TEST_GOOGLE_DRIVE_CLIENT_ID }}
           TEST_GOOGLE_DRIVE_CLIENT_SECRET=${{ secrets.TEST_GOOGLE_DRIVE_CLIENT_SECRET }}
           TEST_GOOGLE_DRIVE_TOKEN_JSON=${{ secrets.TEST_GOOGLE_DRIVE_TOKEN_JSON }}
           # testing DBs
+          TEST_POSTGRES_12_PORT=5000
           TEST_POSTGRES_13_PORT=5001
           TEST_POSTGRES_14_PORT=5002
           TEST_POSTGRES_15_PORT=5003
           TEST_POSTGRES_16_PORT=5004
           TEST_POSTGRES_17_PORT=5005
+          TEST_POSTGRES_18_PORT=5006
           # testing S3
           TEST_MINIO_PORT=9000
           TEST_MINIO_CONSOLE_PORT=9001
+          # testing Azure Blob
+          TEST_AZURITE_BLOB_PORT=10000
           # testing NAS
-          TEST_NAS_PORT=5006
+          TEST_NAS_PORT=7006
+          # testing FTP
+          TEST_FTP_PORT=7007
+          # testing SFTP
+          TEST_SFTP_PORT=7008
+          # testing MySQL
+          TEST_MYSQL_57_PORT=33057
+          TEST_MYSQL_80_PORT=33080
+          TEST_MYSQL_84_PORT=33084
+          TEST_MYSQL_90_PORT=33090
+          # testing MariaDB
+          TEST_MARIADB_55_PORT=33055
+          TEST_MARIADB_101_PORT=33101
+          TEST_MARIADB_102_PORT=33102
+          TEST_MARIADB_103_PORT=33103
+          TEST_MARIADB_104_PORT=33104
+          TEST_MARIADB_105_PORT=33105
+          TEST_MARIADB_106_PORT=33106
+          TEST_MARIADB_1011_PORT=33111
+          TEST_MARIADB_114_PORT=33114
+          TEST_MARIADB_118_PORT=33118
+          TEST_MARIADB_120_PORT=33120
+          # supabase
+          TEST_SUPABASE_HOST=${{ secrets.TEST_SUPABASE_HOST }}
+          TEST_SUPABASE_PORT=${{ secrets.TEST_SUPABASE_PORT }}
+          TEST_SUPABASE_USERNAME=${{ secrets.TEST_SUPABASE_USERNAME }}
+          TEST_SUPABASE_PASSWORD=${{ secrets.TEST_SUPABASE_PASSWORD }}
+          TEST_SUPABASE_DATABASE=${{ secrets.TEST_SUPABASE_DATABASE }}
+          # testing MongoDB
+          TEST_MONGODB_40_PORT=27040
+          TEST_MONGODB_42_PORT=27042
+          TEST_MONGODB_44_PORT=27044
+          TEST_MONGODB_50_PORT=27050
+          TEST_MONGODB_60_PORT=27060
+          TEST_MONGODB_70_PORT=27070
+          TEST_MONGODB_82_PORT=27082
+          # Valkey (cache) - using 172.17.0.1
+          VALKEY_HOST=172.17.0.1
+          VALKEY_PORT=6379
+          VALKEY_USERNAME=
+          VALKEY_PASSWORD=
+          VALKEY_IS_SSL=false
+          # Host for test databases (container -> host)
+          TEST_DB_HOST=172.17.0.1
           EOF
 
       - name: Start test containers
@@ -149,42 +338,251 @@ jobs:
           # Wait for main dev database
           timeout 60 bash -c 'until docker exec dev-db pg_isready -h localhost -p 5437 -U postgres; do sleep 2; done'
 
-          # Wait for test databases
-          timeout 60 bash -c 'until nc -z localhost 5001; do sleep 2; done'
-          timeout 60 bash -c 'until nc -z localhost 5002; do sleep 2; done'
-          timeout 60 bash -c 'until nc -z localhost 5003; do sleep 2; done'
-          timeout 60 bash -c 'until nc -z localhost 5004; do sleep 2; done'
-          timeout 60 bash -c 'until nc -z localhost 5005; do sleep 2; done'
+          # Wait for Valkey (cache)
+          echo "Waiting for Valkey..."
+          timeout 60 bash -c 'until docker exec dev-valkey valkey-cli ping 2>/dev/null | grep -q PONG; do sleep 2; done'
+          echo "Valkey is ready!"
+
+          # Wait for test databases (using 172.17.0.1 from container)
+          timeout 60 bash -c 'until nc -z 172.17.0.1 5000; do sleep 2; done'
+          timeout 60 bash -c 'until nc -z 172.17.0.1 5001; do sleep 2; done'
+          timeout 60 bash -c 'until nc -z 172.17.0.1 5002; do sleep 2; done'
+          timeout 60 bash -c 'until nc -z 172.17.0.1 5003; do sleep 2; done'
+          timeout 60 bash -c 'until nc -z 172.17.0.1 5004; do sleep 2; done'
+          timeout 60 bash -c 'until nc -z 172.17.0.1 5005; do sleep 2; done'
 
           # Wait for MinIO
-          timeout 60 bash -c 'until nc -z localhost 9000; do sleep 2; done'
+          timeout 60 bash -c 'until nc -z 172.17.0.1 9000; do sleep 2; done'
 
-      - name: Install PostgreSQL client tools
+          # Wait for Azurite
+          timeout 60 bash -c 'until nc -z 172.17.0.1 10000; do sleep 2; done'
+
+          # Wait for FTP
+          timeout 60 bash -c 'until nc -z 172.17.0.1 7007; do sleep 2; done'
+
+          # Wait for SFTP
+          timeout 60 bash -c 'until nc -z 172.17.0.1 7008; do sleep 2; done'
+
+          # Wait for MySQL containers
+          echo "Waiting for MySQL 5.7..."
+          timeout 120 bash -c 'until docker exec test-mysql-57 mysqladmin ping -h localhost -u root -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MySQL 8.0..."
+          timeout 120 bash -c 'until docker exec test-mysql-80 mysqladmin ping -h localhost -u root -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MySQL 8.4..."
+          timeout 120 bash -c 'until docker exec test-mysql-84 mysqladmin ping -h localhost -u root -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MySQL 9.0..."
+          timeout 120 bash -c 'until docker exec test-mysql-90 mysqladmin ping -h localhost -u root -prootpassword --silent 2>/dev/null; do sleep 2; done'
+
+          # Wait for MariaDB containers
+          echo "Waiting for MariaDB 5.5..."
+          timeout 120 bash -c 'until docker exec test-mariadb-55 mysqladmin ping -h localhost -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.1..."
+          timeout 120 bash -c 'until docker exec test-mariadb-101 mysqladmin ping -h localhost -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.2..."
+          timeout 120 bash -c 'until docker exec test-mariadb-102 mysqladmin ping -h localhost -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.3..."
+          timeout 120 bash -c 'until docker exec test-mariadb-103 mysqladmin ping -h localhost -prootpassword --silent 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.4..."
+          timeout 120 bash -c 'until docker exec test-mariadb-104 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.5..."
+          timeout 120 bash -c 'until docker exec test-mariadb-105 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.6..."
+          timeout 120 bash -c 'until docker exec test-mariadb-106 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 10.11..."
+          timeout 120 bash -c 'until docker exec test-mariadb-1011 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 11.4..."
+          timeout 120 bash -c 'until docker exec test-mariadb-114 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 11.8..."
+          timeout 120 bash -c 'until docker exec test-mariadb-118 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MariaDB 12.0..."
+          timeout 120 bash -c 'until docker exec test-mariadb-120 healthcheck.sh --connect --innodb_initialized 2>/dev/null; do sleep 2; done'
+
+          # Wait for MongoDB containers
+          echo "Waiting for MongoDB 4.0..."
+          timeout 120 bash -c 'until docker exec test-mongodb-40 mongo --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MongoDB 4.2..."
+          timeout 120 bash -c 'until docker exec test-mongodb-42 mongo --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MongoDB 4.4..."
+          timeout 120 bash -c 'until docker exec test-mongodb-44 mongo --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MongoDB 5.0..."
+          timeout 120 bash -c 'until docker exec test-mongodb-50 mongosh --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MongoDB 6.0..."
+          timeout 120 bash -c 'until docker exec test-mongodb-60 mongosh --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MongoDB 7.0..."
+          timeout 120 bash -c 'until docker exec test-mongodb-70 mongosh --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+          echo "Waiting for MongoDB 8.2..."
+          timeout 120 bash -c 'until docker exec test-mongodb-82 mongosh --eval "db.adminCommand(\"ping\")" -u root -p rootpassword --authenticationDatabase admin 2>/dev/null; do sleep 2; done'
+
+      - name: Create data and temp directories
+        run: |
+          # Create directories that are used for backups and restore
+          # These paths match what's configured in config.go
+          mkdir -p databasus-data/backups
+          mkdir -p databasus-data/temp
+
+      - name: Install database client dependencies
+        run: |
+          apt-get update -qq
+          apt-get install -y -qq libncurses6 libpq5
+          ln -sf /usr/lib/x86_64-linux-gnu/libncurses.so.6 /usr/lib/x86_64-linux-gnu/libncurses.so.5 || true
+          ln -sf /usr/lib/x86_64-linux-gnu/libtinfo.so.6 /usr/lib/x86_64-linux-gnu/libtinfo.so.5 || true
+
+      - name: Setup PostgreSQL, MySQL and MariaDB client tools from pre-built assets
         run: |
-          chmod +x backend/tools/download_linux.sh
           cd backend/tools
-          ./download_linux.sh
+
+          # Create directory structure
+          mkdir -p postgresql mysql mariadb mongodb/bin
+
+          # Copy PostgreSQL client tools (12-18) from pre-built assets
+          for version in 12 13 14 15 16 17 18; do
+            mkdir -p postgresql/postgresql-$version
+            cp -r ../../assets/tools/x64/postgresql/postgresql-$version/bin postgresql/postgresql-$version/
+          done
+
+          # Copy MySQL client tools (5.7, 8.0, 8.4, 9) from pre-built assets
+          for version in 5.7 8.0 8.4 9; do
+            mkdir -p mysql/mysql-$version
+            cp -r ../../assets/tools/x64/mysql/mysql-$version/bin mysql/mysql-$version/
+          done
+
+          # Copy MariaDB client tools (10.6, 12.1) from pre-built assets
+          for version in 10.6 12.1; do
+            mkdir -p mariadb/mariadb-$version
+            cp -r ../../assets/tools/x64/mariadb/mariadb-$version/bin mariadb/mariadb-$version/
+          done
+
+          # Make all binaries executable
+          chmod +x postgresql/*/bin/*
+          chmod +x mysql/*/bin/*
+          chmod +x mariadb/*/bin/*
+
+          echo "Pre-built client tools setup complete"
+
+      - name: Install MongoDB Database Tools
+        run: |
+          cd backend/tools
+
+          # MongoDB Database Tools must be downloaded (not in pre-built assets)
+          # They are backward compatible - single version supports all servers (4.0-8.0)
+          MONGODB_TOOLS_URL="https://fastdl.mongodb.org/tools/db/mongodb-database-tools-debian12-x86_64-100.10.0.deb"
+
+          echo "Downloading MongoDB Database Tools..."
+          wget -q "$MONGODB_TOOLS_URL" -O /tmp/mongodb-database-tools.deb
+
+          echo "Installing MongoDB Database Tools..."
+          dpkg -i /tmp/mongodb-database-tools.deb || apt-get install -f -y --no-install-recommends
+
+          # Create symlinks to tools directory
+          ln -sf /usr/bin/mongodump mongodb/bin/mongodump
+          ln -sf /usr/bin/mongorestore mongodb/bin/mongorestore
+
+          rm -f /tmp/mongodb-database-tools.deb
+          echo "MongoDB Database Tools installed successfully"
+
+      - name: Verify MariaDB client tools exist
+        run: |
+          cd backend/tools
+          echo "Checking MariaDB client tools..."
+          if [ -f "mariadb/mariadb-10.6/bin/mariadb-dump" ]; then
+            echo "MariaDB 10.6 client tools found"
+            ls -la mariadb/mariadb-10.6/bin/
+          else
+            echo "MariaDB 10.6 client tools NOT found"
+          fi
+          if [ -f "mariadb/mariadb-12.1/bin/mariadb-dump" ]; then
+            echo "MariaDB 12.1 client tools found"
+            ls -la mariadb/mariadb-12.1/bin/
+          else
+            echo "MariaDB 12.1 client tools NOT found"
+          fi
+
+      - name: Verify MongoDB Database Tools exist
+        run: |
+          cd backend/tools
+          echo "Checking MongoDB Database Tools..."
+          if [ -f "mongodb/bin/mongodump" ]; then
+            echo "MongoDB Database Tools found"
+            ls -la mongodb/bin/
+            mongodb/bin/mongodump --version || true
+          else
+            echo "MongoDB Database Tools NOT found"
+          fi
 
       - name: Run database migrations
         run: |
           cd backend
-          go install github.com/pressly/goose/v3/cmd/goose@latest
+          go install github.com/pressly/goose/v3/cmd/goose@v3.24.3
           goose up
 
       - name: Run Go tests
         run: |
           cd backend
-          go test ./internal/...
+          go test -p=1 -count=1 -failfast -timeout 10m ./internal/...
 
       - name: Stop test containers
         if: always()
         run: |
           cd backend
+          # Stop and remove containers (keeping images for next run)
           docker compose -f docker-compose.yml.example down -v
 
+          # Clean up all data directories created by docker-compose
+          echo "Cleaning up data directories..."
+          rm -rf pgdata || true
+          rm -rf valkey-data || true
+          rm -rf mysqldata || true
+          rm -rf mariadbdata || true
+          rm -rf temp/nas || true
+          rm -rf databasus-data || true
+
+          # Also clean root-level databasus-data if exists
+          cd ..
+          rm -rf databasus-data || true
+
+          echo "Cleanup complete"
+
+  build-and-push-dev:
+    runs-on: self-hosted
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
+    steps:
+      - name: Clean workspace
+        run: |
+          sudo rm -rf "$GITHUB_WORKSPACE"/* || true
+          sudo rm -rf "$GITHUB_WORKSPACE"/.* || true
+
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU (enables multi-arch emulation)
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push dev image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          build-args: |
+            APP_VERSION=dev-${{ github.sha }}
+          tags: |
+            databasus/databasus-dev:latest
+            databasus/databasus-dev:${{ github.sha }}
+
   determine-version:
-    runs-on: ubuntu-latest
-    needs: [test-backend, lint-frontend]
+    runs-on: self-hosted
+    container:
+      image: node:20
+    needs: [test-backend, test-frontend, test-agent, e2e-agent, e2e-agent-backup-restore]
     if: ${{ github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip-release]') }}
     outputs:
       should_release: ${{ steps.version_bump.outputs.should_release }}
@@ -196,10 +594,9 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
+      - name: Configure Git for container
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
 
       - name: Install semver
         run: npm install -g semver
@@ -213,6 +610,7 @@ jobs:
 
       - name: Analyze commits and determine version bump
         id: version_bump
+        shell: bash
         run: |
           CURRENT_VERSION="${{ steps.current_version.outputs.current_version }}"
           LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
@@ -232,7 +630,7 @@ jobs:
           HAS_FIX=false
           HAS_BREAKING=false
 
-          # Analyze each commit
+          # Analyze each commit - USE PROCESS SUBSTITUTION to avoid subshell variable scope issues
           while IFS= read -r commit; do
             if [[ "$commit" =~ ^FEATURE ]]; then
               HAS_FEATURE=true
@@ -250,7 +648,7 @@ jobs:
               HAS_BREAKING=true
               echo "Found BREAKING CHANGE: $commit"
             fi
-          done <<< "$COMMITS"
+          done < <(printf '%s\n' "$COMMITS")
 
           # Determine version bump
           if [ "$HAS_BREAKING" = true ]; then
@@ -275,43 +673,18 @@ jobs:
             echo "No version bump needed"
           fi
 
-  build-only:
-    runs-on: ubuntu-latest
-    needs: [test-backend, lint-frontend]
-    if: ${{ github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[skip-release]') }}
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v4
-
-      - name: Set up QEMU (enables multi-arch emulation)
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Build and push SHA-only tags
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: |
-            rostislavdugin/postgresus:latest
-            rostislavdugin/postgresus:${{ github.sha }}
-
   build-and-push:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     needs: [determine-version]
     if: ${{ needs.determine-version.outputs.should_release == 'true' }}
     permissions:
       contents: write
     steps:
+      - name: Clean workspace
+        run: |
+          sudo rm -rf "$GITHUB_WORKSPACE"/* || true
+          sudo rm -rf "$GITHUB_WORKSPACE"/.* || true
+
       - name: Check out code
         uses: actions/checkout@v4
 
@@ -333,27 +706,41 @@ jobs:
           context: .
           push: true
           platforms: linux/amd64,linux/arm64
+          build-args: |
+            APP_VERSION=${{ needs.determine-version.outputs.new_version }}
           tags: |
-            rostislavdugin/postgresus:latest
-            rostislavdugin/postgresus:v${{ needs.determine-version.outputs.new_version }}
-            rostislavdugin/postgresus:${{ github.sha }}
+            databasus/databasus:latest
+            databasus/databasus:v${{ needs.determine-version.outputs.new_version }}
+            databasus/databasus:${{ github.sha }}
 
   release:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
+    container:
+      image: node:20
     needs: [determine-version, build-and-push]
     if: ${{ needs.determine-version.outputs.should_release == 'true' }}
     permissions:
       contents: write
       pull-requests: write
     steps:
+      - name: Clean workspace
+        run: |
+          rm -rf "$GITHUB_WORKSPACE"/* || true
+          rm -rf "$GITHUB_WORKSPACE"/.* || true
+
       - name: Check out code
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Configure Git for container
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
       - name: Generate changelog
         id: changelog
+        shell: bash
         run: |
           NEW_VERSION="${{ needs.determine-version.outputs.new_version }}"
           LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
@@ -373,6 +760,7 @@ jobs:
           FIXES=""
           REFACTORS=""
 
+          # USE PROCESS SUBSTITUTION to avoid subshell variable scope issues
           while IFS= read -r line; do
             if [ -n "$line" ]; then
               COMMIT_MSG=$(echo "$line" | cut -d'|' -f1)
@@ -406,7 +794,7 @@ jobs:
                 fi
               fi
             fi
-          done <<< "$COMMITS"
+          done < <(printf '%s\n' "$COMMITS")
 
           # Build changelog sections
           if [ -n "$FEATURES" ]; then
@@ -423,7 +811,7 @@ jobs:
 
           # Add Docker image info
           CHANGELOG="${CHANGELOG}### 🐳 Docker\n"
-          CHANGELOG="${CHANGELOG}- **Image**: \`rostislavdugin/postgresus:v${NEW_VERSION}\`\n"
+          CHANGELOG="${CHANGELOG}- **Image**: \`databasus/databasus:v${NEW_VERSION}\`\n"
           CHANGELOG="${CHANGELOG}- **Platforms**: linux/amd64, linux/arm64\n\n"
 
           # Set output for GitHub release
@@ -443,3 +831,54 @@ jobs:
           body: ${{ steps.changelog.outputs.changelog }}
           draft: false
           prerelease: false
+
+  publish-helm-chart:
+    runs-on: self-hosted
+    container:
+      image: alpine:3.19
+      volumes:
+        - /runner-cache/apk-cache:/etc/apk/cache
+    needs: [determine-version, build-and-push]
+    if: ${{ needs.determine-version.outputs.should_release == 'true' }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Clean workspace
+        run: |
+          rm -rf "$GITHUB_WORKSPACE"/* || true
+          rm -rf "$GITHUB_WORKSPACE"/.* || true
+
+      - name: Install dependencies
+        run: |
+          apk add --no-cache git bash curl
+
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Configure Git for container
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: v3.14.0
+
+      - name: Log in to GHCR
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | helm registry login ghcr.io -u ${{ github.actor }} --password-stdin
+
+      - name: Update Chart.yaml with release version
+        run: |
+          VERSION="${{ needs.determine-version.outputs.new_version }}"
+          sed -i "s/^version: .*/version: ${VERSION}/" deploy/helm/Chart.yaml
+          sed -i "s/^appVersion: .*/appVersion: \"v${VERSION}\"/" deploy/helm/Chart.yaml
+          cat deploy/helm/Chart.yaml
+
+      - name: Package Helm chart
+        run: helm package deploy/helm --destination .
+
+      - name: Push Helm chart to GHCR
+        run: |
+          VERSION="${{ needs.determine-version.outputs.new_version }}"
+          helm push databasus-${VERSION}.tgz oci://ghcr.io/databasus/charts

.gitignore

@@ -1,6 +1,16 @@
+ansible/
 postgresus_data/
 postgresus-data/
+databasus-data/
 .env
 pgdata/
 docker-compose.yml
-node_modules/
+!agent/e2e/docker-compose.yml
+node_modules/
+.idea
+/articles
+
+.DS_Store
+/scripts
+.vscode/settings.json
+.claude

.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+# Pre-commit configuration
+# See https://pre-commit.com for more information
+repos:
+  # Frontend checks
+  - repo: local
+    hooks:
+      - id: frontend-format
+        name: Frontend Format (Prettier)
+        entry: bash -c "cd frontend && npm run format"
+        language: system
+        files: ^frontend/.*\.(ts|tsx|js|jsx|json|css|md)$
+        pass_filenames: false
+
+      - id: frontend-lint
+        name: Frontend Lint (ESLint)
+        entry: bash -c "cd frontend && npm run lint"
+        language: system
+        files: ^frontend/.*\.(ts|tsx|js|jsx)$
+        pass_filenames: false
+
+      - id: frontend-build
+        name: Frontend Build
+        entry: bash -c "cd frontend && npm run build"
+        language: system
+        files: ^frontend/.*\.(ts|tsx|js|jsx|json|css)$
+        pass_filenames: false
+
+  # Backend checks
+  - repo: local
+    hooks:
+      - id: backend-format-and-lint
+        name: Backend Format & Lint (golangci-lint)
+        entry: bash -c "cd backend && golangci-lint fmt ./internal/... ./cmd/... && golangci-lint run ./internal/... ./cmd/..."
+        language: system
+        files: ^backend/.*\.go$
+        pass_filenames: false
+
+      - id: backend-go-mod-tidy
+        name: Backend Go Mod Tidy
+        entry: bash -c "cd backend && go mod tidy"
+        language: system
+        files: ^backend/.*\.go$
+        pass_filenames: false
+
+  # Agent checks
+  - repo: local
+    hooks:
+      - id: agent-format-and-lint
+        name: Agent Format & Lint (golangci-lint)
+        entry: bash -c "cd agent && golangci-lint fmt ./internal/... ./cmd/... && golangci-lint run ./internal/... ./cmd/..."
+        language: system
+        files: ^agent/.*\.go$
+        pass_filenames: false
+
+      - id: agent-go-mod-tidy
+        name: Agent Go Mod Tidy
+        entry: bash -c "cd agent && go mod tidy"
+        language: system
+        files: ^agent/.*\.go$
+        pass_filenames: false

CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+title: Databasus
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - family-names: Dugin
+    given-names: Rostislav
+repository-code: https://github.com/databasus/databasus
+url: https://databasus.com
+abstract: "Free, open source and self-hosted solution for automated databases backups with multiple storage options and notifications."
+keywords:
+  - docker
+  - kubernetes
+  - golang
+  - backups
+  - postgres
+  - devops
+  - backup
+  - database
+  - tools
+  - monitoring
+  - ftp
+  - postgresql
+  - s3
+  - psql
+  - web-ui
+  - self-hosted
+  - pg
+  - system-administration
+  - database-backup
+  - mysql
+  - mongodb
+  - mariadb
+license: Apache-2.0
+version: 2.21.0
+date-released: "2026-01-05"

CLAUDE.md

@@ -0,0 +1 @@
+Look at @AGENTS.md

Dockerfile

@@ -3,24 +3,40 @@ FROM --platform=$BUILDPLATFORM node:24-alpine AS frontend-build
 
 WORKDIR /frontend
 
+# Add version for the frontend build
+ARG APP_VERSION=dev
+ENV VITE_APP_VERSION=$APP_VERSION
+
 COPY frontend/package.json frontend/package-lock.json ./
 RUN npm ci
 COPY frontend/ ./
 
 # Copy .env file (with fallback to .env.production.example)
 RUN if [ ! -f .env ]; then \
-      if [ -f .env.production.example ]; then \
-        cp .env.production.example .env; \
-      fi; \
-    fi
+  if [ -f .env.production.example ]; then \
+  cp .env.production.example .env; \
+  fi; \
+  fi
 
 RUN npm run build
 
 # ========= BUILD BACKEND =========
-FROM --platform=$BUILDPLATFORM golang:1.23.3 AS backend-build
+# Backend build stage
+FROM --platform=$BUILDPLATFORM golang:1.26.1 AS backend-build
 
-# Install Go public tools needed in runtime
-RUN curl -fsSL https://raw.githubusercontent.com/pressly/goose/master/install.sh | sh
+# Make TARGET args available early so tools built here match the final image arch
+ARG TARGETOS
+ARG TARGETARCH
+
+# Install Go public tools needed in runtime. Use `go build` for goose so the
+# binary is compiled for the target architecture instead of downloading a
+# prebuilt binary which may have the wrong architecture (causes exec format
+# errors on ARM).
+RUN git clone --depth 1 --branch v3.24.3 https://github.com/pressly/goose.git /tmp/goose && \
+  cd /tmp/goose/cmd/goose && \
+  GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH:-amd64} \
+  go build -o /usr/local/bin/goose . && \
+  rm -rf /tmp/goose
 RUN go install github.com/swaggo/swag/cmd/swag@v1.16.4
 
 # Set working directory
@@ -45,30 +61,188 @@ ARG TARGETOS
 ARG TARGETARCH
 ARG TARGETVARIANT
 RUN CGO_ENABLED=0 \
-    GOOS=$TARGETOS \
-    GOARCH=$TARGETARCH \
-    go build -o /app/main ./cmd/main.go
+  GOOS=$TARGETOS \
+  GOARCH=$TARGETARCH \
+  go build -o /app/main ./cmd/main.go
+
+
+# ========= BUILD AGENT =========
+# Builds the databasus-agent CLI binary for BOTH x86_64 and ARM64.
+# Both architectures are always built because:
+# - Databasus server runs on one arch (e.g. amd64)
+# - The agent runs on remote PostgreSQL servers that may be on a
+#   different arch (e.g. arm64)
+# - The backend serves the correct binary based on the agent's
+#   ?arch= query parameter
+#
+# We cross-compile from the build platform (no QEMU needed) because the
+# agent is pure Go with zero C dependencies.
+# CGO_ENABLED=0 produces fully static binaries — no glibc/musl dependency,
+# so the agent runs on any Linux distro (Alpine, Debian, Ubuntu, RHEL, etc.).
+# APP_VERSION is baked into the binary via -ldflags so the agent can
+# compare its version against the server and auto-update when needed.
+FROM --platform=$BUILDPLATFORM golang:1.26.1 AS agent-build
+
+ARG APP_VERSION=dev
+
+WORKDIR /agent
+
+COPY agent/go.mod ./
+RUN go mod download
+
+COPY agent/ ./
+
+# Build for x86_64 (amd64) — static binary, no glibc dependency
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+    go build -ldflags "-X main.Version=${APP_VERSION}" \
+    -o /agent-binaries/databasus-agent-linux-amd64 ./cmd/main.go
+
+# Build for ARM64 (arm64) — static binary, no glibc dependency
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=arm64 \
+    go build -ldflags "-X main.Version=${APP_VERSION}" \
+    -o /agent-binaries/databasus-agent-linux-arm64 ./cmd/main.go
 
 
 # ========= RUNTIME =========
-FROM --platform=$TARGETPLATFORM debian:bookworm-slim
+FROM debian:bookworm-slim
 
-# Install PostgreSQL server and client tools (versions 13-17)
-RUN apt-get update && apt-get install -y --no-install-recommends \
-       wget ca-certificates gnupg lsb-release sudo gosu && \
-    wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - && \
-    echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
-      > /etc/apt/sources.list.d/pgdg.list && \
-    apt-get update && \
-    apt-get install -y --no-install-recommends \
-       postgresql-17 postgresql-client-13 postgresql-client-14 postgresql-client-15 \
-       postgresql-client-16 postgresql-client-17 && \
-    rm -rf /var/lib/apt/lists/*
+# Add version metadata to runtime image
+ARG APP_VERSION=dev
+ARG TARGETARCH
+LABEL org.opencontainers.image.version=$APP_VERSION
+ENV APP_VERSION=$APP_VERSION
+ENV CONTAINER_ARCH=$TARGETARCH
+
+# Set production mode for Docker containers
+ENV ENV_MODE=production
+
+# ========= STEP 1: Install base packages =========
+RUN apt-get update
+RUN apt-get install -y --no-install-recommends \
+  wget ca-certificates gnupg lsb-release sudo gosu curl unzip xz-utils libncurses5 libncurses6
+RUN rm -rf /var/lib/apt/lists/*
+
+# ========= Install PostgreSQL client binaries (versions 12-18) =========
+# Pre-downloaded binaries from assets/tools/ - no network download needed
+ARG TARGETARCH
+RUN mkdir -p /usr/lib/postgresql/12/bin /usr/lib/postgresql/13/bin \
+  /usr/lib/postgresql/14/bin /usr/lib/postgresql/15/bin \
+  /usr/lib/postgresql/16/bin /usr/lib/postgresql/17/bin \
+  /usr/lib/postgresql/18/bin
+
+# Copy pre-downloaded PostgreSQL binaries based on architecture
+COPY assets/tools/x64/postgresql/ /tmp/pg-x64/
+COPY assets/tools/arm/postgresql/ /tmp/pg-arm/
+RUN if [ "$TARGETARCH" = "amd64" ]; then \
+  cp -r /tmp/pg-x64/postgresql-12/bin/* /usr/lib/postgresql/12/bin/ && \
+  cp -r /tmp/pg-x64/postgresql-13/bin/* /usr/lib/postgresql/13/bin/ && \
+  cp -r /tmp/pg-x64/postgresql-14/bin/* /usr/lib/postgresql/14/bin/ && \
+  cp -r /tmp/pg-x64/postgresql-15/bin/* /usr/lib/postgresql/15/bin/ && \
+  cp -r /tmp/pg-x64/postgresql-16/bin/* /usr/lib/postgresql/16/bin/ && \
+  cp -r /tmp/pg-x64/postgresql-17/bin/* /usr/lib/postgresql/17/bin/ && \
+  cp -r /tmp/pg-x64/postgresql-18/bin/* /usr/lib/postgresql/18/bin/; \
+  elif [ "$TARGETARCH" = "arm64" ]; then \
+  cp -r /tmp/pg-arm/postgresql-12/bin/* /usr/lib/postgresql/12/bin/ && \
+  cp -r /tmp/pg-arm/postgresql-13/bin/* /usr/lib/postgresql/13/bin/ && \
+  cp -r /tmp/pg-arm/postgresql-14/bin/* /usr/lib/postgresql/14/bin/ && \
+  cp -r /tmp/pg-arm/postgresql-15/bin/* /usr/lib/postgresql/15/bin/ && \
+  cp -r /tmp/pg-arm/postgresql-16/bin/* /usr/lib/postgresql/16/bin/ && \
+  cp -r /tmp/pg-arm/postgresql-17/bin/* /usr/lib/postgresql/17/bin/ && \
+  cp -r /tmp/pg-arm/postgresql-18/bin/* /usr/lib/postgresql/18/bin/; \
+  fi && \
+  rm -rf /tmp/pg-x64 /tmp/pg-arm && \
+  chmod +x /usr/lib/postgresql/*/bin/*
+
+# Install PostgreSQL 17 server (needed for internal database)
+# Add PostgreSQL repository for server installation only
+RUN wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - && \
+  echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
+  > /etc/apt/sources.list.d/pgdg.list && \
+  apt-get update && \
+  apt-get install -y --no-install-recommends postgresql-17 && \
+  rm -rf /var/lib/apt/lists/*
+
+# Install Valkey server from debian repository
+# Valkey is only accessible internally (localhost) - not exposed outside container
+RUN wget -O /usr/share/keyrings/greensec.github.io-valkey-debian.key https://greensec.github.io/valkey-debian/public.key && \
+  echo "deb [signed-by=/usr/share/keyrings/greensec.github.io-valkey-debian.key] https://greensec.github.io/valkey-debian/repo $(lsb_release -cs) main" \
+  > /etc/apt/sources.list.d/valkey-debian.list && \
+  apt-get update && \
+  apt-get install -y --no-install-recommends valkey && \
+  rm -rf /var/lib/apt/lists/*
+
+# ========= Install rclone =========
+RUN apt-get update && \
+  apt-get install -y --no-install-recommends rclone && \
+  rm -rf /var/lib/apt/lists/*
+
+# Create directories for all database clients
+RUN mkdir -p /usr/local/mysql-5.7/bin /usr/local/mysql-8.0/bin /usr/local/mysql-8.4/bin \
+  /usr/local/mysql-9/bin \
+  /usr/local/mariadb-10.6/bin /usr/local/mariadb-12.1/bin \
+  /usr/local/mongodb-database-tools/bin
+
+# ========= Install MySQL clients (5.7, 8.0, 8.4, 9) =========
+# Pre-downloaded binaries from assets/tools/ - no network download needed
+# Note: MySQL 5.7 is only available for x86_64
+# Note: MySQL binaries require libncurses5 for terminal handling
+COPY assets/tools/x64/mysql/ /tmp/mysql-x64/
+COPY assets/tools/arm/mysql/ /tmp/mysql-arm/
+RUN if [ "$TARGETARCH" = "amd64" ]; then \
+  cp /tmp/mysql-x64/mysql-5.7/bin/* /usr/local/mysql-5.7/bin/ && \
+  cp /tmp/mysql-x64/mysql-8.0/bin/* /usr/local/mysql-8.0/bin/ && \
+  cp /tmp/mysql-x64/mysql-8.4/bin/* /usr/local/mysql-8.4/bin/ && \
+  cp /tmp/mysql-x64/mysql-9/bin/* /usr/local/mysql-9/bin/; \
+  elif [ "$TARGETARCH" = "arm64" ]; then \
+  echo "MySQL 5.7 not available for arm64, skipping..." && \
+  cp /tmp/mysql-arm/mysql-8.0/bin/* /usr/local/mysql-8.0/bin/ && \
+  cp /tmp/mysql-arm/mysql-8.4/bin/* /usr/local/mysql-8.4/bin/ && \
+  cp /tmp/mysql-arm/mysql-9/bin/* /usr/local/mysql-9/bin/; \
+  fi && \
+  rm -rf /tmp/mysql-x64 /tmp/mysql-arm && \
+  chmod +x /usr/local/mysql-*/bin/*
+
+# ========= Install MariaDB clients (10.6, 12.1) =========
+# Pre-downloaded binaries from assets/tools/ - no network download needed
+# 10.6 (legacy): For older servers (5.5, 10.1) that don't have generation_expression column
+# 12.1 (modern): For newer servers (10.2+)
+COPY assets/tools/x64/mariadb/ /tmp/mariadb-x64/
+COPY assets/tools/arm/mariadb/ /tmp/mariadb-arm/
+RUN if [ "$TARGETARCH" = "amd64" ]; then \
+  cp /tmp/mariadb-x64/mariadb-10.6/bin/* /usr/local/mariadb-10.6/bin/ && \
+  cp /tmp/mariadb-x64/mariadb-12.1/bin/* /usr/local/mariadb-12.1/bin/; \
+  elif [ "$TARGETARCH" = "arm64" ]; then \
+  cp /tmp/mariadb-arm/mariadb-10.6/bin/* /usr/local/mariadb-10.6/bin/ && \
+  cp /tmp/mariadb-arm/mariadb-12.1/bin/* /usr/local/mariadb-12.1/bin/; \
+  fi && \
+  rm -rf /tmp/mariadb-x64 /tmp/mariadb-arm && \
+  chmod +x /usr/local/mariadb-*/bin/*
+
+# ========= Install MongoDB Database Tools =========
+# Note: MongoDB Database Tools are backward compatible - single version supports all server versions (4.0-8.0)
+# Note: For ARM64, we use Ubuntu 22.04 package as MongoDB doesn't provide Debian 12 ARM64 packages
+RUN apt-get update && \
+  if [ "$TARGETARCH" = "amd64" ]; then \
+  wget -q https://fastdl.mongodb.org/tools/db/mongodb-database-tools-debian12-x86_64-100.10.0.deb -O /tmp/mongodb-database-tools.deb; \
+  elif [ "$TARGETARCH" = "arm64" ]; then \
+  wget -q https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2204-arm64-100.10.0.deb -O /tmp/mongodb-database-tools.deb; \
+  fi && \
+  dpkg -i /tmp/mongodb-database-tools.deb || apt-get install -f -y --no-install-recommends && \
+  rm -f /tmp/mongodb-database-tools.deb && \
+  rm -rf /var/lib/apt/lists/* && \
+  mkdir -p /usr/local/mongodb-database-tools/bin && \
+  if [ -f /usr/bin/mongodump ]; then \
+  ln -sf /usr/bin/mongodump /usr/local/mongodb-database-tools/bin/mongodump; \
+  fi && \
+  if [ -f /usr/bin/mongorestore ]; then \
+  ln -sf /usr/bin/mongorestore /usr/local/mongodb-database-tools/bin/mongorestore; \
+  fi
 
 # Create postgres user and set up directories
-RUN useradd -m -s /bin/bash postgres || true && \
-    mkdir -p /postgresus-data/pgdata && \
-    chown -R postgres:postgres /postgresus-data/pgdata
+RUN groupadd -g 999 postgres || true && \
+  useradd -m -s /bin/bash -u 999 -g 999 postgres || true && \
+  mkdir -p /databasus-data/pgdata && \
+  chown -R postgres:postgres /databasus-data/pgdata
 
 WORKDIR /app
 
@@ -84,79 +258,288 @@ COPY backend/migrations ./migrations
 # Copy UI files
 COPY --from=backend-build /app/ui/build ./ui/build
 
+# Copy cloud static HTML template (injected into index.html at startup when IS_CLOUD=true)
+COPY frontend/cloud-root-content.html /app/cloud-root-content.html
+
+# Copy agent binaries (both architectures) — served by the backend
+# at GET /api/v1/system/agent?arch=amd64|arm64
+COPY --from=agent-build /agent-binaries ./agent-binaries
+
 # Copy .env file (with fallback to .env.production.example)
 COPY backend/.env* /app/
 RUN if [ ! -f /app/.env ]; then \
-      if [ -f /app/.env.production.example ]; then \
-        cp /app/.env.production.example /app/.env; \
-      fi; \
-    fi
+  if [ -f /app/.env.production.example ]; then \
+  cp /app/.env.production.example /app/.env; \
+  fi; \
+  fi
 
 # Create startup script
 COPY <<EOF /app/start.sh
 #!/bin/bash
 set -e
 
+# Check for legacy postgresus-data volume mount
+if [ -d "/postgresus-data" ] && [ "\$(ls -A /postgresus-data 2>/dev/null)" ]; then
+    echo ""
+    echo "=========================================="
+    echo "ERROR: Legacy volume detected!"
+    echo "=========================================="
+    echo ""
+    echo "You are using the \`postgresus-data\` folder. It seems you changed the image name from Postgresus to Databasus without changing the volume."
+    echo ""
+    echo "Please either:"
+    echo "  1. Switch back to image rostislavdugin/postgresus:latest (supported until ~Dec 2026)"
+    echo "  2. Read the migration guide: https://databasus.com/installation/#postgresus-migration"
+    echo ""
+    echo "=========================================="
+    exit 1
+fi
+
+# ========= Adjust postgres user UID/GID =========
+PUID=\${PUID:-999}
+PGID=\${PGID:-999}
+
+CURRENT_UID=\$(id -u postgres)
+CURRENT_GID=\$(id -g postgres)
+
+if [ "\$CURRENT_GID" != "\$PGID" ]; then
+    echo "Adjusting postgres group GID from \$CURRENT_GID to \$PGID..."
+    groupmod -o -g "\$PGID" postgres
+fi
+
+if [ "\$CURRENT_UID" != "\$PUID" ]; then
+    echo "Adjusting postgres user UID from \$CURRENT_UID to \$PUID..."
+    usermod -o -u "\$PUID" postgres
+fi
+
 # PostgreSQL 17 binary paths
 PG_BIN="/usr/lib/postgresql/17/bin"
 
-# Ensure proper ownership of data directory
-echo "Setting up data directory permissions..."
-mkdir -p /postgresus-data/pgdata
-chown -R postgres:postgres /postgresus-data
+# Generate runtime configuration for frontend
+echo "Generating runtime configuration..."
 
-# Initialize PostgreSQL if not already initialized
-if [ ! -s "/postgresus-data/pgdata/PG_VERSION" ]; then
-    echo "Initializing PostgreSQL database..."
-    gosu postgres \$PG_BIN/initdb -D /postgresus-data/pgdata --encoding=UTF8 --locale=C.UTF-8
-    
-    # Configure PostgreSQL
-    echo "host all all 127.0.0.1/32 md5" >> /postgresus-data/pgdata/pg_hba.conf
-    echo "local all all trust" >> /postgresus-data/pgdata/pg_hba.conf
-    echo "port = 5437" >> /postgresus-data/pgdata/postgresql.conf
-    echo "listen_addresses = 'localhost'" >> /postgresus-data/pgdata/postgresql.conf
-    echo "shared_buffers = 256MB" >> /postgresus-data/pgdata/postgresql.conf
-    echo "max_connections = 100" >> /postgresus-data/pgdata/postgresql.conf
+# Detect if email is configured (both SMTP_HOST and DATABASUS_URL must be set)
+if [ -n "\${SMTP_HOST:-}" ] && [ -n "\${DATABASUS_URL:-}" ]; then
+  IS_EMAIL_CONFIGURED="true"
+else
+  IS_EMAIL_CONFIGURED="false"
 fi
 
-# Start PostgreSQL in background
-echo "Starting PostgreSQL..."
-gosu postgres \$PG_BIN/postgres -D /postgresus-data/pgdata -p 5437 &
-POSTGRES_PID=\$!
+cat > /app/ui/build/runtime-config.js <<JSEOF
+// Runtime configuration injected at container startup
+// This file is generated dynamically and should not be edited manually
+window.__RUNTIME_CONFIG__ = {
+  IS_CLOUD: '\${IS_CLOUD:-false}',
+  GITHUB_CLIENT_ID: '\${GITHUB_CLIENT_ID:-}',
+  GOOGLE_CLIENT_ID: '\${GOOGLE_CLIENT_ID:-}',
+  IS_EMAIL_CONFIGURED: '\$IS_EMAIL_CONFIGURED',
+  CLOUDFLARE_TURNSTILE_SITE_KEY: '\${CLOUDFLARE_TURNSTILE_SITE_KEY:-}',
+  CONTAINER_ARCH: '\${CONTAINER_ARCH:-unknown}',
+  CLOUD_PRICE_PER_GB: '\${CLOUD_PRICE_PER_GB:-}',
+  CLOUD_PADDLE_CLIENT_TOKEN: '\${CLOUD_PADDLE_CLIENT_TOKEN:-}'
+};
+JSEOF
 
-# Wait for PostgreSQL to be ready
-echo "Waiting for PostgreSQL to be ready..."
+# Inject analytics script if provided (only if not already injected)
+if [ -n "\${ANALYTICS_SCRIPT:-}" ]; then
+  if ! grep -q "rybbit.databasus.com" /app/ui/build/index.html 2>/dev/null; then
+    echo "Injecting analytics script..."
+    sed -i "s#</head>#  \${ANALYTICS_SCRIPT}\\
+  </head>#" /app/ui/build/index.html
+  fi
+fi
+
+# Inject Paddle script if client token is provided (only if not already injected)
+if [ -n "\${CLOUD_PADDLE_CLIENT_TOKEN:-}" ]; then
+  if ! grep -q "cdn.paddle.com" /app/ui/build/index.html 2>/dev/null; then
+    echo "Injecting Paddle script..."
+    sed -i "s#</head>#  <script src=\"https://cdn.paddle.com/paddle/v2/paddle.js\"></script>\\
+  </head>#" /app/ui/build/index.html
+  fi
+fi
+
+# Inject static HTML into root div for cloud mode (payment system requires visible legal links)
+if [ "\${IS_CLOUD:-false}" = "true" ]; then
+  if ! grep -q "cloud-static-content" /app/ui/build/index.html 2>/dev/null; then
+    echo "Injecting cloud static HTML content..."
+    perl -i -pe '
+      BEGIN {
+        open my \$fh, "<", "/app/cloud-root-content.html" or die;
+        local \$/;
+        \$c = <\$fh>;
+        close \$fh;
+        \$c =~ s/\\n/ /g;
+      }
+      s/<div id="root"><\\/div>/<div id="root"><!-- cloud-static-content --><noscript>\$c<\\/noscript><\\/div>/
+    ' /app/ui/build/index.html
+  fi
+fi
+
+# Ensure proper ownership of data directory
+echo "Setting up data directory permissions..."
+mkdir -p /databasus-data/pgdata
+mkdir -p /databasus-data/temp
+mkdir -p /databasus-data/backups
+chown -R postgres:postgres /databasus-data
+chmod 700 /databasus-data/temp
+
+# ========= Start Valkey (internal cache) =========
+echo "Configuring Valkey cache..."
+cat > /tmp/valkey.conf << 'VALKEY_CONFIG'
+port 6379
+bind 127.0.0.1
+protected-mode yes
+save ""
+maxmemory 256mb
+maxmemory-policy allkeys-lru
+VALKEY_CONFIG
+
+echo "Starting Valkey..."
+valkey-server /tmp/valkey.conf &
+VALKEY_PID=\$!
+
+echo "Waiting for Valkey to be ready..."
 for i in {1..30}; do
-    if gosu postgres \$PG_BIN/pg_isready -p 5437 -h localhost >/dev/null 2>&1; then
-        echo "PostgreSQL is ready!"
+    if valkey-cli ping >/dev/null 2>&1; then
+        echo "Valkey is ready!"
         break
     fi
-    if [ \$i -eq 30 ]; then
-        echo "PostgreSQL failed to start"
-        exit 1
-    fi
     sleep 1
 done
 
+# Initialize PostgreSQL if not already initialized
+if [ ! -s "/databasus-data/pgdata/PG_VERSION" ]; then
+    echo "Initializing PostgreSQL database..."
+    gosu postgres \$PG_BIN/initdb -D /databasus-data/pgdata --encoding=UTF8 --locale=C.UTF-8
+    
+    # Configure PostgreSQL
+    echo "host all all 127.0.0.1/32 md5" >> /databasus-data/pgdata/pg_hba.conf
+    echo "local all all trust" >> /databasus-data/pgdata/pg_hba.conf
+    echo "port = 5437" >> /databasus-data/pgdata/postgresql.conf
+    echo "listen_addresses = 'localhost'" >> /databasus-data/pgdata/postgresql.conf
+    echo "shared_buffers = 256MB" >> /databasus-data/pgdata/postgresql.conf
+    echo "max_connections = 100" >> /databasus-data/pgdata/postgresql.conf
+fi
+
+# Function to start PostgreSQL and wait for it to be ready
+start_postgres() {
+    echo "Starting PostgreSQL..."
+    # -k /tmp: create Unix socket and lock file in /tmp instead of /var/run/postgresql/.
+    # On NAS systems (e.g. TrueNAS Scale), the ZFS-backed Docker overlay filesystem
+    # ignores chown/chmod on directories from image layers, so PostgreSQL gets
+    # "Permission denied" when creating .s.PGSQL.5437.lock in /var/run/postgresql/.
+    # All internal connections use TCP (-h localhost), so the socket location does not matter.
+    gosu postgres \$PG_BIN/postgres -D /databasus-data/pgdata -p 5437 -k /tmp &
+    POSTGRES_PID=\$!
+    
+    echo "Waiting for PostgreSQL to be ready..."
+    for i in {1..30}; do
+        if gosu postgres \$PG_BIN/pg_isready -p 5437 -h localhost >/dev/null 2>&1; then
+            echo "PostgreSQL is ready!"
+            return 0
+        fi
+        sleep 1
+    done
+    return 1
+}
+
+# Try to start PostgreSQL
+if ! start_postgres; then
+    echo ""
+    echo "=========================================="
+    echo "PostgreSQL failed to start. Attempting WAL reset recovery..."
+    echo "=========================================="
+    echo ""
+    
+    # Kill any remaining postgres processes
+    pkill -9 postgres 2>/dev/null || true
+    sleep 2
+    
+    # Attempt pg_resetwal to recover from WAL corruption
+    echo "Running pg_resetwal to reset WAL..."
+    if gosu postgres \$PG_BIN/pg_resetwal -f /databasus-data/pgdata; then
+        echo "WAL reset successful. Restarting PostgreSQL..."
+        
+        # Try starting PostgreSQL again after WAL reset
+        if start_postgres; then
+            echo "PostgreSQL recovered successfully after WAL reset!"
+        else
+            echo ""
+            echo "=========================================="
+            echo "ERROR: PostgreSQL failed to start even after WAL reset."
+            echo "The database may be severely corrupted."
+            echo ""
+            echo "Options:"
+            echo "  1. Delete the volume and start fresh (data loss)"
+            echo "  2. Manually inspect /databasus-data/pgdata for issues"
+            echo "=========================================="
+            exit 1
+        fi
+    else
+        echo ""
+        echo "=========================================="
+        echo "ERROR: pg_resetwal failed."
+        echo "The database may be severely corrupted."
+        echo ""
+        echo "Options:"
+        echo "  1. Delete the volume and start fresh (data loss)"
+        echo "  2. Manually inspect /databasus-data/pgdata for issues"
+        echo "=========================================="
+        exit 1
+    fi
+fi
+
 # Create database and set password for postgres user
 echo "Setting up database and user..."
 gosu postgres \$PG_BIN/psql -p 5437 -h localhost -d postgres << 'SQL'
+
+-- We use stub password, because internal DB is not exposed outside container
 ALTER USER postgres WITH PASSWORD 'Q1234567';
-CREATE DATABASE "postgresus" OWNER postgres;
-\q
+SELECT 'CREATE DATABASE databasus OWNER postgres'
+WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = 'databasus')
+\\gexec
+\\q
 SQL
 
 # Start the main application
-echo "Starting Postgresus application..."
+echo "Starting Databasus application..."
+
+# Check and warn about external database/Valkey usage
+if [ -n "\${DANGEROUS_EXTERNAL_DATABASE_DSN:-}" ]; then
+    echo ""
+    echo "=========================================="
+    echo "WARNING: Using external database"
+    echo "=========================================="
+    echo "DANGEROUS_EXTERNAL_DATABASE_DSN is set."
+    echo "Application will connect to external PostgreSQL instead of internal instance."
+    echo "Internal PostgreSQL is still running in the background."
+    echo "=========================================="
+    echo ""
+fi
+
+if [ -n "\${DANGEROUS_VALKEY_HOST:-}" ]; then
+    echo ""
+    echo "=========================================="
+    echo "WARNING: Using external Valkey"
+    echo "=========================================="
+    echo "DANGEROUS_VALKEY_HOST is set."
+    echo "Application will connect to external Valkey instead of internal instance."
+    echo "Internal Valkey is still running in the background."
+    echo "=========================================="
+    echo ""
+fi
+
 exec ./main
 EOF
 
+LABEL org.opencontainers.image.source="https://github.com/databasus/databasus"
+
 RUN chmod +x /app/start.sh
 
 EXPOSE 4005
 
 # Volume for PostgreSQL data
-VOLUME ["/postgresus-data"]
+VOLUME ["/databasus-data"]
 
 ENTRYPOINT ["/app/start.sh"]
 CMD []

LICENSE

@@ -1,21 +1,202 @@
-MIT License
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright (c) 2025 Postgresus
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   1. Definitions.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+      "Licensor" shall mean the copyright owner or entity granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (which shall not include communications that are solely written
+      by You).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based upon (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and derivative works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control
+      systems, and issue tracking systems that are managed by, or on behalf
+      of, the Licensor for the purpose of discussing and improving the Work,
+      but excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to use, reproduce, modify, distribute, prepare
+      Derivative Works of, and publicly display, publicly perform,
+      sublicense, and distribute the Work and such Derivative Works in
+      Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright notice to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. When redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "license" line as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Databasus
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE.md

@@ -0,0 +1,22 @@
+Copyright © 2025–2026 Rostislav Dugin and contributors.
+
+“Databasus” is a trademark of Rostislav Dugin.
+
+The source code in this repository is licensed under the Apache License, Version 2.0.
+That license applies to the code only and does not grant any right to use the
+Databasus name, logo, or branding, except for reasonable and customary referential
+use in describing the origin of the software and reproducing the content of this NOTICE.
+
+Permitted referential use includes truthful use of the name “Databasus” to identify
+the original Databasus project in software catalogs, deployment templates, hosting
+panels, package indexes, compatibility pages, integrations, tutorials, reviews, and
+similar informational materials, including phrases such as “Databasus”,
+“Deploy Databasus”, “Databasus on Coolify”, and “Compatible with Databasus”.
+
+You may not use “Databasus” as the name or primary branding of a competing product,
+service, fork, distribution, or hosted offering, or in any manner likely to cause
+confusion as to source, affiliation, sponsorship, or endorsement.
+
+Nothing in this repository transfers, waives, limits, or estops any rights in the
+Databasus mark. All trademark rights are reserved except for the limited referential
+use stated above.

README.md

@@ -1,18 +1,21 @@
 <div align="center">
-  <img src="assets/logo.svg" style="margin-bottom: 20px;" alt="Postgresus Logo" width="250"/>
+  <img src="assets/logo.svg" alt="Databasus Logo" width="250"/>
 
-  <h3>PostgreSQL monitoring and backup</h3>
-  <p>Free, open source and self-hosted solution for automated PostgreSQL monitoring and backups. With multiple storage options and notifications</p>
+  <h3>PostgreSQL backup tool (with MySQL\MariaDB and MongoDB support)</h3>
+  <p>Databasus is a free, open source and self-hosted tool to backup databases (with primary focus on PostgreSQL). Make backups with different storages (S3, Google Drive, FTP, etc.) and notifications about progress (Slack, Discord, Telegram, etc.)</p>
   
   <!-- Badges -->
-  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-  [![Docker Pulls](https://img.shields.io/docker/pulls/rostislavdugin/postgresus?color=brightgreen)](https://hub.docker.com/r/rostislavdugin/postgresus)
-  [![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)](https://github.com/RostislavDugin/postgresus)
-  
-  [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-13%20%7C%2014%20%7C%2015%20%7C%2016%20%7C%2017-336791?logo=postgresql&logoColor=white)](https://www.postgresql.org/)
-  [![Self Hosted](https://img.shields.io/badge/self--hosted-yes-brightgreen)](https://github.com/RostislavDugin/postgresus)
-  [![Open Source](https://img.shields.io/badge/open%20source-❤️-red)](https://github.com/RostislavDugin/postgresus)
-  
+   [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-336791?logo=postgresql&logoColor=white)](https://www.postgresql.org/)
+  [![MySQL](https://img.shields.io/badge/MySQL-4479A1?logo=mysql&logoColor=white)](https://www.mysql.com/)
+  [![MariaDB](https://img.shields.io/badge/MariaDB-003545?logo=mariadb&logoColor=white)](https://mariadb.org/)
+  [![MongoDB](https://img.shields.io/badge/MongoDB-47A248?logo=mongodb&logoColor=white)](https://www.mongodb.com/)
+  <br />
+  [![Apache 2.0 License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+  [![Docker Pulls](https://img.shields.io/docker/pulls/databasus/databasus?color=brightgreen)](https://hub.docker.com/r/databasus/databasus)
+  [![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)](https://github.com/databasus/databasus)
+  [![Self Hosted](https://img.shields.io/badge/self--hosted-yes-brightgreen)](https://github.com/databasus/databasus)
+  [![Open Source](https://img.shields.io/badge/open%20source-❤️-red)](https://github.com/databasus/databasus)
+
   <p>
     <a href="#-features">Features</a> •
     <a href="#-installation">Installation</a> •
@@ -22,118 +25,152 @@
   </p>
 
   <p style="margin-top: 20px; margin-bottom: 20px; font-size: 1.2em;">
-    <a href="https://postgresus.com" target="_blank"><strong>🌐 Postgresus website</strong></a>
+    <a href="https://databasus.com" target="_blank"><strong>🌐 Databasus website</strong></a>
   </p>
   
-  <img src="assets/dashboard.svg" alt="Postgresus Dashboard" width="800"/>
-  
- 
+  <img src="assets/dashboard-dark.svg" alt="Databasus Dark Dashboard" width="800" style="margin-bottom: 10px;"/>
+
+  <img src="assets/dashboard.svg" alt="Databasus Dashboard" width="800"/>
 </div>
 
 ---
 
 ## ✨ Features
 
-### 🔄 **Scheduled Backups**
+### 💾 **Supported databases**
 
-- **Flexible scheduling**: hourly, daily, weekly, monthly
+- **PostgreSQL**: 12, 13, 14, 15, 16, 17 and 18
+- **MySQL**: 5.7, 8 and 9
+- **MariaDB**: 10, 11 and 12
+- **MongoDB**: 4, 5, 6, 7 and 8
+
+### 🔄 **Scheduled backups**
+
+- **Flexible scheduling**: hourly, daily, weekly, monthly or cron
 - **Precise timing**: run backups at specific times (e.g., 4 AM during low traffic)
 - **Smart compression**: 4-8x space savings with balanced compression (~20% overhead)
 
-### 🗄️ **Multiple Storage Destinations**
+### 🗑️ **Retention policies**
+
+- **Time period**: Keep backups for a fixed duration (e.g., 7 days, 3 months, 1 year)
+- **Count**: Keep a fixed number of the most recent backups (e.g., last 30)
+- **GFS (Grandfather-Father-Son)**: Layered retention — keep hourly, daily, weekly, monthly and yearly backups independently for fine-grained long-term history (enterprises requirement)
+- **Size limits**: Set per-backup and total storage size caps to control storage usage
+
+### 🗄️ **Multiple storage destinations** <a href="https://databasus.com/storages">(view supported)</a>
 
 - **Local storage**: Keep backups on your VPS/server
-- **Cloud storage**: S3, Cloudflare R2, Google Drive, NAS, Dropbox and more
+- **Cloud storage**: S3, Cloudflare R2, Google Drive, NAS, Dropbox, SFTP, Rclone and more
 - **Secure**: All data stays under your control
 
-### 📱 **Smart Notifications**
+### 📱 **Smart notifications** <a href="https://databasus.com/notifiers">(view supported)</a>
 
 - **Multiple channels**: Email, Telegram, Slack, Discord, webhooks
 - **Real-time updates**: Success and failure notifications
 - **Team integration**: Perfect for DevOps workflows
 
-### 🐘 **PostgreSQL Support**
+### 🔒 **Enterprise-grade security** <a href="https://databasus.com/security">(docs)</a>
 
-- **Multiple versions**: PostgreSQL 13, 14, 15, 16 and 17
-- **SSL support**: Secure connections available
-- **Easy restoration**: One-click restore from any backup
+- **AES-256-GCM encryption**: Enterprise-grade protection for backup files
+- **Zero-trust storage**: Backups are encrypted and remain useless to attackers, so you can safely store them in shared storage like S3, Azure Blob Storage, etc.
+- **Encryption for secrets**: Any sensitive data is encrypted and never exposed, even in logs or error messages
+- **Read-only user**: Databasus uses a read-only user by default for backups and never stores anything that can modify your data
 
-### 🐳 **Self-Hosted & Secure**
+It is also important for Databasus that you are able to decrypt and restore backups from storages (local, S3, etc.) without Databasus itself. To do so, read our guide on [how to recover directly from storage](https://databasus.com/how-to-recover-without-databasus). We avoid "vendor lock-in" even to open source tool!
+
+### 👥 **Suitable for teams** <a href="https://databasus.com/access-management">(docs)</a>
+
+- **Workspaces**: Group databases, notifiers and storages for different projects or teams
+- **Access management**: Control who can view or manage specific databases with role-based permissions
+- **Audit logs**: Track all system activities and changes made by users
+- **User roles**: Assign viewer, member, admin or owner roles within workspaces
+
+### 🎨 **UX-Friendly**
+
+- **Designer-polished UI**: Clean, intuitive interface crafted with attention to detail
+- **Dark & light themes**: Choose the look that suits your workflow
+- **Mobile adaptive**: Check your backups from anywhere on any device
+
+### 🔌 **Connection types**
+
+- **Remote** — Databasus connects directly to the database over the network (recommended in read-only mode). No agent or additional software required. Works with cloud-managed and self-hosted databases
+- **Agent** — A lightweight Databasus agent (written in Go) runs alongside the database. The agent streams backups directly to Databasus, so the database never needs to be exposed publicly. Supports host-installed databases and Docker containers
+
+### 📦 **Backup types**
+
+- **Logical** — Native dump of the database in its engine-specific binary format. Compressed and streamed directly to storage with no intermediate files
+- **Physical** — File-level copy of the entire database cluster. Faster backup and restore for large datasets compared to logical dumps
+- **Incremental** — Physical base backup combined with continuous WAL segment archiving. Enables Point-in-time recovery (PITR) — restore to any second between backups. Designed for disaster recovery and near-zero data loss requirements
+
+### 🐳 **Self-hosted & secure**
 
 - **Docker-based**: Easy deployment and management
 - **Privacy-first**: All your data stays on your infrastructure
-- **Open source**: MIT licensed, inspect every line of code
+- **Open source**: Apache 2.0 licensed, inspect every line of code
 
-### 📊 **Monitoring & Insights**
+### 📦 Installation <a href="https://databasus.com/installation">(docs)</a>
 
-- **Real-time metrics**: Track database health
-- **Historical data**: View trends and patterns over time
-- **Alert system**: Get notified when issues are detected
+You have four ways to install Databasus:
 
-### 📦 Installation
-
-You have three ways to install Postgresus:
-
-- Script (recommended)
+- Automated script (recommended)
 - Simple Docker run
 - Docker Compose setup
+- Kubernetes with Helm
 
-<img src="assets/healthchecks.svg" alt="Postgresus Dashboard" width="800"/>
+<img src="assets/healthchecks.svg" alt="Databasus Dashboard" width="800"/>
 
 ---
 
 ## 📦 Installation
 
-You have three ways to install Postgresus: automated script (recommended), simple Docker run, or Docker Compose setup.
+You have four ways to install Databasus: automated script (recommended), simple Docker run, or Docker Compose setup.
 
-### Option 1: Automated Installation Script (Recommended, Linux only)
+### Option 1: Automated installation script (recommended, Linux only)
 
 The installation script will:
 
-- ✅ Install Docker with Docker Compose(if not already installed)
-- ✅ Set up Postgresus
+- ✅ Install Docker with Docker Compose (if not already installed)
+- ✅ Set up Databasus
 - ✅ Configure automatic startup on system reboot
 
 ```bash
 sudo apt-get install -y curl && \
-sudo curl -sSL https://raw.githubusercontent.com/RostislavDugin/postgresus/refs/heads/main/install-postgresus.sh \
+sudo curl -sSL https://raw.githubusercontent.com/databasus/databasus/refs/heads/main/install-databasus.sh \
 | sudo bash
 ```
 
-### Option 2: Simple Docker Run
+### Option 2: Simple Docker run
 
-The easiest way to run Postgresus with embedded PostgreSQL:
+The easiest way to run Databasus:
 
 ```bash
 docker run -d \
-  --name postgresus \
+  --name databasus \
   -p 4005:4005 \
-  -v ./postgresus-data:/postgresus-data \
+  -v ./databasus-data:/databasus-data \
   --restart unless-stopped \
-  rostislavdugin/postgresus:latest
+  databasus/databasus:latest
 ```
 
 This single command will:
 
-- ✅ Start Postgresus
-- ✅ Store all data in `./postgresus-data` directory
+- ✅ Start Databasus
+- ✅ Store all data in `./databasus-data` directory
 - ✅ Automatically restart on system reboot
 
-### Option 3: Docker Compose Setup
+### Option 3: Docker Compose setup
 
 Create a `docker-compose.yml` file with the following configuration:
 
 ```yaml
-version: "3"
-
 services:
-  postgresus:
-    container_name: postgresus
-    image: rostislavdugin/postgresus:latest
+  databasus:
+    container_name: databasus
+    image: databasus/databasus:latest
     ports:
       - "4005:4005"
     volumes:
-      - ./postgresus-data:/postgresus-data
+      - ./databasus-data:/databasus-data
     restart: unless-stopped
 ```
 
@@ -143,34 +180,130 @@ Then run:
 docker compose up -d
 ```
 
+### Option 4: Kubernetes with Helm
+
+For Kubernetes deployments, install directly from the OCI registry.
+
+**With ClusterIP + port-forward (development/testing):**
+
+```bash
+helm install databasus oci://ghcr.io/databasus/charts/databasus \
+  -n databasus --create-namespace
+```
+
+```bash
+kubectl port-forward svc/databasus-service 4005:4005 -n databasus
+# Access at http://localhost:4005
+```
+
+**With LoadBalancer (cloud environments):**
+
+```bash
+helm install databasus oci://ghcr.io/databasus/charts/databasus \
+  -n databasus --create-namespace \
+  --set service.type=LoadBalancer
+```
+
+```bash
+kubectl get svc databasus-service -n databasus
+# Access at http://<EXTERNAL-IP>:4005
+```
+
+**With Ingress (domain-based access):**
+
+```bash
+helm install databasus oci://ghcr.io/databasus/charts/databasus \
+  -n databasus --create-namespace \
+  --set ingress.enabled=true \
+  --set ingress.hosts[0].host=backup.example.com
+```
+
+For more options (NodePort, TLS, HTTPRoute for Gateway API), see the [Helm chart README](deploy/helm/README.md).
+
 ---
 
 ## 🚀 Usage
 
 1. **Access the dashboard**: Navigate to `http://localhost:4005`
-2. **Add first DB for backup**: Click "New Database" and follow the setup wizard
-3. **Configure schedule**: Choose from hourly, daily, weekly or monthly intervals
-4. **Set database connection**: Enter your PostgreSQL credentials and connection details
+2. **Add your first database for backup**: Click "New Database" and follow the setup wizard
+3. **Configure schedule**: Choose from hourly, daily, weekly, monthly or cron intervals
+4. **Set database connection**: Enter your database credentials and connection details
 5. **Choose storage**: Select where to store your backups (local, S3, Google Drive, etc.)
-6. **Add notifications** (optional): Configure email, Telegram, Slack, or webhook notifications
-7. **Save and start**: Postgresus will validate settings and begin the backup schedule
+6. **Configure retention policy**: Choose time period, count or GFS to control how long backups are kept
+7. **Add notifications** (optional): Configure email, Telegram, Slack, or webhook notifications
+8. **Save and start**: Databasus will validate settings and begin the backup schedule
 
-### 🔑 Resetting Admin Password
+### 🔑 Resetting password <a href="https://databasus.com/password">(docs)</a>
 
-If you need to reset the admin password, you can use the built-in password reset command:
+If you need to reset the password, you can use the built-in password reset command:
 
 ```bash
-docker exec -it postgresus ./main --new-password="YourNewSecurePassword123"
+docker exec -it databasus ./main --new-password="YourNewSecurePassword123" --email="admin"
 ```
 
+Replace `admin` with the actual email address of the user whose password you want to reset.
+
+### 💾 Backuping Databasus itself
+
+After installation, it is also recommended to <a href="https://databasus.com/faq#backup-databasus">backup your Databasus itself</a> or, at least, to copy secret key used for encryption (30 seconds is needed). So you are able to restore from your encrypted backups if you lose access to the server with Databasus or it is corrupted.
+
 ---
 
 ## 📝 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
+This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details
 
 ## 🤝 Contributing
 
-Contributions are welcome! Read [contributing guide](contribute/readme.md) for more details, prioerities and rules are specified there. If you want to contribute, but don't know what and how - message me on Telegram [@rostislav_dugin](https://t.me/rostislav_dugin)
+Contributions are welcome! Read the <a href="https://databasus.com/contribute">contributing guide</a> for more details, priorities and rules. If you want to contribute but don't know where to start, message me on Telegram [@rostislav_dugin](https://t.me/rostislav_dugin)
+
+Also you can join our large community of developers, DBAs and DevOps engineers on Telegram [@databasus_community](https://t.me/databasus_community).
+
+## FAQ
+
+### AI disclaimer
+
+There have been questions about AI usage in project development in issues and discussions. As the project focuses on security, reliability and production usage, it's important to explain how AI is used in the development process.
+
+First of all, we are proud to say that Databasus has been accepted into both [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) by Anthropic and [Codex for Open Source](https://developers.openai.com/codex/community/codex-for-oss/) by OpenAI in March 2026. For us it is one more signal that the project was recognized as important open-source software and was as critical infrastructure worth supporting independently by two of the world's leading AI companies. Read more at [databasus.com/faq](https://databasus.com/faq#oss-programs).
+
+Despite of this, we have the following rules how AI is used in the development process:
+
+AI is used as a helper for:
+
+- verification of code quality and searching for vulnerabilities
+- cleaning up and improving documentation, comments and code
+- assistance during development
+- double-checking PRs and commits after human review
+- additional security analysis of PRs via Codex Security
+
+AI is not used for:
+
+- writing entire code
+- "vibe code" approach
+- code without line-by-line verification by a human
+- code without tests
+
+The project has:
+
+- solid test coverage (both unit and integration tests)
+- CI/CD pipeline automation with tests and linting to ensure code quality
+- verification by experienced developers with experience in large and secure projects
+
+So AI is just an assistant and a tool for developers to increase productivity and ensure code quality. The work is done by developers.
+
+Moreover, it's important to note that we do not differentiate between bad human code and AI vibe code. There are strict requirements for any code to be merged to keep the codebase maintainable.
+
+Even if code is written manually by a human, it's not guaranteed to be merged. Vibe code is not allowed at all and all such PRs are rejected by default (see [contributing guide](https://databasus.com/contribute)).
+
+We also draw attention to fast issue resolution and security [vulnerability reporting](https://github.com/databasus/databasus?tab=security-ov-file#readme).
+
+### You have a cloud version — are you truly open source?
+
+Yes. Every feature available in Databasus Cloud is equally available in the self-hosted version with no restrictions, no feature gates and no usage limits. The entire codebase is Apache 2.0 licensed and always will be.
+
+Databasus is not "open core." We do not withhold features behind a paid tier and then call the limited remainder "open source," as projects like GitLab or Sentry do. We believe open source means the complete product is open, not just a marketing label on a stripped-down edition.
+
+Databasus Cloud runs the exact same code as the self-hosted version. The only difference is that we take care of infrastructure, availability, backups, reservations, monitoring and updates for you — so you don't have to. If you are using cloud, you can always move your databases from cloud to self-hosted if you wish.
+
+Revenue from Cloud funds full-time development of the project. Most large open-source projects rely on corporate backing or sponsorship to survive. We chose a different path: Databasus sustains itself so it can grow and improve independently, without being tied to any enterprise or sponsor.

agent/.env.example

@@ -0,0 +1,3 @@
+ENV_MODE=development
+AGENT_DB_ID=your-database-id
+AGENT_TOKEN=your-agent-token

agent/.gitignore

@@ -0,0 +1,27 @@
+main
+.env
+docker-compose.yml
+!e2e/docker-compose.yml
+pgdata
+pgdata_test/
+mysqldata/
+mariadbdata/
+main.exe
+swagger/
+swagger/*
+swagger/docs.go
+swagger/swagger.json
+swagger/swagger.yaml
+postgresus-backend.exe
+databasus-backend.exe
+ui/build/*
+pgdata-for-restore/
+temp/
+cmd.exe
+temp/
+valkey-data/
+victoria-logs-data/
+databasus.json
+.test-tmp/
+databasus.log
+wal-queue/

agent/.golangci.yml

@@ -0,0 +1,41 @@
+version: "2"
+
+run:
+  timeout: 5m
+  tests: false
+  concurrency: 4
+
+linters:
+  default: standard
+  enable:
+    - funcorder
+    - bodyclose
+    - errorlint
+    - gocritic
+    - unconvert
+    - misspell
+    - errname
+    - noctx
+    - modernize
+
+  settings:
+    errcheck:
+      check-type-assertions: true
+
+formatters:
+  enable:
+    - gofumpt
+    - golines
+    - gci
+
+  settings:
+    golines:
+      max-len: 120
+    gofumpt:
+      module-path: databasus-agent
+      extra-rules: true
+    gci:
+      sections:
+        - standard
+        - default
+        - localmodule

agent/Makefile

@@ -0,0 +1,41 @@
+.PHONY: run build test lint e2e e2e-clean e2e-backup-restore e2e-backup-restore-clean
+
+-include .env
+export
+
+run:
+	go run cmd/main.go start \
+		--databasus-host http://localhost:4005 \
+		--db-id $(AGENT_DB_ID) \
+		--token $(AGENT_TOKEN) \
+		--pg-host 127.0.0.1 \
+		--pg-port 7433 \
+		--pg-user devuser \
+		--pg-password devpassword \
+		--pg-type docker \
+		--pg-docker-container-name dev-postgres \
+		--pg-wal-dir ./wal-queue \
+		--skip-update
+
+build:
+	CGO_ENABLED=0 go build -ldflags "-X main.Version=$(VERSION)" -o databasus-agent ./cmd/main.go
+
+test:
+	go test -count=1 -failfast ./internal/...
+
+lint:
+	golangci-lint fmt ./cmd/... ./internal/... ./e2e/... && golangci-lint run ./cmd/... ./internal/... ./e2e/...
+
+e2e:
+	cd e2e && docker compose build --no-cache e2e-mock-server
+	cd e2e && docker compose build
+	cd e2e && docker compose run --rm e2e-agent-builder
+	cd e2e && docker compose up -d e2e-postgres e2e-mock-server
+	cd e2e && docker compose run --rm e2e-agent-runner
+	cd e2e && docker compose run --rm e2e-agent-docker
+	cd e2e && docker compose down -v
+
+e2e-clean:
+	cd e2e && docker compose down -v --rmi local
+	cd e2e && docker compose -f docker-compose.backup-restore.yml down -v --rmi local 2>/dev/null || true
+	rm -rf e2e/artifacts

agent/cmd/main.go

@@ -0,0 +1,245 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+
+	"databasus-agent/internal/config"
+	"databasus-agent/internal/features/api"
+	"databasus-agent/internal/features/restore"
+	"databasus-agent/internal/features/start"
+	"databasus-agent/internal/features/upgrade"
+	"databasus-agent/internal/logger"
+)
+
+var Version = "dev"
+
+func main() {
+	if len(os.Args) < 2 {
+		printUsage()
+		os.Exit(1)
+	}
+
+	switch os.Args[1] {
+	case "start":
+		runStart(os.Args[2:])
+	case "_run":
+		runDaemon(os.Args[2:])
+	case "stop":
+		runStop()
+	case "status":
+		runStatus()
+	case "restore":
+		runRestore(os.Args[2:])
+	case "version":
+		fmt.Println(Version)
+	default:
+		fmt.Fprintf(os.Stderr, "unknown command: %s\n", os.Args[1])
+		printUsage()
+		os.Exit(1)
+	}
+}
+
+func runStart(args []string) {
+	fs := flag.NewFlagSet("start", flag.ExitOnError)
+
+	isSkipUpdate := fs.Bool("skip-update", false, "Skip auto-update check")
+
+	cfg := &config.Config{}
+	cfg.LoadFromJSONAndArgs(fs, args)
+
+	if err := cfg.SaveToJSON(); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to save config: %v\n", err)
+	}
+
+	log := logger.GetLogger()
+
+	isDev := checkIsDevelopment()
+	runUpdateCheck(cfg.DatabasusHost, *isSkipUpdate, isDev, log)
+
+	if err := start.Start(cfg, Version, isDev, log); err != nil {
+		if errors.Is(err, upgrade.ErrUpgradeRestart) {
+			reexecAfterUpgrade(log)
+		}
+
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func runDaemon(args []string) {
+	fs := flag.NewFlagSet("_run", flag.ExitOnError)
+
+	if err := fs.Parse(args); err != nil {
+		os.Exit(1)
+	}
+
+	log := logger.GetLogger()
+
+	cfg := &config.Config{}
+	cfg.LoadFromJSON()
+
+	if err := start.RunDaemon(cfg, Version, checkIsDevelopment(), log); err != nil {
+		if errors.Is(err, upgrade.ErrUpgradeRestart) {
+			reexecAfterUpgrade(log)
+		}
+
+		log.Error("Agent exited with error", "error", err)
+		os.Exit(1)
+	}
+}
+
+func runStop() {
+	log := logger.GetLogger()
+
+	if err := start.Stop(log); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func runStatus() {
+	log := logger.GetLogger()
+
+	if err := start.Status(log); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func runRestore(args []string) {
+	fs := flag.NewFlagSet("restore", flag.ExitOnError)
+
+	pgDataDir := fs.String("target-dir", "", "Target pgdata directory (required)")
+	backupID := fs.String("backup-id", "", "Full backup UUID (optional)")
+	targetTime := fs.String("target-time", "", "PITR target time in RFC3339 (optional)")
+	isSkipUpdate := fs.Bool("skip-update", false, "Skip auto-update check")
+
+	cfg := &config.Config{}
+	cfg.LoadFromJSONAndArgs(fs, args)
+
+	if err := cfg.SaveToJSON(); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to save config: %v\n", err)
+	}
+
+	log := logger.GetLogger()
+
+	isDev := checkIsDevelopment()
+	runUpdateCheck(cfg.DatabasusHost, *isSkipUpdate, isDev, log)
+
+	if *pgDataDir == "" {
+		fmt.Fprintln(os.Stderr, "Error: --target-dir is required")
+		os.Exit(1)
+	}
+
+	if cfg.DatabasusHost == "" || cfg.Token == "" {
+		fmt.Fprintln(os.Stderr, "Error: databasus-host and token must be configured")
+		os.Exit(1)
+	}
+
+	if cfg.PgType != "host" && cfg.PgType != "docker" {
+		fmt.Fprintf(os.Stderr, "Error: --pg-type must be 'host' or 'docker', got '%s'\n", cfg.PgType)
+		os.Exit(1)
+	}
+
+	apiClient := api.NewClient(cfg.DatabasusHost, cfg.Token, log)
+	restorer := restore.NewRestorer(apiClient, log, *pgDataDir, *backupID, *targetTime, cfg.PgType)
+
+	ctx := context.Background()
+	if err := restorer.Run(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func printUsage() {
+	fmt.Fprintln(os.Stderr, "Usage: databasus-agent <command> [flags]")
+	fmt.Fprintln(os.Stderr, "")
+	fmt.Fprintln(os.Stderr, "Commands:")
+	fmt.Fprintln(os.Stderr, "  start    Start the agent (WAL archiving + basebackups)")
+	fmt.Fprintln(os.Stderr, "  stop     Stop a running agent")
+	fmt.Fprintln(os.Stderr, "  status   Show agent status")
+	fmt.Fprintln(os.Stderr, "  restore  Restore a database from backup")
+	fmt.Fprintln(os.Stderr, "  version  Print agent version")
+}
+
+func runUpdateCheck(host string, isSkipUpdate, isDev bool, log *slog.Logger) {
+	if isSkipUpdate {
+		return
+	}
+
+	if host == "" {
+		return
+	}
+
+	apiClient := api.NewClient(host, "", log)
+
+	isUpgraded, err := upgrade.CheckAndUpdate(apiClient, Version, isDev, log)
+	if err != nil {
+		log.Error("Auto-update failed", "error", err)
+		os.Exit(1)
+	}
+
+	if isUpgraded {
+		reexecAfterUpgrade(log)
+	}
+}
+
+func checkIsDevelopment() bool {
+	dir, err := os.Getwd()
+	if err != nil {
+		return false
+	}
+
+	for range 3 {
+		if data, err := os.ReadFile(filepath.Join(dir, ".env")); err == nil {
+			return parseEnvMode(data)
+		}
+
+		if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
+			return false
+		}
+
+		dir = filepath.Dir(dir)
+	}
+
+	return false
+}
+
+func parseEnvMode(data []byte) bool {
+	for line := range strings.SplitSeq(string(data), "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+
+		parts := strings.SplitN(line, "=", 2)
+		if len(parts) == 2 && strings.TrimSpace(parts[0]) == "ENV_MODE" {
+			return strings.TrimSpace(parts[1]) == "development"
+		}
+	}
+
+	return false
+}
+
+func reexecAfterUpgrade(log *slog.Logger) {
+	selfPath, err := os.Executable()
+	if err != nil {
+		log.Error("Failed to resolve executable for re-exec", "error", err)
+		os.Exit(1)
+	}
+
+	log.Info("Re-executing after upgrade...")
+
+	if err := syscall.Exec(selfPath, os.Args, os.Environ()); err != nil {
+		log.Error("Failed to re-exec after upgrade", "error", err)
+		os.Exit(1)
+	}
+}

agent/docker-compose.yml.example

@@ -0,0 +1,58 @@
+services:
+  dev-postgres:
+    image: postgres:17
+    container_name: dev-postgres
+    environment:
+      POSTGRES_DB: devdb
+      POSTGRES_USER: devuser
+      POSTGRES_PASSWORD: devpassword
+    ports:
+      - "7433:5432"
+    command:
+      - bash
+      - -c
+      - |
+        mkdir -p /wal-queue && chown postgres:postgres /wal-queue
+        exec docker-entrypoint.sh postgres \
+          -c wal_level=replica \
+          -c max_wal_senders=3 \
+          -c archive_mode=on \
+          -c "archive_command=cp %p /wal-queue/%f"
+    volumes:
+      - ./wal-queue:/wal-queue
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U devuser -d devdb"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  db-writer:
+    image: postgres:17
+    container_name: dev-db-writer
+    depends_on:
+      dev-postgres:
+        condition: service_healthy
+    environment:
+      PGHOST: dev-postgres
+      PGPORT: "5432"
+      PGUSER: devuser
+      PGPASSWORD: devpassword
+      PGDATABASE: devdb
+    command:
+      - bash
+      - -c
+      - |
+        echo "Waiting for postgres..."
+        until pg_isready -h dev-postgres -U devuser -d devdb; do sleep 1; done
+
+        psql -c "DROP TABLE IF EXISTS wal_generator;"
+        psql -c "CREATE TABLE wal_generator (id SERIAL PRIMARY KEY, data TEXT NOT NULL);"
+        echo "Starting WAL generation loop..."
+        while true; do
+          echo "Inserting ~50MB of data..."
+          psql -c "INSERT INTO wal_generator (data) SELECT repeat(md5(random()::text), 640) FROM generate_series(1, 2500);"
+          echo "Deleting data..."
+          psql -c "DELETE FROM wal_generator;"
+          echo "Cycle complete, sleeping 5s..."
+          sleep 5
+        done

agent/e2e/.gitignore

@@ -0,0 +1,2 @@
+artifacts/
+pgdata/

agent/e2e/Dockerfile.agent-builder

@@ -0,0 +1,13 @@
+# Builds agent binaries with different versions so
+# we can test upgrade behavior (v1 -> v2)
+FROM golang:1.26.1-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -ldflags "-X main.Version=v1.0.0" -o /out/agent-v1 ./cmd/main.go
+RUN CGO_ENABLED=0 go build -ldflags "-X main.Version=v2.0.0" -o /out/agent-v2 ./cmd/main.go
+
+FROM alpine:3.21
+COPY --from=build /out/ /out/
+CMD ["cp", "-v", "/out/agent-v1", "/out/agent-v2", "/artifacts/"]

agent/e2e/Dockerfile.agent-docker

@@ -0,0 +1,22 @@
+# Runs backup-restore via docker exec test (test 6). Needs both Docker
+# CLI (for pg_basebackup via docker exec) and PostgreSQL server (for
+# restore verification).
+FROM debian:bookworm-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ca-certificates curl gnupg2 locales postgresql-common && \
+    sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && \
+    locale-gen && \
+    /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && \
+    apt-get install -y --no-install-recommends \
+      postgresql-17 && \
+    install -m 0755 -d /etc/apt/keyrings && \
+    curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian bookworm stable" > /etc/apt/sources.list.d/docker.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends docker-ce-cli && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp
+ENTRYPOINT []

agent/e2e/Dockerfile.agent-runner

@@ -0,0 +1,14 @@
+# Runs upgrade and host-mode backup-restore tests (tests 1-5). Needs
+# full PostgreSQL server for backup-restore lifecycle tests.
+FROM debian:bookworm-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ca-certificates curl gnupg2 postgresql-common && \
+    /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && \
+    apt-get install -y --no-install-recommends \
+      postgresql-17 && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp
+ENTRYPOINT []

agent/e2e/Dockerfile.backup-restore-runner

@@ -0,0 +1,16 @@
+# Runs backup-restore lifecycle tests with a specific PostgreSQL version.
+# Used for PG version matrix testing (15, 16, 17, 18).
+FROM debian:bookworm-slim
+
+ARG PG_VERSION=17
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ca-certificates curl gnupg2 postgresql-common && \
+    /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && \
+    apt-get install -y --no-install-recommends \
+      postgresql-${PG_VERSION} && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp
+ENTRYPOINT []

agent/e2e/Dockerfile.mock-server

@@ -0,0 +1,10 @@
+# Mock databasus API server for version checks and binary downloads. Just
+# serves static responses and files from the `artifacts` directory.
+FROM golang:1.26.1-alpine AS build
+WORKDIR /app
+COPY mock-server/main.go .
+RUN CGO_ENABLED=0 go build -o mock-server main.go
+
+FROM alpine:3.21
+COPY --from=build /app/mock-server /usr/local/bin/mock-server
+ENTRYPOINT ["mock-server"]

agent/e2e/docker-compose.backup-restore.yml

@@ -0,0 +1,33 @@
+services:
+  e2e-br-mock-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.mock-server
+    volumes:
+      - backup-storage:/backup-storage
+    container_name: e2e-br-mock-server
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:4050/health"]
+      interval: 2s
+      timeout: 5s
+      retries: 10
+
+  e2e-br-runner:
+    build:
+      context: .
+      dockerfile: Dockerfile.backup-restore-runner
+      args:
+        PG_VERSION: ${PG_VERSION:-17}
+    volumes:
+      - ./artifacts:/opt/agent/artifacts:ro
+      - ./scripts:/opt/agent/scripts:ro
+    depends_on:
+      e2e-br-mock-server:
+        condition: service_healthy
+    container_name: e2e-br-runner
+    command: ["bash", "/opt/agent/scripts/test-pg-host-path.sh"]
+    environment:
+      MOCK_SERVER_OVERRIDE: "http://e2e-br-mock-server:4050"
+
+volumes:
+  backup-storage:

agent/e2e/docker-compose.yml

@@ -0,0 +1,84 @@
+services:
+  e2e-agent-builder:
+    build:
+      context: ..
+      dockerfile: e2e/Dockerfile.agent-builder
+    volumes:
+      - ./artifacts:/artifacts
+    container_name: e2e-agent-builder
+
+  e2e-postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_DB: testdb
+      POSTGRES_USER: testuser
+      POSTGRES_PASSWORD: testpassword
+    container_name: e2e-agent-postgres
+    command:
+      - bash
+      - -c
+      - |
+        mkdir -p /wal-queue && chown postgres:postgres /wal-queue
+        exec docker-entrypoint.sh postgres \
+          -c wal_level=replica \
+          -c max_wal_senders=3 \
+          -c archive_mode=on \
+          -c "archive_command=cp %p /wal-queue/%f"
+    volumes:
+      - ./pgdata:/var/lib/postgresql/data
+      - wal-queue:/wal-queue
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U testuser -d testdb"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  e2e-mock-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.mock-server
+    volumes:
+      - ./artifacts:/artifacts:ro
+      - backup-storage:/backup-storage
+    container_name: e2e-mock-server
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:4050/health"]
+      interval: 2s
+      timeout: 5s
+      retries: 10
+
+  e2e-agent-runner:
+    build:
+      context: .
+      dockerfile: Dockerfile.agent-runner
+    volumes:
+      - ./artifacts:/opt/agent/artifacts:ro
+      - ./scripts:/opt/agent/scripts:ro
+    depends_on:
+      e2e-postgres:
+        condition: service_healthy
+      e2e-mock-server:
+        condition: service_healthy
+    container_name: e2e-agent-runner
+    command: ["bash", "/opt/agent/scripts/run-all.sh", "host"]
+
+  e2e-agent-docker:
+    build:
+      context: .
+      dockerfile: Dockerfile.agent-docker
+    volumes:
+      - ./artifacts:/opt/agent/artifacts:ro
+      - ./scripts:/opt/agent/scripts:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+      - wal-queue:/wal-queue
+    depends_on:
+      e2e-postgres:
+        condition: service_healthy
+      e2e-mock-server:
+        condition: service_healthy
+    container_name: e2e-agent-docker
+    command: ["bash", "/opt/agent/scripts/run-all.sh", "docker"]
+
+volumes:
+  wal-queue:
+  backup-storage:

agent/e2e/mock-server/main.go

@@ -0,0 +1,477 @@
+package main
+
+import (
+	"crypto/rand"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+)
+
+const backupStorageDir = "/backup-storage"
+
+type walSegment struct {
+	BackupID    string
+	SegmentName string
+	FilePath    string
+	SizeBytes   int64
+}
+
+type server struct {
+	mu         sync.RWMutex
+	version    string
+	binaryPath string
+
+	backupID        string
+	backupFilePath  string
+	startSegment    string
+	stopSegment     string
+	isFinalized     bool
+	walSegments     []walSegment
+	backupCreatedAt time.Time
+}
+
+func main() {
+	version := "v2.0.0"
+	binaryPath := "/artifacts/agent-v2"
+	port := "4050"
+
+	_ = os.MkdirAll(backupStorageDir, 0o755)
+
+	s := &server{version: version, binaryPath: binaryPath}
+
+	// System endpoints
+	http.HandleFunc("/api/v1/system/version", s.handleVersion)
+	http.HandleFunc("/api/v1/system/agent", s.handleAgentDownload)
+
+	// Backup endpoints
+	http.HandleFunc("/api/v1/backups/postgres/wal/is-wal-chain-valid-since-last-full-backup", s.handleChainValidity)
+	http.HandleFunc("/api/v1/backups/postgres/wal/next-full-backup-time", s.handleNextBackupTime)
+	http.HandleFunc("/api/v1/backups/postgres/wal/upload/full-start", s.handleFullStart)
+	http.HandleFunc("/api/v1/backups/postgres/wal/upload/full-complete", s.handleFullComplete)
+	http.HandleFunc("/api/v1/backups/postgres/wal/upload/wal", s.handleWalUpload)
+	http.HandleFunc("/api/v1/backups/postgres/wal/error", s.handleError)
+
+	// Restore endpoints
+	http.HandleFunc("/api/v1/backups/postgres/wal/restore/plan", s.handleRestorePlan)
+	http.HandleFunc("/api/v1/backups/postgres/wal/restore/download", s.handleRestoreDownload)
+
+	// Mock control endpoints
+	http.HandleFunc("/mock/set-version", s.handleSetVersion)
+	http.HandleFunc("/mock/set-binary-path", s.handleSetBinaryPath)
+	http.HandleFunc("/mock/backup-status", s.handleBackupStatus)
+	http.HandleFunc("/mock/reset", s.handleReset)
+	http.HandleFunc("/health", s.handleHealth)
+
+	addr := ":" + port
+	log.Printf("Mock server starting on %s (version=%s, binary=%s)", addr, version, binaryPath)
+
+	if err := http.ListenAndServe(addr, nil); err != nil {
+		log.Fatalf("Server failed: %v", err)
+	}
+}
+
+// --- System handlers ---
+
+func (s *server) handleVersion(w http.ResponseWriter, _ *http.Request) {
+	s.mu.RLock()
+	v := s.version
+	s.mu.RUnlock()
+
+	log.Printf("GET /api/v1/system/version -> %s", v)
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]string{"version": v})
+}
+
+func (s *server) handleAgentDownload(w http.ResponseWriter, r *http.Request) {
+	s.mu.RLock()
+	path := s.binaryPath
+	s.mu.RUnlock()
+
+	log.Printf("GET /api/v1/system/agent (arch=%s) -> serving %s", r.URL.Query().Get("arch"), path)
+
+	http.ServeFile(w, r, path)
+}
+
+// --- Backup handlers ---
+
+func (s *server) handleChainValidity(w http.ResponseWriter, _ *http.Request) {
+	s.mu.RLock()
+	isFinalized := s.isFinalized
+	s.mu.RUnlock()
+
+	log.Printf("GET chain-validity -> isFinalized=%v", isFinalized)
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if isFinalized {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"isValid": true,
+		})
+	} else {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"isValid": false,
+			"error":   "no full backup found",
+		})
+	}
+}
+
+func (s *server) handleNextBackupTime(w http.ResponseWriter, _ *http.Request) {
+	log.Printf("GET next-full-backup-time")
+
+	nextTime := time.Now().UTC().Add(1 * time.Hour)
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"nextFullBackupTime": nextTime.Format(time.RFC3339),
+	})
+}
+
+func (s *server) handleFullStart(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	backupID := generateID()
+	filePath := filepath.Join(backupStorageDir, backupID+".zst")
+
+	file, err := os.Create(filePath)
+	if err != nil {
+		log.Printf("ERROR creating backup file: %v", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+
+	bytesWritten, err := io.Copy(file, r.Body)
+	_ = file.Close()
+
+	if err != nil {
+		log.Printf("ERROR writing backup data: %v", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+
+	s.mu.Lock()
+	s.backupID = backupID
+	s.backupFilePath = filePath
+	s.backupCreatedAt = time.Now().UTC()
+	s.mu.Unlock()
+
+	log.Printf("POST full-start -> backupID=%s, size=%d bytes", backupID, bytesWritten)
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]string{"backupId": backupID})
+}
+
+func (s *server) handleFullComplete(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var body struct {
+		BackupID     string  `json:"backupId"`
+		StartSegment string  `json:"startSegment"`
+		StopSegment  string  `json:"stopSegment"`
+		Error        *string `json:"error,omitempty"`
+	}
+
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if body.Error != nil {
+		log.Printf("POST full-complete -> backupID=%s ERROR: %s", body.BackupID, *body.Error)
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+
+	s.mu.Lock()
+	s.startSegment = body.StartSegment
+	s.stopSegment = body.StopSegment
+	s.isFinalized = true
+	s.mu.Unlock()
+
+	log.Printf(
+		"POST full-complete -> backupID=%s, start=%s, stop=%s",
+		body.BackupID,
+		body.StartSegment,
+		body.StopSegment,
+	)
+
+	w.WriteHeader(http.StatusOK)
+}
+
+func (s *server) handleWalUpload(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	segmentName := r.Header.Get("X-Wal-Segment-Name")
+	if segmentName == "" {
+		http.Error(w, "missing X-Wal-Segment-Name header", http.StatusBadRequest)
+		return
+	}
+
+	walBackupID := generateID()
+	filePath := filepath.Join(backupStorageDir, walBackupID+".zst")
+
+	file, err := os.Create(filePath)
+	if err != nil {
+		log.Printf("ERROR creating WAL file: %v", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+
+	bytesWritten, err := io.Copy(file, r.Body)
+	_ = file.Close()
+
+	if err != nil {
+		log.Printf("ERROR writing WAL data: %v", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+
+	s.mu.Lock()
+	s.walSegments = append(s.walSegments, walSegment{
+		BackupID:    walBackupID,
+		SegmentName: segmentName,
+		FilePath:    filePath,
+		SizeBytes:   bytesWritten,
+	})
+	s.mu.Unlock()
+
+	log.Printf("POST wal-upload -> segment=%s, walBackupID=%s, size=%d", segmentName, walBackupID, bytesWritten)
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (s *server) handleError(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var body struct {
+		Error string `json:"error"`
+	}
+
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		log.Printf("POST error -> failed to decode: %v", err)
+	} else {
+		log.Printf("POST error -> %s", body.Error)
+	}
+
+	w.WriteHeader(http.StatusOK)
+}
+
+// --- Restore handlers ---
+
+func (s *server) handleRestorePlan(w http.ResponseWriter, _ *http.Request) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if !s.isFinalized {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		_ = json.NewEncoder(w).Encode(map[string]string{
+			"error":   "no_backups",
+			"message": "No full backups available",
+		})
+		return
+	}
+
+	backupFileInfo, err := os.Stat(s.backupFilePath)
+	if err != nil {
+		log.Printf("ERROR stat backup file: %v", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+
+	backupSizeBytes := backupFileInfo.Size()
+	totalSizeBytes := backupSizeBytes
+
+	walSegmentsJSON := make([]map[string]any, 0, len(s.walSegments))
+
+	latestSegment := ""
+
+	for _, segment := range s.walSegments {
+		totalSizeBytes += segment.SizeBytes
+		latestSegment = segment.SegmentName
+
+		walSegmentsJSON = append(walSegmentsJSON, map[string]any{
+			"backupId":    segment.BackupID,
+			"segmentName": segment.SegmentName,
+			"sizeBytes":   segment.SizeBytes,
+		})
+	}
+
+	response := map[string]any{
+		"fullBackup": map[string]any{
+			"id":                        s.backupID,
+			"fullBackupWalStartSegment": s.startSegment,
+			"fullBackupWalStopSegment":  s.stopSegment,
+			"pgVersion":                 "17",
+			"createdAt":                 s.backupCreatedAt.Format(time.RFC3339),
+			"sizeBytes":                 backupSizeBytes,
+		},
+		"walSegments":            walSegmentsJSON,
+		"totalSizeBytes":         totalSizeBytes,
+		"latestAvailableSegment": latestSegment,
+	}
+
+	log.Printf("GET restore-plan -> backupID=%s, walSegments=%d", s.backupID, len(s.walSegments))
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(response)
+}
+
+func (s *server) handleRestoreDownload(w http.ResponseWriter, r *http.Request) {
+	requestedBackupID := r.URL.Query().Get("backupId")
+	if requestedBackupID == "" {
+		http.Error(w, "missing backupId query param", http.StatusBadRequest)
+		return
+	}
+
+	filePath := s.findBackupFile(requestedBackupID)
+	if filePath == "" {
+		log.Printf("GET restore-download -> backupId=%s NOT FOUND", requestedBackupID)
+		http.Error(w, "backup not found", http.StatusNotFound)
+		return
+	}
+
+	log.Printf("GET restore-download -> backupId=%s, file=%s", requestedBackupID, filePath)
+
+	http.ServeFile(w, r, filePath)
+}
+
+// --- Mock control handlers ---
+
+func (s *server) handleSetVersion(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var body struct {
+		Version string `json:"version"`
+	}
+
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	s.mu.Lock()
+	s.version = body.Version
+	s.mu.Unlock()
+
+	log.Printf("POST /mock/set-version -> %s", body.Version)
+
+	_, _ = fmt.Fprintf(w, "version set to %s", body.Version)
+}
+
+func (s *server) handleSetBinaryPath(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var body struct {
+		BinaryPath string `json:"binaryPath"`
+	}
+
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	s.mu.Lock()
+	s.binaryPath = body.BinaryPath
+	s.mu.Unlock()
+
+	log.Printf("POST /mock/set-binary-path -> %s", body.BinaryPath)
+
+	_, _ = fmt.Fprintf(w, "binary path set to %s", body.BinaryPath)
+}
+
+func (s *server) handleBackupStatus(w http.ResponseWriter, _ *http.Request) {
+	s.mu.RLock()
+	isFinalized := s.isFinalized
+	walSegmentCount := len(s.walSegments)
+	s.mu.RUnlock()
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"isFinalized":     isFinalized,
+		"walSegmentCount": walSegmentCount,
+	})
+}
+
+func (s *server) handleReset(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	s.mu.Lock()
+	s.backupID = ""
+	s.backupFilePath = ""
+	s.startSegment = ""
+	s.stopSegment = ""
+	s.isFinalized = false
+	s.walSegments = nil
+	s.backupCreatedAt = time.Time{}
+	s.mu.Unlock()
+
+	// Clean stored files
+	entries, _ := os.ReadDir(backupStorageDir)
+	for _, entry := range entries {
+		_ = os.Remove(filepath.Join(backupStorageDir, entry.Name()))
+	}
+
+	log.Printf("POST /mock/reset -> state cleared")
+
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("ok"))
+}
+
+func (s *server) handleHealth(w http.ResponseWriter, _ *http.Request) {
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("ok"))
+}
+
+// --- Private helpers ---
+
+func generateID() string {
+	b := make([]byte, 16)
+	_, _ = rand.Read(b)
+
+	return fmt.Sprintf("%08x-%04x-%04x-%04x-%012x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
+}
+
+func (s *server) findBackupFile(backupID string) string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if s.backupID == backupID {
+		return s.backupFilePath
+	}
+
+	for _, segment := range s.walSegments {
+		if segment.BackupID == backupID {
+			return segment.FilePath
+		}
+	}
+
+	return ""
+}

agent/e2e/scripts/backup-restore-helpers.sh

@@ -0,0 +1,357 @@
+#!/bin/bash
+# Shared helper functions for backup-restore E2E tests.
+# Source this file from test scripts: source "$(dirname "$0")/backup-restore-helpers.sh"
+
+AGENT="/tmp/test-agent"
+AGENT_PID=""
+
+cleanup_agent() {
+  if [ -n "$AGENT_PID" ]; then
+    kill "$AGENT_PID" 2>/dev/null || true
+    wait "$AGENT_PID" 2>/dev/null || true
+    AGENT_PID=""
+  fi
+
+  pkill -f "test-agent" 2>/dev/null || true
+  for i in $(seq 1 20); do
+    pgrep -f "test-agent" > /dev/null 2>&1 || break
+    sleep 0.5
+  done
+  pkill -9 -f "test-agent" 2>/dev/null || true
+  sleep 0.5
+
+  rm -f "$AGENT" "$AGENT.update" databasus.lock databasus.log databasus.log.old databasus.json 2>/dev/null || true
+}
+
+setup_agent() {
+  local artifacts="${1:-/opt/agent/artifacts}"
+
+  cleanup_agent
+  cp "$artifacts/agent-v1" "$AGENT"
+  chmod +x "$AGENT"
+}
+
+init_pg_local() {
+  local pgdata="$1"
+  local port="$2"
+  local wal_queue="$3"
+  local pg_bin_dir="$4"
+
+  # Stop any leftover PG from previous test runs
+  su postgres -c "$pg_bin_dir/pg_ctl -D $pgdata stop -m immediate" 2>/dev/null || true
+  su postgres -c "$pg_bin_dir/pg_ctl -D /tmp/restore-pgdata stop -m immediate" 2>/dev/null || true
+
+  mkdir -p "$wal_queue"
+  chown postgres:postgres "$wal_queue"
+  rm -rf "$pgdata"
+
+  su postgres -c "$pg_bin_dir/initdb -D $pgdata" > /dev/null
+
+  cat >> "$pgdata/postgresql.conf" <<PGCONF
+wal_level = replica
+archive_mode = on
+archive_command = 'cp %p $wal_queue/%f'
+max_wal_senders = 3
+listen_addresses = 'localhost'
+port = $port
+checkpoint_timeout = 30s
+PGCONF
+
+  echo "local all all trust" > "$pgdata/pg_hba.conf"
+  echo "host all all 127.0.0.1/32 trust" >> "$pgdata/pg_hba.conf"
+  echo "host all all ::1/128 trust" >> "$pgdata/pg_hba.conf"
+  echo "local replication all trust" >> "$pgdata/pg_hba.conf"
+  echo "host replication all 127.0.0.1/32 trust" >> "$pgdata/pg_hba.conf"
+  echo "host replication all ::1/128 trust" >> "$pgdata/pg_hba.conf"
+
+  su postgres -c "$pg_bin_dir/pg_ctl -D $pgdata -l /tmp/pg.log start -w"
+
+  su postgres -c "$pg_bin_dir/psql -p $port -c \"CREATE USER testuser WITH SUPERUSER REPLICATION;\"" > /dev/null 2>&1 || true
+  su postgres -c "$pg_bin_dir/psql -p $port -c \"CREATE DATABASE testdb OWNER testuser;\"" > /dev/null 2>&1 || true
+
+  echo "PostgreSQL initialized and started on port $port"
+}
+
+insert_test_data() {
+  local port="$1"
+  local pg_bin_dir="$2"
+
+  su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb" <<SQL
+CREATE TABLE e2e_test_data (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL,
+    value INT NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+INSERT INTO e2e_test_data (name, value) VALUES
+    ('row1', 100),
+    ('row2', 200),
+    ('row3', 300);
+SQL
+
+  echo "Test data inserted (3 rows)"
+}
+
+force_checkpoint() {
+  local port="$1"
+  local pg_bin_dir="$2"
+
+  su postgres -c "$pg_bin_dir/psql -p $port -c 'CHECKPOINT;'" > /dev/null
+  echo "Checkpoint forced"
+}
+
+run_agent_backup() {
+  local mock_server="$1"
+  local pg_host="$2"
+  local pg_port="$3"
+  local wal_queue="$4"
+  local pg_type="$5"
+  local pg_host_bin_dir="${6:-}"
+  local pg_docker_container="${7:-}"
+
+  # Reset mock server state and set version to match agent (prevents background upgrade loop)
+  curl -sf -X POST "$mock_server/mock/reset" > /dev/null
+  curl -sf -X POST "$mock_server/mock/set-version" \
+    -H "Content-Type: application/json" \
+    -d '{"version":"v1.0.0"}' > /dev/null
+
+  # Build JSON config
+  cd /tmp
+
+  local extra_fields=""
+  if [ -n "$pg_host_bin_dir" ]; then
+    extra_fields="$extra_fields\"pgHostBinDir\": \"$pg_host_bin_dir\","
+  fi
+  if [ -n "$pg_docker_container" ]; then
+    extra_fields="$extra_fields\"pgDockerContainerName\": \"$pg_docker_container\","
+  fi
+
+  cat > databasus.json <<AGENTCONF
+{
+  "databasusHost": "$mock_server",
+  "dbId": "test-db-id",
+  "token": "test-token",
+  "pgHost": "$pg_host",
+  "pgPort": $pg_port,
+  "pgUser": "testuser",
+  "pgPassword": "",
+  ${extra_fields}
+  "pgType": "$pg_type",
+  "pgWalDir": "$wal_queue",
+  "deleteWalAfterUpload": true
+}
+AGENTCONF
+
+  # Run agent daemon in background
+  "$AGENT" _run > /tmp/agent-output.log 2>&1 &
+  AGENT_PID=$!
+
+  echo "Agent started with PID $AGENT_PID"
+}
+
+generate_wal_background() {
+  local port="$1"
+  local pg_bin_dir="$2"
+
+  while true; do
+    su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb -c \"
+      INSERT INTO e2e_test_data (name, value)
+      SELECT 'bulk_' || g, g FROM generate_series(1, 1000) g;
+      SELECT pg_switch_wal();
+    \"" > /dev/null 2>&1 || break
+    sleep 2
+  done
+}
+
+generate_wal_docker_background() {
+  local container="$1"
+
+  while true; do
+    docker exec "$container" psql -U testuser -d testdb -c "
+      INSERT INTO e2e_test_data (name, value)
+      SELECT 'bulk_' || g, g FROM generate_series(1, 1000) g;
+      SELECT pg_switch_wal();
+    " > /dev/null 2>&1 || break
+    sleep 2
+  done
+}
+
+wait_for_backup_complete() {
+  local mock_server="$1"
+  local timeout="${2:-120}"
+
+  echo "Waiting for backup to complete (timeout: ${timeout}s)..."
+
+  for i in $(seq 1 "$timeout"); do
+    STATUS=$(curl -sf "$mock_server/mock/backup-status" 2>/dev/null || echo '{}')
+    IS_FINALIZED=$(echo "$STATUS" | grep -o '"isFinalized":true' || true)
+    WAL_COUNT=$(echo "$STATUS" | grep -o '"walSegmentCount":[0-9]*' | grep -o '[0-9]*$' || echo "0")
+
+    if [ -n "$IS_FINALIZED" ] && [ "$WAL_COUNT" -gt 0 ]; then
+      echo "Backup complete: finalized with $WAL_COUNT WAL segments"
+      return 0
+    fi
+
+    sleep 1
+  done
+
+  echo "FAIL: Backup did not complete within ${timeout} seconds"
+  echo "Last status: $STATUS"
+  echo "Agent output:"
+  cat /tmp/agent-output.log 2>/dev/null || true
+  return 1
+}
+
+stop_agent() {
+  if [ -n "$AGENT_PID" ]; then
+    kill "$AGENT_PID" 2>/dev/null || true
+    wait "$AGENT_PID" 2>/dev/null || true
+    AGENT_PID=""
+  fi
+
+  echo "Agent stopped"
+}
+
+stop_pg() {
+  local pgdata="$1"
+  local pg_bin_dir="$2"
+
+  su postgres -c "$pg_bin_dir/pg_ctl -D $pgdata stop -m fast" 2>/dev/null || true
+
+  echo "PostgreSQL stopped"
+}
+
+run_agent_restore() {
+  local mock_server="$1"
+  local restore_dir="$2"
+
+  rm -rf "$restore_dir"
+  mkdir -p "$restore_dir"
+  chown postgres:postgres "$restore_dir"
+
+  cd /tmp
+
+  "$AGENT" restore \
+    --skip-update \
+    --databasus-host "$mock_server" \
+    --token test-token \
+    --target-dir "$restore_dir"
+
+  echo "Agent restore completed"
+}
+
+start_restored_pg() {
+  local restore_dir="$1"
+  local port="$2"
+  local pg_bin_dir="$3"
+
+  # Ensure port is set in restored config
+  if ! grep -q "^port" "$restore_dir/postgresql.conf" 2>/dev/null; then
+    echo "port = $port" >> "$restore_dir/postgresql.conf"
+  fi
+
+  # Ensure listen_addresses is set
+  if ! grep -q "^listen_addresses" "$restore_dir/postgresql.conf" 2>/dev/null; then
+    echo "listen_addresses = 'localhost'" >> "$restore_dir/postgresql.conf"
+  fi
+
+  chown -R postgres:postgres "$restore_dir"
+  chmod 700 "$restore_dir"
+
+  if ! su postgres -c "$pg_bin_dir/pg_ctl -D $restore_dir -l /tmp/pg-restore.log start -w"; then
+    echo "FAIL: PostgreSQL failed to start on restored data"
+    echo "--- pg-restore.log ---"
+    cat /tmp/pg-restore.log 2>/dev/null || echo "(no log file)"
+    echo "--- postgresql.auto.conf ---"
+    cat "$restore_dir/postgresql.auto.conf" 2>/dev/null || echo "(no file)"
+    echo "--- pg_wal/ listing ---"
+    ls -la "$restore_dir/pg_wal/" 2>/dev/null || echo "(no pg_wal dir)"
+    echo "--- databasus-wal-restore/ listing ---"
+    ls -la "$restore_dir/databasus-wal-restore/" 2>/dev/null || echo "(no dir)"
+    echo "--- end diagnostics ---"
+    return 1
+  fi
+
+  echo "PostgreSQL started on restored data"
+}
+
+wait_for_recovery_complete() {
+  local port="$1"
+  local pg_bin_dir="$2"
+  local timeout="${3:-60}"
+
+  echo "Waiting for recovery to complete (timeout: ${timeout}s)..."
+
+  for i in $(seq 1 "$timeout"); do
+    IS_READY=$(su postgres -c "$pg_bin_dir/pg_isready -p $port" 2>&1 || true)
+
+    if echo "$IS_READY" | grep -q "accepting connections"; then
+      IN_RECOVERY=$(su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb -t -c 'SELECT pg_is_in_recovery();'" 2>/dev/null | tr -d ' \n' || echo "t")
+
+      if [ "$IN_RECOVERY" = "f" ]; then
+        echo "PostgreSQL recovered and promoted to primary"
+        return 0
+      fi
+    fi
+
+    sleep 1
+  done
+
+  echo "FAIL: PostgreSQL did not recover within ${timeout} seconds"
+  echo "Recovery log:"
+  cat /tmp/pg-restore.log 2>/dev/null || true
+  return 1
+}
+
+verify_restored_data() {
+  local port="$1"
+  local pg_bin_dir="$2"
+
+  ROW_COUNT=$(su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb -t -c 'SELECT COUNT(*) FROM e2e_test_data;'" | tr -d ' \n')
+
+  if [ "$ROW_COUNT" -lt 3 ]; then
+    echo "FAIL: Expected at least 3 rows, got $ROW_COUNT"
+    su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb -c 'SELECT * FROM e2e_test_data;'"
+    return 1
+  fi
+
+  RESULT=$(su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb -t -c \"SELECT value FROM e2e_test_data WHERE name='row1';\"" | tr -d ' \n')
+
+  if [ "$RESULT" != "100" ]; then
+    echo "FAIL: Expected row1 value=100, got $RESULT"
+    return 1
+  fi
+
+  RESULT2=$(su postgres -c "$pg_bin_dir/psql -p $port -U testuser -d testdb -t -c \"SELECT value FROM e2e_test_data WHERE name='row3';\"" | tr -d ' \n')
+
+  if [ "$RESULT2" != "300" ]; then
+    echo "FAIL: Expected row3 value=300, got $RESULT2"
+    return 1
+  fi
+
+  echo "PASS: Found $ROW_COUNT rows, data integrity verified"
+  return 0
+}
+
+find_pg_bin_dir() {
+  # Find the PG bin dir from the installed version
+  local pg_config_path
+  pg_config_path=$(which pg_config 2>/dev/null || true)
+
+  if [ -n "$pg_config_path" ]; then
+    pg_config --bindir
+    return
+  fi
+
+  # Fallback: search common locations
+  for version in 18 17 16 15; do
+    if [ -d "/usr/lib/postgresql/$version/bin" ]; then
+      echo "/usr/lib/postgresql/$version/bin"
+      return
+    fi
+  done
+
+  echo "ERROR: Cannot find PostgreSQL bin directory" >&2
+  return 1
+}

agent/e2e/scripts/run-all.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+set -euo pipefail
+
+MODE="${1:-host}"
+SCRIPT_DIR="$(dirname "$0")"
+PASSED=0
+FAILED=0
+FAILED_NAMES=""
+
+run_test() {
+  local name="$1"
+  local script="$2"
+
+  echo ""
+  echo "========================================"
+  echo "  $name"
+  echo "========================================"
+
+  if bash "$script"; then
+    echo "  PASSED: $name"
+    PASSED=$((PASSED + 1))
+  else
+    echo "  FAILED: $name"
+    FAILED=$((FAILED + 1))
+    FAILED_NAMES="${FAILED_NAMES}\n    - ${name}"
+  fi
+}
+
+if [ "$MODE" = "host" ]; then
+  run_test "Test 1: Upgrade success (v1 -> v2)" "$SCRIPT_DIR/test-upgrade-success.sh"
+  run_test "Test 2: Upgrade skip (version matches)" "$SCRIPT_DIR/test-upgrade-skip.sh"
+  run_test "Test 3: Background upgrade (v1 -> v2 while running)" "$SCRIPT_DIR/test-upgrade-background.sh"
+  run_test "Test 4: Backup-restore via host PATH" "$SCRIPT_DIR/test-pg-host-path.sh"
+  run_test "Test 5: Backup-restore via host bindir" "$SCRIPT_DIR/test-pg-host-bindir.sh"
+
+elif [ "$MODE" = "docker" ]; then
+  run_test "Test 6: Backup-restore via docker exec" "$SCRIPT_DIR/test-pg-docker-exec.sh"
+
+else
+  echo "Unknown mode: $MODE (expected 'host' or 'docker')"
+  exit 1
+fi
+
+echo ""
+echo "========================================"
+echo "  Results: $PASSED passed, $FAILED failed"
+if [ "$FAILED" -gt 0 ]; then
+  echo ""
+  echo "  Failed:"
+  echo -e "$FAILED_NAMES"
+fi
+echo "========================================"
+
+if [ "$FAILED" -gt 0 ]; then
+  exit 1
+fi

agent/e2e/scripts/test-pg-docker-exec.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(dirname "$0")"
+source "$SCRIPT_DIR/backup-restore-helpers.sh"
+
+MOCK_SERVER="${MOCK_SERVER_OVERRIDE:-http://e2e-mock-server:4050}"
+PG_CONTAINER="e2e-agent-postgres"
+RESTORE_PGDATA="/tmp/restore-pgdata"
+WAL_QUEUE="/wal-queue"
+PG_PORT=5432
+
+# For restore verification we need a local PG bin dir
+PG_BIN_DIR=$(find_pg_bin_dir)
+echo "Using local PG bin dir for restore verification: $PG_BIN_DIR"
+
+# Verify docker CLI works and PG container is accessible
+if ! docker exec "$PG_CONTAINER" pg_basebackup --version > /dev/null 2>&1; then
+  echo "FAIL: Cannot reach pg_basebackup inside container $PG_CONTAINER (test setup issue)"
+  exit 1
+fi
+
+echo "=== Phase 1: Setup agent ==="
+setup_agent
+
+echo "=== Phase 2: Insert test data into containerized PostgreSQL ==="
+docker exec "$PG_CONTAINER" psql -U testuser -d testdb -c "
+CREATE TABLE IF NOT EXISTS e2e_test_data (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL,
+    value INT NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+DELETE FROM e2e_test_data;
+INSERT INTO e2e_test_data (name, value) VALUES
+    ('row1', 100),
+    ('row2', 200),
+    ('row3', 300);
+"
+echo "Test data inserted (3 rows)"
+
+echo "=== Phase 3: Start agent backup (docker exec mode) ==="
+curl -sf -X POST "$MOCK_SERVER/mock/reset" > /dev/null
+
+cd /tmp
+cat > databasus.json <<AGENTCONF
+{
+  "databasusHost": "$MOCK_SERVER",
+  "dbId": "test-db-id",
+  "token": "test-token",
+  "pgHost": "$PG_CONTAINER",
+  "pgPort": $PG_PORT,
+  "pgUser": "testuser",
+  "pgPassword": "testpassword",
+  "pgType": "docker",
+  "pgDockerContainerName": "$PG_CONTAINER",
+  "pgWalDir": "$WAL_QUEUE",
+  "deleteWalAfterUpload": true
+}
+AGENTCONF
+
+"$AGENT" _run > /tmp/agent-output.log 2>&1 &
+AGENT_PID=$!
+echo "Agent started with PID $AGENT_PID"
+
+echo "=== Phase 4: Generate WAL in background ==="
+generate_wal_docker_background "$PG_CONTAINER" &
+WAL_GEN_PID=$!
+
+echo "=== Phase 5: Wait for backup to complete ==="
+wait_for_backup_complete "$MOCK_SERVER" 120
+
+echo "=== Phase 6: Stop WAL generator and agent ==="
+kill $WAL_GEN_PID 2>/dev/null || true
+wait $WAL_GEN_PID 2>/dev/null || true
+stop_agent
+
+echo "=== Phase 7: Restore to local directory ==="
+run_agent_restore "$MOCK_SERVER" "$RESTORE_PGDATA"
+
+echo "=== Phase 8: Start local PostgreSQL on restored data ==="
+# Use a different port to avoid conflict with the containerized PG
+RESTORE_PORT=5433
+start_restored_pg "$RESTORE_PGDATA" "$RESTORE_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 9: Wait for recovery ==="
+wait_for_recovery_complete "$RESTORE_PORT" "$PG_BIN_DIR" 60
+
+echo "=== Phase 10: Verify data ==="
+verify_restored_data "$RESTORE_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 11: Cleanup ==="
+stop_pg "$RESTORE_PGDATA" "$PG_BIN_DIR"
+
+echo "pg_basebackup via docker exec: full backup-restore lifecycle passed"

agent/e2e/scripts/test-pg-host-bindir.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(dirname "$0")"
+source "$SCRIPT_DIR/backup-restore-helpers.sh"
+
+MOCK_SERVER="${MOCK_SERVER_OVERRIDE:-http://e2e-mock-server:4050}"
+PGDATA="/tmp/pgdata"
+RESTORE_PGDATA="/tmp/restore-pgdata"
+WAL_QUEUE="/tmp/wal-queue"
+PG_PORT=5433
+CUSTOM_BIN_DIR="/opt/pg/bin"
+
+PG_BIN_DIR=$(find_pg_bin_dir)
+echo "Using PG bin dir: $PG_BIN_DIR"
+
+# Copy pg_basebackup to a custom directory (simulates non-PATH installation)
+mkdir -p "$CUSTOM_BIN_DIR"
+cp "$PG_BIN_DIR/pg_basebackup" "$CUSTOM_BIN_DIR/pg_basebackup"
+
+echo "=== Phase 1: Setup agent ==="
+setup_agent
+
+echo "=== Phase 2: Initialize PostgreSQL ==="
+init_pg_local "$PGDATA" "$PG_PORT" "$WAL_QUEUE" "$PG_BIN_DIR"
+
+echo "=== Phase 3: Insert test data ==="
+insert_test_data "$PG_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 4: Force checkpoint and start agent backup (using --pg-host-bin-dir) ==="
+force_checkpoint "$PG_PORT" "$PG_BIN_DIR"
+run_agent_backup "$MOCK_SERVER" "127.0.0.1" "$PG_PORT" "$WAL_QUEUE" "host" "$CUSTOM_BIN_DIR"
+
+echo "=== Phase 5: Generate WAL in background ==="
+generate_wal_background "$PG_PORT" "$PG_BIN_DIR" &
+WAL_GEN_PID=$!
+
+echo "=== Phase 6: Wait for backup to complete ==="
+wait_for_backup_complete "$MOCK_SERVER" 120
+
+echo "=== Phase 7: Stop WAL generator, agent, and PostgreSQL ==="
+kill $WAL_GEN_PID 2>/dev/null || true
+wait $WAL_GEN_PID 2>/dev/null || true
+stop_agent
+stop_pg "$PGDATA" "$PG_BIN_DIR"
+
+echo "=== Phase 8: Restore ==="
+run_agent_restore "$MOCK_SERVER" "$RESTORE_PGDATA"
+
+echo "=== Phase 9: Start PostgreSQL on restored data ==="
+start_restored_pg "$RESTORE_PGDATA" "$PG_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 10: Wait for recovery ==="
+wait_for_recovery_complete "$PG_PORT" "$PG_BIN_DIR" 60
+
+echo "=== Phase 11: Verify data ==="
+verify_restored_data "$PG_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 12: Cleanup ==="
+stop_pg "$RESTORE_PGDATA" "$PG_BIN_DIR"
+
+echo "pg_basebackup via custom bindir: full backup-restore lifecycle passed"

agent/e2e/scripts/test-pg-host-path.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(dirname "$0")"
+source "$SCRIPT_DIR/backup-restore-helpers.sh"
+
+MOCK_SERVER="${MOCK_SERVER_OVERRIDE:-http://e2e-mock-server:4050}"
+PGDATA="/tmp/pgdata"
+RESTORE_PGDATA="/tmp/restore-pgdata"
+WAL_QUEUE="/tmp/wal-queue"
+PG_PORT=5433
+
+PG_BIN_DIR=$(find_pg_bin_dir)
+echo "Using PG bin dir: $PG_BIN_DIR"
+
+# Verify pg_basebackup is in PATH
+if ! which pg_basebackup > /dev/null 2>&1; then
+  echo "FAIL: pg_basebackup not found in PATH (test setup issue)"
+  exit 1
+fi
+
+echo "=== Phase 1: Setup agent ==="
+setup_agent
+
+echo "=== Phase 2: Initialize PostgreSQL ==="
+init_pg_local "$PGDATA" "$PG_PORT" "$WAL_QUEUE" "$PG_BIN_DIR"
+
+echo "=== Phase 3: Insert test data ==="
+insert_test_data "$PG_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 4: Force checkpoint and start agent backup ==="
+force_checkpoint "$PG_PORT" "$PG_BIN_DIR"
+run_agent_backup "$MOCK_SERVER" "127.0.0.1" "$PG_PORT" "$WAL_QUEUE" "host"
+
+echo "=== Phase 5: Generate WAL in background ==="
+generate_wal_background "$PG_PORT" "$PG_BIN_DIR" &
+WAL_GEN_PID=$!
+
+echo "=== Phase 6: Wait for backup to complete ==="
+wait_for_backup_complete "$MOCK_SERVER" 120
+
+echo "=== Phase 7: Stop WAL generator, agent, and PostgreSQL ==="
+kill $WAL_GEN_PID 2>/dev/null || true
+wait $WAL_GEN_PID 2>/dev/null || true
+stop_agent
+stop_pg "$PGDATA" "$PG_BIN_DIR"
+
+echo "=== Phase 8: Restore ==="
+run_agent_restore "$MOCK_SERVER" "$RESTORE_PGDATA"
+
+echo "=== Phase 9: Start PostgreSQL on restored data ==="
+start_restored_pg "$RESTORE_PGDATA" "$PG_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 10: Wait for recovery ==="
+wait_for_recovery_complete "$PG_PORT" "$PG_BIN_DIR" 60
+
+echo "=== Phase 11: Verify data ==="
+verify_restored_data "$PG_PORT" "$PG_BIN_DIR"
+
+echo "=== Phase 12: Cleanup ==="
+stop_pg "$RESTORE_PGDATA" "$PG_BIN_DIR"
+
+echo "pg_basebackup in PATH: full backup-restore lifecycle passed"

agent/e2e/scripts/test-upgrade-background.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+set -euo pipefail
+
+ARTIFACTS="/opt/agent/artifacts"
+AGENT="/tmp/test-agent"
+
+# Cleanup from previous runs
+pkill -f "test-agent" 2>/dev/null || true
+for i in $(seq 1 20); do
+  pgrep -f "test-agent" > /dev/null 2>&1 || break
+  sleep 0.5
+done
+pkill -9 -f "test-agent" 2>/dev/null || true
+sleep 0.5
+rm -f "$AGENT" "$AGENT.update" databasus.lock databasus.log databasus.log.old databasus.json 2>/dev/null || true
+
+# Set mock server to v1.0.0 (same as agent — no sync upgrade on start)
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-version \
+  -H "Content-Type: application/json" \
+  -d '{"version":"v1.0.0"}'
+
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-binary-path \
+  -H "Content-Type: application/json" \
+  -d '{"binaryPath":"/artifacts/agent-v1"}'
+
+# Copy v1 binary to writable location
+cp "$ARTIFACTS/agent-v1" "$AGENT"
+chmod +x "$AGENT"
+
+# Verify initial version
+VERSION=$("$AGENT" version)
+if [ "$VERSION" != "v1.0.0" ]; then
+  echo "FAIL: Expected initial version v1.0.0, got $VERSION"
+  exit 1
+fi
+echo "Initial version: $VERSION"
+
+# Start agent as daemon (versions match → no sync upgrade)
+mkdir -p /tmp/wal
+"$AGENT" start \
+  --databasus-host http://e2e-mock-server:4050 \
+  --db-id test-db-id \
+  --token test-token \
+  --pg-host e2e-postgres \
+  --pg-port 5432 \
+  --pg-user testuser \
+  --pg-password testpassword \
+  --pg-wal-dir /tmp/wal \
+  --pg-type host
+
+echo "Agent started as daemon, waiting for stabilization..."
+sleep 2
+
+# Change mock server to v2.0.0 and point to v2 binary
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-version \
+  -H "Content-Type: application/json" \
+  -d '{"version":"v2.0.0"}'
+
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-binary-path \
+  -H "Content-Type: application/json" \
+  -d '{"binaryPath":"/artifacts/agent-v2"}'
+
+echo "Mock server updated to v2.0.0, waiting for background upgrade..."
+
+# Poll for upgrade (timeout 60s, poll every 3s)
+DEADLINE=$((SECONDS + 60))
+while [ $SECONDS -lt $DEADLINE ]; do
+  VERSION=$("$AGENT" version)
+  if [ "$VERSION" = "v2.0.0" ]; then
+    echo "Binary upgraded to $VERSION"
+    break
+  fi
+  sleep 3
+done
+
+VERSION=$("$AGENT" version)
+if [ "$VERSION" != "v2.0.0" ]; then
+  echo "FAIL: Expected v2.0.0 after background upgrade, got $VERSION"
+  cat databasus.log 2>/dev/null || true
+  exit 1
+fi
+
+# Verify agent is still running after restart
+sleep 2
+"$AGENT" status || true
+
+# Cleanup
+"$AGENT" stop || true
+
+echo "Background upgrade test passed"

agent/e2e/scripts/test-upgrade-skip.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+set -euo pipefail
+
+ARTIFACTS="/opt/agent/artifacts"
+AGENT="/tmp/test-agent"
+
+# Cleanup from previous runs
+pkill -f "test-agent" 2>/dev/null || true
+for i in $(seq 1 20); do
+  pgrep -f "test-agent" > /dev/null 2>&1 || break
+  sleep 0.5
+done
+pkill -9 -f "test-agent" 2>/dev/null || true
+sleep 0.5
+rm -f "$AGENT" "$AGENT.update" databasus.lock databasus.log databasus.log.old databasus.json 2>/dev/null || true
+
+# Set mock server to return v1.0.0 (same as agent)
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-version \
+  -H "Content-Type: application/json" \
+  -d '{"version":"v1.0.0"}'
+
+# Copy v1 binary to writable location
+cp "$ARTIFACTS/agent-v1" "$AGENT"
+chmod +x "$AGENT"
+
+# Verify initial version
+VERSION=$("$AGENT" version)
+if [ "$VERSION" != "v1.0.0" ]; then
+  echo "FAIL: Expected initial version v1.0.0, got $VERSION"
+  exit 1
+fi
+
+# Run start — agent should see version matches and skip upgrade
+echo "Running agent start (expecting upgrade skip)..."
+OUTPUT=$("$AGENT" start \
+  --databasus-host http://e2e-mock-server:4050 \
+  --db-id test-db-id \
+  --token test-token \
+  --pg-host e2e-postgres \
+  --pg-port 5432 \
+  --pg-user testuser \
+  --pg-password testpassword \
+  --pg-wal-dir /tmp/wal \
+  --pg-type host 2>&1) || true
+
+echo "$OUTPUT"
+
+# Verify output contains "up to date"
+if ! echo "$OUTPUT" | grep -qi "up to date"; then
+  echo "FAIL: Expected output to contain 'up to date'"
+  exit 1
+fi
+
+# Verify binary is still v1
+VERSION=$("$AGENT" version)
+if [ "$VERSION" != "v1.0.0" ]; then
+  echo "FAIL: Expected version v1.0.0 (unchanged), got $VERSION"
+  exit 1
+fi
+
+echo "Upgrade correctly skipped, version still $VERSION"
+
+# Cleanup daemon
+"$AGENT" stop || true

agent/e2e/scripts/test-upgrade-success.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+set -euo pipefail
+
+ARTIFACTS="/opt/agent/artifacts"
+AGENT="/tmp/test-agent"
+
+# Cleanup from previous runs
+pkill -f "test-agent" 2>/dev/null || true
+for i in $(seq 1 20); do
+  pgrep -f "test-agent" > /dev/null 2>&1 || break
+  sleep 0.5
+done
+pkill -9 -f "test-agent" 2>/dev/null || true
+sleep 0.5
+rm -f "$AGENT" "$AGENT.update" databasus.lock databasus.log databasus.log.old databasus.json 2>/dev/null || true
+
+# Ensure mock server returns v2.0.0 and serves v2 binary
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-version \
+  -H "Content-Type: application/json" \
+  -d '{"version":"v2.0.0"}'
+
+curl -sf -X POST http://e2e-mock-server:4050/mock/set-binary-path \
+  -H "Content-Type: application/json" \
+  -d '{"binaryPath":"/artifacts/agent-v2"}'
+
+# Copy v1 binary to writable location
+cp "$ARTIFACTS/agent-v1" "$AGENT"
+chmod +x "$AGENT"
+
+# Verify initial version
+VERSION=$("$AGENT" version)
+if [ "$VERSION" != "v1.0.0" ]; then
+  echo "FAIL: Expected initial version v1.0.0, got $VERSION"
+  exit 1
+fi
+echo "Initial version: $VERSION"
+
+# Run start — agent will:
+# 1. Fetch version from mock (v2.0.0 != v1.0.0)
+# 2. Download v2 binary from mock
+# 3. Replace itself on disk
+# 4. Re-exec with same args
+# 5. Re-exec'd v2 fetches version (v2.0.0 == v2.0.0) → skips update
+# 6. Proceeds to start → verifies pg_basebackup + DB → exits 0 (stub)
+echo "Running agent start (expecting upgrade v1 -> v2)..."
+OUTPUT=$("$AGENT" start \
+  --databasus-host http://e2e-mock-server:4050 \
+  --db-id test-db-id \
+  --token test-token \
+  --pg-host e2e-postgres \
+  --pg-port 5432 \
+  --pg-user testuser \
+  --pg-password testpassword \
+  --pg-wal-dir /tmp/wal \
+  --pg-type host 2>&1) || true
+
+echo "$OUTPUT"
+
+# Verify binary on disk is now v2
+VERSION=$("$AGENT" version)
+if [ "$VERSION" != "v2.0.0" ]; then
+  echo "FAIL: Expected upgraded version v2.0.0, got $VERSION"
+  exit 1
+fi
+
+echo "Binary upgraded successfully to $VERSION"
+
+# Cleanup daemon
+"$AGENT" stop || true

agent/go.mod

@@ -0,0 +1,22 @@
+module databasus-agent
+
+go 1.26.1
+
+require (
+	github.com/go-resty/resty/v2 v2.17.2
+	github.com/jackc/pgx/v5 v5.8.0
+	github.com/klauspost/compress v1.18.4
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	golang.org/x/net v0.43.0 // indirect
+	golang.org/x/text v0.29.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

agent/go.sum

@@ -0,0 +1,43 @@
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-resty/resty/v2 v2.17.2 h1:FQW5oHYcIlkCNrMD2lloGScxcHJ0gkjshV3qcQAyHQk=
+github.com/go-resty/resty/v2 v2.17.2/go.mod h1:kCKZ3wWmwJaNc7S29BRtUhJwy7iqmn+2mLtQrOyQlVA=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
+github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/net v0.43.0 h1:lat02VYK2j4aLzMzecihNvTlJNQUq316m2Mr9rnM6YE=
+golang.org/x/net v0.43.0/go.mod h1:vhO1fvI4dGsIjh73sWfUVjj3N7CA9WkKJNQm2svM6Jg=
+golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
+golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
+golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

agent/internal/config/config.go

@@ -0,0 +1,271 @@
+package config
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+
+	"databasus-agent/internal/logger"
+)
+
+var log = logger.GetLogger()
+
+const configFileName = "databasus.json"
+
+type Config struct {
+	DatabasusHost          string `json:"databasusHost"`
+	DbID                   string `json:"dbId"`
+	Token                  string `json:"token"`
+	PgHost                 string `json:"pgHost"`
+	PgPort                 int    `json:"pgPort"`
+	PgUser                 string `json:"pgUser"`
+	PgPassword             string `json:"pgPassword"`
+	PgType                 string `json:"pgType"`
+	PgHostBinDir           string `json:"pgHostBinDir"`
+	PgDockerContainerName  string `json:"pgDockerContainerName"`
+	PgWalDir               string `json:"pgWalDir"`
+	IsDeleteWalAfterUpload *bool  `json:"deleteWalAfterUpload"`
+
+	flags parsedFlags
+}
+
+// LoadFromJSONAndArgs reads databasus.json into the struct
+// and overrides JSON values with any explicitly provided CLI flags.
+func (c *Config) LoadFromJSONAndArgs(fs *flag.FlagSet, args []string) {
+	c.loadFromJSON()
+	c.applyDefaults()
+	c.initSources()
+
+	c.flags.databasusHost = fs.String(
+		"databasus-host",
+		"",
+		"Databasus server URL (e.g. http://your-server:4005)",
+	)
+	c.flags.dbID = fs.String("db-id", "", "Database ID")
+	c.flags.token = fs.String("token", "", "Agent token")
+	c.flags.pgHost = fs.String("pg-host", "", "PostgreSQL host")
+	c.flags.pgPort = fs.Int("pg-port", 0, "PostgreSQL port")
+	c.flags.pgUser = fs.String("pg-user", "", "PostgreSQL user")
+	c.flags.pgPassword = fs.String("pg-password", "", "PostgreSQL password")
+	c.flags.pgType = fs.String("pg-type", "", "PostgreSQL type: host or docker")
+	c.flags.pgHostBinDir = fs.String("pg-host-bin-dir", "", "Path to PG bin directory (host mode)")
+	c.flags.pgDockerContainerName = fs.String("pg-docker-container-name", "", "Docker container name (docker mode)")
+	c.flags.pgWalDir = fs.String("pg-wal-dir", "", "Path to WAL queue directory")
+
+	if err := fs.Parse(args); err != nil {
+		os.Exit(1)
+	}
+
+	c.applyFlags()
+	log.Info("========= Loading config ============")
+	c.logConfigSources()
+	log.Info("========= Config has been loaded ====")
+}
+
+// SaveToJSON writes the current struct to databasus.json.
+func (c *Config) SaveToJSON() error {
+	data, err := json.MarshalIndent(c, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(configFileName, data, 0o644)
+}
+
+func (c *Config) LoadFromJSON() {
+	c.loadFromJSON()
+	c.applyDefaults()
+}
+
+func (c *Config) loadFromJSON() {
+	data, err := os.ReadFile(configFileName)
+	if err != nil {
+		if os.IsNotExist(err) {
+			log.Info("No databasus.json found, will create on save")
+			return
+		}
+
+		log.Warn("Failed to read databasus.json", "error", err)
+
+		return
+	}
+
+	if err := json.Unmarshal(data, c); err != nil {
+		log.Warn("Failed to parse databasus.json", "error", err)
+
+		return
+	}
+
+	log.Info("Configuration loaded from " + configFileName)
+}
+
+func (c *Config) applyDefaults() {
+	if c.PgPort == 0 {
+		c.PgPort = 5432
+	}
+
+	if c.PgType == "" {
+		c.PgType = "host"
+	}
+
+	if c.IsDeleteWalAfterUpload == nil {
+		c.IsDeleteWalAfterUpload = new(true)
+	}
+}
+
+func (c *Config) initSources() {
+	c.flags.sources = map[string]string{
+		"databasus-host":           "not configured",
+		"db-id":                    "not configured",
+		"token":                    "not configured",
+		"pg-host":                  "not configured",
+		"pg-port":                  "not configured",
+		"pg-user":                  "not configured",
+		"pg-password":              "not configured",
+		"pg-type":                  "not configured",
+		"pg-host-bin-dir":          "not configured",
+		"pg-docker-container-name": "not configured",
+		"pg-wal-dir":               "not configured",
+		"delete-wal-after-upload":  "not configured",
+	}
+
+	if c.DatabasusHost != "" {
+		c.flags.sources["databasus-host"] = configFileName
+	}
+
+	if c.DbID != "" {
+		c.flags.sources["db-id"] = configFileName
+	}
+
+	if c.Token != "" {
+		c.flags.sources["token"] = configFileName
+	}
+
+	if c.PgHost != "" {
+		c.flags.sources["pg-host"] = configFileName
+	}
+
+	// PgPort always has a value after applyDefaults
+	c.flags.sources["pg-port"] = configFileName
+
+	if c.PgUser != "" {
+		c.flags.sources["pg-user"] = configFileName
+	}
+
+	if c.PgPassword != "" {
+		c.flags.sources["pg-password"] = configFileName
+	}
+
+	// PgType always has a value after applyDefaults
+	c.flags.sources["pg-type"] = configFileName
+
+	if c.PgHostBinDir != "" {
+		c.flags.sources["pg-host-bin-dir"] = configFileName
+	}
+
+	if c.PgDockerContainerName != "" {
+		c.flags.sources["pg-docker-container-name"] = configFileName
+	}
+
+	if c.PgWalDir != "" {
+		c.flags.sources["pg-wal-dir"] = configFileName
+	}
+
+	// IsDeleteWalAfterUpload always has a value after applyDefaults
+	c.flags.sources["delete-wal-after-upload"] = configFileName
+}
+
+func (c *Config) applyFlags() {
+	if c.flags.databasusHost != nil && *c.flags.databasusHost != "" {
+		c.DatabasusHost = *c.flags.databasusHost
+		c.flags.sources["databasus-host"] = "command line args"
+	}
+
+	if c.flags.dbID != nil && *c.flags.dbID != "" {
+		c.DbID = *c.flags.dbID
+		c.flags.sources["db-id"] = "command line args"
+	}
+
+	if c.flags.token != nil && *c.flags.token != "" {
+		c.Token = *c.flags.token
+		c.flags.sources["token"] = "command line args"
+	}
+
+	if c.flags.pgHost != nil && *c.flags.pgHost != "" {
+		c.PgHost = *c.flags.pgHost
+		c.flags.sources["pg-host"] = "command line args"
+	}
+
+	if c.flags.pgPort != nil && *c.flags.pgPort != 0 {
+		c.PgPort = *c.flags.pgPort
+		c.flags.sources["pg-port"] = "command line args"
+	}
+
+	if c.flags.pgUser != nil && *c.flags.pgUser != "" {
+		c.PgUser = *c.flags.pgUser
+		c.flags.sources["pg-user"] = "command line args"
+	}
+
+	if c.flags.pgPassword != nil && *c.flags.pgPassword != "" {
+		c.PgPassword = *c.flags.pgPassword
+		c.flags.sources["pg-password"] = "command line args"
+	}
+
+	if c.flags.pgType != nil && *c.flags.pgType != "" {
+		c.PgType = *c.flags.pgType
+		c.flags.sources["pg-type"] = "command line args"
+	}
+
+	if c.flags.pgHostBinDir != nil && *c.flags.pgHostBinDir != "" {
+		c.PgHostBinDir = *c.flags.pgHostBinDir
+		c.flags.sources["pg-host-bin-dir"] = "command line args"
+	}
+
+	if c.flags.pgDockerContainerName != nil && *c.flags.pgDockerContainerName != "" {
+		c.PgDockerContainerName = *c.flags.pgDockerContainerName
+		c.flags.sources["pg-docker-container-name"] = "command line args"
+	}
+
+	if c.flags.pgWalDir != nil && *c.flags.pgWalDir != "" {
+		c.PgWalDir = *c.flags.pgWalDir
+		c.flags.sources["pg-wal-dir"] = "command line args"
+	}
+}
+
+func (c *Config) logConfigSources() {
+	log.Info("databasus-host", "value", c.DatabasusHost, "source", c.flags.sources["databasus-host"])
+	log.Info("db-id", "value", c.DbID, "source", c.flags.sources["db-id"])
+	log.Info("token", "value", maskSensitive(c.Token), "source", c.flags.sources["token"])
+	log.Info("pg-host", "value", c.PgHost, "source", c.flags.sources["pg-host"])
+	log.Info("pg-port", "value", c.PgPort, "source", c.flags.sources["pg-port"])
+	log.Info("pg-user", "value", c.PgUser, "source", c.flags.sources["pg-user"])
+	log.Info("pg-password", "value", maskSensitive(c.PgPassword), "source", c.flags.sources["pg-password"])
+	log.Info("pg-type", "value", c.PgType, "source", c.flags.sources["pg-type"])
+	log.Info("pg-host-bin-dir", "value", c.PgHostBinDir, "source", c.flags.sources["pg-host-bin-dir"])
+	log.Info(
+		"pg-docker-container-name",
+		"value",
+		c.PgDockerContainerName,
+		"source",
+		c.flags.sources["pg-docker-container-name"],
+	)
+	log.Info("pg-wal-dir", "value", c.PgWalDir, "source", c.flags.sources["pg-wal-dir"])
+	log.Info(
+		"delete-wal-after-upload",
+		"value",
+		fmt.Sprintf("%v", *c.IsDeleteWalAfterUpload),
+		"source",
+		c.flags.sources["delete-wal-after-upload"],
+	)
+}
+
+func maskSensitive(value string) string {
+	if value == "" {
+		return "(not set)"
+	}
+
+	visibleLen := max(len(value)/4, 1)
+
+	return value[:visibleLen] + "***"
+}

agent/internal/config/config_test.go

@@ -0,0 +1,301 @@
+package config
+
+import (
+	"encoding/json"
+	"flag"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_LoadFromJSONAndArgs_ValuesLoadedFromJSON(t *testing.T) {
+	dir := setupTempDir(t)
+	writeConfigJSON(t, dir, Config{
+		DatabasusHost: "http://json-host:4005",
+		DbID:          "json-db-id",
+		Token:         "json-token",
+	})
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{})
+
+	assert.Equal(t, "http://json-host:4005", cfg.DatabasusHost)
+	assert.Equal(t, "json-db-id", cfg.DbID)
+	assert.Equal(t, "json-token", cfg.Token)
+}
+
+func Test_LoadFromJSONAndArgs_ValuesLoadedFromArgs_WhenNoJSON(t *testing.T) {
+	setupTempDir(t)
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{
+		"--databasus-host", "http://arg-host:4005",
+		"--db-id", "arg-db-id",
+		"--token", "arg-token",
+	})
+
+	assert.Equal(t, "http://arg-host:4005", cfg.DatabasusHost)
+	assert.Equal(t, "arg-db-id", cfg.DbID)
+	assert.Equal(t, "arg-token", cfg.Token)
+}
+
+func Test_LoadFromJSONAndArgs_ArgsOverrideJSON(t *testing.T) {
+	dir := setupTempDir(t)
+	writeConfigJSON(t, dir, Config{
+		DatabasusHost: "http://json-host:4005",
+		DbID:          "json-db-id",
+		Token:         "json-token",
+	})
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{
+		"--databasus-host", "http://arg-host:9999",
+		"--db-id", "arg-db-id-override",
+		"--token", "arg-token-override",
+	})
+
+	assert.Equal(t, "http://arg-host:9999", cfg.DatabasusHost)
+	assert.Equal(t, "arg-db-id-override", cfg.DbID)
+	assert.Equal(t, "arg-token-override", cfg.Token)
+}
+
+func Test_LoadFromJSONAndArgs_PartialArgsOverrideJSON(t *testing.T) {
+	dir := setupTempDir(t)
+	writeConfigJSON(t, dir, Config{
+		DatabasusHost: "http://json-host:4005",
+		DbID:          "json-db-id",
+		Token:         "json-token",
+	})
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{
+		"--databasus-host", "http://arg-host-only:4005",
+	})
+
+	assert.Equal(t, "http://arg-host-only:4005", cfg.DatabasusHost)
+	assert.Equal(t, "json-db-id", cfg.DbID)
+	assert.Equal(t, "json-token", cfg.Token)
+}
+
+func Test_SaveToJSON_ConfigSavedCorrectly(t *testing.T) {
+	setupTempDir(t)
+
+	deleteWal := true
+	cfg := &Config{
+		DatabasusHost:          "http://save-host:4005",
+		DbID:                   "save-db-id",
+		Token:                  "save-token",
+		IsDeleteWalAfterUpload: &deleteWal,
+	}
+
+	err := cfg.SaveToJSON()
+	require.NoError(t, err)
+
+	saved := readConfigJSON(t)
+
+	assert.Equal(t, "http://save-host:4005", saved.DatabasusHost)
+	assert.Equal(t, "save-db-id", saved.DbID)
+	assert.Equal(t, "save-token", saved.Token)
+}
+
+func Test_SaveToJSON_AfterArgsOverrideJSON_SavedFileContainsMergedValues(t *testing.T) {
+	dir := setupTempDir(t)
+	writeConfigJSON(t, dir, Config{
+		DatabasusHost: "http://json-host:4005",
+		DbID:          "json-db-id",
+		Token:         "json-token",
+	})
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{
+		"--databasus-host", "http://override-host:9999",
+	})
+
+	err := cfg.SaveToJSON()
+	require.NoError(t, err)
+
+	saved := readConfigJSON(t)
+
+	assert.Equal(t, "http://override-host:9999", saved.DatabasusHost)
+	assert.Equal(t, "json-db-id", saved.DbID)
+	assert.Equal(t, "json-token", saved.Token)
+}
+
+func Test_LoadFromJSONAndArgs_PgFieldsLoadedFromJSON(t *testing.T) {
+	dir := setupTempDir(t)
+	deleteWal := false
+	writeConfigJSON(t, dir, Config{
+		DatabasusHost:          "http://json-host:4005",
+		DbID:                   "json-db-id",
+		Token:                  "json-token",
+		PgHost:                 "pg-json-host",
+		PgPort:                 5433,
+		PgUser:                 "pg-json-user",
+		PgPassword:             "pg-json-pass",
+		PgType:                 "docker",
+		PgHostBinDir:           "/usr/bin",
+		PgDockerContainerName:  "pg-container",
+		PgWalDir:               "/opt/wal",
+		IsDeleteWalAfterUpload: &deleteWal,
+	})
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{})
+
+	assert.Equal(t, "pg-json-host", cfg.PgHost)
+	assert.Equal(t, 5433, cfg.PgPort)
+	assert.Equal(t, "pg-json-user", cfg.PgUser)
+	assert.Equal(t, "pg-json-pass", cfg.PgPassword)
+	assert.Equal(t, "docker", cfg.PgType)
+	assert.Equal(t, "/usr/bin", cfg.PgHostBinDir)
+	assert.Equal(t, "pg-container", cfg.PgDockerContainerName)
+	assert.Equal(t, "/opt/wal", cfg.PgWalDir)
+	assert.Equal(t, false, *cfg.IsDeleteWalAfterUpload)
+}
+
+func Test_LoadFromJSONAndArgs_PgFieldsLoadedFromArgs(t *testing.T) {
+	setupTempDir(t)
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{
+		"--pg-host", "arg-pg-host",
+		"--pg-port", "5433",
+		"--pg-user", "arg-pg-user",
+		"--pg-password", "arg-pg-pass",
+		"--pg-type", "docker",
+		"--pg-host-bin-dir", "/custom/bin",
+		"--pg-docker-container-name", "my-pg",
+		"--pg-wal-dir", "/var/wal",
+	})
+
+	assert.Equal(t, "arg-pg-host", cfg.PgHost)
+	assert.Equal(t, 5433, cfg.PgPort)
+	assert.Equal(t, "arg-pg-user", cfg.PgUser)
+	assert.Equal(t, "arg-pg-pass", cfg.PgPassword)
+	assert.Equal(t, "docker", cfg.PgType)
+	assert.Equal(t, "/custom/bin", cfg.PgHostBinDir)
+	assert.Equal(t, "my-pg", cfg.PgDockerContainerName)
+	assert.Equal(t, "/var/wal", cfg.PgWalDir)
+}
+
+func Test_LoadFromJSONAndArgs_PgArgsOverrideJSON(t *testing.T) {
+	dir := setupTempDir(t)
+	writeConfigJSON(t, dir, Config{
+		PgHost:   "json-host",
+		PgPort:   5432,
+		PgUser:   "json-user",
+		PgType:   "host",
+		PgWalDir: "/json/wal",
+	})
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{
+		"--pg-host", "arg-host",
+		"--pg-port", "5433",
+		"--pg-user", "arg-user",
+		"--pg-type", "docker",
+		"--pg-docker-container-name", "my-container",
+		"--pg-wal-dir", "/arg/wal",
+	})
+
+	assert.Equal(t, "arg-host", cfg.PgHost)
+	assert.Equal(t, 5433, cfg.PgPort)
+	assert.Equal(t, "arg-user", cfg.PgUser)
+	assert.Equal(t, "docker", cfg.PgType)
+	assert.Equal(t, "my-container", cfg.PgDockerContainerName)
+	assert.Equal(t, "/arg/wal", cfg.PgWalDir)
+}
+
+func Test_LoadFromJSONAndArgs_DefaultsApplied_WhenNoJSONAndNoArgs(t *testing.T) {
+	setupTempDir(t)
+
+	cfg := &Config{}
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	cfg.LoadFromJSONAndArgs(fs, []string{})
+
+	assert.Equal(t, 5432, cfg.PgPort)
+	assert.Equal(t, "host", cfg.PgType)
+	require.NotNil(t, cfg.IsDeleteWalAfterUpload)
+	assert.Equal(t, true, *cfg.IsDeleteWalAfterUpload)
+}
+
+func Test_SaveToJSON_PgFieldsSavedCorrectly(t *testing.T) {
+	setupTempDir(t)
+
+	deleteWal := false
+	cfg := &Config{
+		DatabasusHost:          "http://host:4005",
+		DbID:                   "db-id",
+		Token:                  "token",
+		PgHost:                 "pg-host",
+		PgPort:                 5433,
+		PgUser:                 "pg-user",
+		PgPassword:             "pg-pass",
+		PgType:                 "docker",
+		PgHostBinDir:           "/usr/bin",
+		PgDockerContainerName:  "pg-container",
+		PgWalDir:               "/opt/wal",
+		IsDeleteWalAfterUpload: &deleteWal,
+	}
+
+	err := cfg.SaveToJSON()
+	require.NoError(t, err)
+
+	saved := readConfigJSON(t)
+
+	assert.Equal(t, "pg-host", saved.PgHost)
+	assert.Equal(t, 5433, saved.PgPort)
+	assert.Equal(t, "pg-user", saved.PgUser)
+	assert.Equal(t, "pg-pass", saved.PgPassword)
+	assert.Equal(t, "docker", saved.PgType)
+	assert.Equal(t, "/usr/bin", saved.PgHostBinDir)
+	assert.Equal(t, "pg-container", saved.PgDockerContainerName)
+	assert.Equal(t, "/opt/wal", saved.PgWalDir)
+	require.NotNil(t, saved.IsDeleteWalAfterUpload)
+	assert.Equal(t, false, *saved.IsDeleteWalAfterUpload)
+}
+
+func setupTempDir(t *testing.T) string {
+	t.Helper()
+
+	origDir, err := os.Getwd()
+	require.NoError(t, err)
+
+	dir := t.TempDir()
+	require.NoError(t, os.Chdir(dir))
+
+	t.Cleanup(func() { os.Chdir(origDir) })
+
+	return dir
+}
+
+func writeConfigJSON(t *testing.T, dir string, cfg Config) {
+	t.Helper()
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	require.NoError(t, err)
+
+	require.NoError(t, os.WriteFile(dir+"/"+configFileName, data, 0o644))
+}
+
+func readConfigJSON(t *testing.T) Config {
+	t.Helper()
+
+	data, err := os.ReadFile(configFileName)
+	require.NoError(t, err)
+
+	var cfg Config
+	require.NoError(t, json.Unmarshal(data, &cfg))
+
+	return cfg
+}

agent/internal/config/dto.go

@@ -0,0 +1,17 @@
+package config
+
+type parsedFlags struct {
+	databasusHost         *string
+	dbID                  *string
+	token                 *string
+	pgHost                *string
+	pgPort                *int
+	pgUser                *string
+	pgPassword            *string
+	pgType                *string
+	pgHostBinDir          *string
+	pgDockerContainerName *string
+	pgWalDir              *string
+
+	sources map[string]string
+}

agent/internal/features/api/api.go

@@ -0,0 +1,376 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"os"
+	"time"
+
+	"github.com/go-resty/resty/v2"
+)
+
+const (
+	chainValidPath      = "/api/v1/backups/postgres/wal/is-wal-chain-valid-since-last-full-backup"
+	nextBackupTimePath  = "/api/v1/backups/postgres/wal/next-full-backup-time"
+	walUploadPath       = "/api/v1/backups/postgres/wal/upload/wal"
+	fullStartPath       = "/api/v1/backups/postgres/wal/upload/full-start"
+	fullCompletePath    = "/api/v1/backups/postgres/wal/upload/full-complete"
+	reportErrorPath     = "/api/v1/backups/postgres/wal/error"
+	restorePlanPath     = "/api/v1/backups/postgres/wal/restore/plan"
+	restoreDownloadPath = "/api/v1/backups/postgres/wal/restore/download"
+	versionPath         = "/api/v1/system/version"
+	agentBinaryPath     = "/api/v1/system/agent"
+
+	apiCallTimeout   = 30 * time.Second
+	maxRetryAttempts = 3
+	retryBaseDelay   = 1 * time.Second
+)
+
+// For stream uploads (basebackup and WAL segments) the standard resty client is not used,
+// because it buffers the entire body in memory before sending.
+type Client struct {
+	json       *resty.Client
+	streamHTTP *http.Client
+	host       string
+	token      string
+	log        *slog.Logger
+}
+
+func NewClient(host, token string, log *slog.Logger) *Client {
+	setAuth := func(_ *resty.Client, req *resty.Request) error {
+		if token != "" {
+			req.SetHeader("Authorization", token)
+		}
+
+		return nil
+	}
+
+	jsonClient := resty.New().
+		SetTimeout(apiCallTimeout).
+		SetRetryCount(maxRetryAttempts - 1).
+		SetRetryWaitTime(retryBaseDelay).
+		SetRetryMaxWaitTime(4 * retryBaseDelay).
+		AddRetryCondition(func(resp *resty.Response, err error) bool {
+			return err != nil || resp.StatusCode() >= 500
+		}).
+		OnBeforeRequest(setAuth)
+
+	return &Client{
+		json:       jsonClient,
+		streamHTTP: &http.Client{},
+		host:       host,
+		token:      token,
+		log:        log,
+	}
+}
+
+func (c *Client) CheckWalChainValidity(ctx context.Context) (*WalChainValidityResponse, error) {
+	var resp WalChainValidityResponse
+
+	httpResp, err := c.json.R().
+		SetContext(ctx).
+		SetResult(&resp).
+		Get(c.buildURL(chainValidPath))
+	if err != nil {
+		return nil, err
+	}
+
+	if err := c.checkResponse(httpResp, "check WAL chain validity"); err != nil {
+		return nil, err
+	}
+
+	return &resp, nil
+}
+
+func (c *Client) GetNextFullBackupTime(ctx context.Context) (*NextFullBackupTimeResponse, error) {
+	var resp NextFullBackupTimeResponse
+
+	httpResp, err := c.json.R().
+		SetContext(ctx).
+		SetResult(&resp).
+		Get(c.buildURL(nextBackupTimePath))
+	if err != nil {
+		return nil, err
+	}
+
+	if err := c.checkResponse(httpResp, "get next full backup time"); err != nil {
+		return nil, err
+	}
+
+	return &resp, nil
+}
+
+func (c *Client) ReportBackupError(ctx context.Context, errMsg string) error {
+	httpResp, err := c.json.R().
+		SetContext(ctx).
+		SetBody(reportErrorRequest{Error: errMsg}).
+		Post(c.buildURL(reportErrorPath))
+	if err != nil {
+		return err
+	}
+
+	return c.checkResponse(httpResp, "report backup error")
+}
+
+func (c *Client) UploadBasebackup(
+	ctx context.Context,
+	body io.Reader,
+) (*UploadBasebackupResponse, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.buildURL(fullStartPath), body)
+	if err != nil {
+		return nil, fmt.Errorf("create upload request: %w", err)
+	}
+
+	c.setStreamHeaders(req)
+	req.Header.Set("Content-Type", "application/octet-stream")
+
+	resp, err := c.streamHTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("upload request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+
+		return nil, fmt.Errorf("upload failed with status %d: %s", resp.StatusCode, string(respBody))
+	}
+
+	var result UploadBasebackupResponse
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode upload response: %w", err)
+	}
+
+	return &result, nil
+}
+
+func (c *Client) FinalizeBasebackup(
+	ctx context.Context,
+	backupID string,
+	startSegment string,
+	stopSegment string,
+) error {
+	resp, err := c.json.R().
+		SetContext(ctx).
+		SetBody(finalizeBasebackupRequest{
+			BackupID:     backupID,
+			StartSegment: startSegment,
+			StopSegment:  stopSegment,
+		}).
+		Post(c.buildURL(fullCompletePath))
+	if err != nil {
+		return fmt.Errorf("finalize request: %w", err)
+	}
+
+	if resp.StatusCode() != http.StatusOK {
+		return fmt.Errorf("finalize failed with status %d: %s", resp.StatusCode(), resp.String())
+	}
+
+	return nil
+}
+
+func (c *Client) FinalizeBasebackupWithError(
+	ctx context.Context,
+	backupID string,
+	errMsg string,
+) error {
+	resp, err := c.json.R().
+		SetContext(ctx).
+		SetBody(finalizeBasebackupRequest{
+			BackupID: backupID,
+			Error:    &errMsg,
+		}).
+		Post(c.buildURL(fullCompletePath))
+	if err != nil {
+		return fmt.Errorf("finalize-with-error request: %w", err)
+	}
+
+	if resp.StatusCode() != http.StatusOK {
+		return fmt.Errorf("finalize-with-error failed with status %d: %s", resp.StatusCode(), resp.String())
+	}
+
+	return nil
+}
+
+func (c *Client) UploadWalSegment(
+	ctx context.Context,
+	segmentName string,
+	body io.Reader,
+) (*UploadWalSegmentResult, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.buildURL(walUploadPath), body)
+	if err != nil {
+		return nil, fmt.Errorf("create WAL upload request: %w", err)
+	}
+
+	c.setStreamHeaders(req)
+	req.Header.Set("Content-Type", "application/octet-stream")
+	req.Header.Set("X-Wal-Segment-Name", segmentName)
+
+	resp, err := c.streamHTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("upload request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	switch resp.StatusCode {
+	case http.StatusNoContent:
+		return &UploadWalSegmentResult{IsGapDetected: false}, nil
+
+	case http.StatusConflict:
+		var errResp uploadErrorResponse
+
+		if err := json.NewDecoder(resp.Body).Decode(&errResp); err != nil {
+			return &UploadWalSegmentResult{IsGapDetected: true}, nil
+		}
+
+		return &UploadWalSegmentResult{
+			IsGapDetected:       true,
+			ExpectedSegmentName: errResp.ExpectedSegmentName,
+			ReceivedSegmentName: errResp.ReceivedSegmentName,
+		}, nil
+
+	default:
+		respBody, _ := io.ReadAll(resp.Body)
+
+		return nil, fmt.Errorf("upload failed with status %d: %s", resp.StatusCode, string(respBody))
+	}
+}
+
+func (c *Client) GetRestorePlan(
+	ctx context.Context,
+	backupID string,
+) (*GetRestorePlanResponse, *GetRestorePlanErrorResponse, error) {
+	request := c.json.R().SetContext(ctx)
+
+	if backupID != "" {
+		request.SetQueryParam("backupId", backupID)
+	}
+
+	httpResp, err := request.Get(c.buildURL(restorePlanPath))
+	if err != nil {
+		return nil, nil, fmt.Errorf("get restore plan: %w", err)
+	}
+
+	switch httpResp.StatusCode() {
+	case http.StatusOK:
+		var response GetRestorePlanResponse
+		if err := json.Unmarshal(httpResp.Body(), &response); err != nil {
+			return nil, nil, fmt.Errorf("decode restore plan response: %w", err)
+		}
+
+		return &response, nil, nil
+
+	case http.StatusBadRequest:
+		var errorResponse GetRestorePlanErrorResponse
+		if err := json.Unmarshal(httpResp.Body(), &errorResponse); err != nil {
+			return nil, nil, fmt.Errorf("decode restore plan error: %w", err)
+		}
+
+		return nil, &errorResponse, nil
+
+	default:
+		return nil, nil, fmt.Errorf("get restore plan: server returned status %d: %s",
+			httpResp.StatusCode(), httpResp.String())
+	}
+}
+
+func (c *Client) DownloadBackupFile(
+	ctx context.Context,
+	backupID string,
+) (io.ReadCloser, error) {
+	requestURL := c.buildURL(restoreDownloadPath) + "?" + url.Values{"backupId": {backupID}}.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, requestURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create download request: %w", err)
+	}
+
+	c.setStreamHeaders(req)
+
+	resp, err := c.streamHTTP.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download backup file: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+
+		return nil, fmt.Errorf("download backup file: server returned status %d: %s",
+			resp.StatusCode, string(respBody))
+	}
+
+	return resp.Body, nil
+}
+
+func (c *Client) FetchServerVersion(ctx context.Context) (string, error) {
+	var ver versionResponse
+
+	httpResp, err := c.json.R().
+		SetContext(ctx).
+		SetResult(&ver).
+		Get(c.buildURL(versionPath))
+	if err != nil {
+		return "", err
+	}
+
+	if err := c.checkResponse(httpResp, "fetch server version"); err != nil {
+		return "", err
+	}
+
+	return ver.Version, nil
+}
+
+func (c *Client) DownloadAgentBinary(ctx context.Context, arch, destPath string) error {
+	requestURL := c.buildURL(agentBinaryPath) + "?" + url.Values{"arch": {arch}}.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, requestURL, nil)
+	if err != nil {
+		return fmt.Errorf("create agent download request: %w", err)
+	}
+
+	c.setStreamHeaders(req)
+
+	resp, err := c.streamHTTP.Do(req)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("server returned %d for agent download", resp.StatusCode)
+	}
+
+	file, err := os.Create(destPath)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = file.Close() }()
+
+	_, err = io.Copy(file, resp.Body)
+
+	return err
+}
+
+func (c *Client) buildURL(path string) string {
+	return c.host + path
+}
+
+func (c *Client) checkResponse(resp *resty.Response, method string) error {
+	if resp.StatusCode() >= 400 {
+		return fmt.Errorf("%s: server returned status %d: %s", method, resp.StatusCode(), resp.String())
+	}
+
+	return nil
+}
+
+func (c *Client) setStreamHeaders(req *http.Request) {
+	if c.token != "" {
+		req.Header.Set("Authorization", c.token)
+	}
+}

agent/internal/features/api/dto.go

@@ -0,0 +1,72 @@
+package api
+
+import "time"
+
+type WalChainValidityResponse struct {
+	IsValid               bool   `json:"isValid"`
+	Error                 string `json:"error,omitempty"`
+	LastContiguousSegment string `json:"lastContiguousSegment,omitempty"`
+}
+
+type NextFullBackupTimeResponse struct {
+	NextFullBackupTime *time.Time `json:"nextFullBackupTime"`
+}
+
+type UploadWalSegmentResult struct {
+	IsGapDetected       bool
+	ExpectedSegmentName string
+	ReceivedSegmentName string
+}
+
+type reportErrorRequest struct {
+	Error string `json:"error"`
+}
+
+type versionResponse struct {
+	Version string `json:"version"`
+}
+
+type UploadBasebackupResponse struct {
+	BackupID string `json:"backupId"`
+}
+
+type finalizeBasebackupRequest struct {
+	BackupID     string  `json:"backupId"`
+	StartSegment string  `json:"startSegment"`
+	StopSegment  string  `json:"stopSegment"`
+	Error        *string `json:"error,omitempty"`
+}
+
+type uploadErrorResponse struct {
+	Error               string `json:"error"`
+	ExpectedSegmentName string `json:"expectedSegmentName"`
+	ReceivedSegmentName string `json:"receivedSegmentName"`
+}
+
+type RestorePlanFullBackup struct {
+	BackupID                  string    `json:"id"`
+	FullBackupWalStartSegment string    `json:"fullBackupWalStartSegment"`
+	FullBackupWalStopSegment  string    `json:"fullBackupWalStopSegment"`
+	PgVersion                 string    `json:"pgVersion"`
+	CreatedAt                 time.Time `json:"createdAt"`
+	SizeBytes                 int64     `json:"sizeBytes"`
+}
+
+type RestorePlanWalSegment struct {
+	BackupID    string `json:"backupId"`
+	SegmentName string `json:"segmentName"`
+	SizeBytes   int64  `json:"sizeBytes"`
+}
+
+type GetRestorePlanResponse struct {
+	FullBackup             RestorePlanFullBackup   `json:"fullBackup"`
+	WalSegments            []RestorePlanWalSegment `json:"walSegments"`
+	TotalSizeBytes         int64                   `json:"totalSizeBytes"`
+	LatestAvailableSegment string                  `json:"latestAvailableSegment"`
+}
+
+type GetRestorePlanErrorResponse struct {
+	Error                 string `json:"error"`
+	Message               string `json:"message"`
+	LastContiguousSegment string `json:"lastContiguousSegment,omitempty"`
+}

agent/internal/features/api/idle_timeout_reader.go

@@ -0,0 +1,60 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"time"
+)
+
+// IdleTimeoutReader wraps an io.Reader and cancels the associated context
+// if no bytes are successfully read within the specified timeout duration.
+// This detects stalled uploads where the network or source stops transmitting data.
+//
+// When the idle timeout fires, the reader is also closed (if it implements io.Closer)
+// to unblock any goroutine blocked on the underlying Read.
+type IdleTimeoutReader struct {
+	reader  io.Reader
+	timeout time.Duration
+	cancel  context.CancelCauseFunc
+	timer   *time.Timer
+}
+
+// NewIdleTimeoutReader creates a reader that cancels the context via cancel
+// if Read does not return any bytes for the given timeout duration.
+func NewIdleTimeoutReader(reader io.Reader, timeout time.Duration, cancel context.CancelCauseFunc) *IdleTimeoutReader {
+	r := &IdleTimeoutReader{
+		reader:  reader,
+		timeout: timeout,
+		cancel:  cancel,
+	}
+
+	r.timer = time.AfterFunc(timeout, func() {
+		cancel(fmt.Errorf("upload idle timeout: no bytes transmitted for %v", timeout))
+
+		if closer, ok := reader.(io.Closer); ok {
+			_ = closer.Close()
+		}
+	})
+
+	return r
+}
+
+func (r *IdleTimeoutReader) Read(p []byte) (int, error) {
+	n, err := r.reader.Read(p)
+
+	if n > 0 {
+		r.timer.Reset(r.timeout)
+	}
+
+	if err != nil && err != io.EOF {
+		r.Stop()
+	}
+
+	return n, err
+}
+
+// Stop cancels the idle timer. Must be called when the reader is no longer needed.
+func (r *IdleTimeoutReader) Stop() {
+	r.timer.Stop()
+}

agent/internal/features/api/idle_timeout_reader_test.go

@@ -0,0 +1,112 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_ReadThroughIdleTimeoutReader_WhenBytesFlowContinuously_DoesNotCancelContext(t *testing.T) {
+	ctx, cancel := context.WithCancelCause(t.Context())
+	defer cancel(nil)
+
+	pr, pw := io.Pipe()
+
+	idleReader := NewIdleTimeoutReader(pr, 200*time.Millisecond, cancel)
+	defer idleReader.Stop()
+
+	go func() {
+		for range 5 {
+			_, _ = pw.Write([]byte("data"))
+			time.Sleep(50 * time.Millisecond)
+		}
+
+		_ = pw.Close()
+	}()
+
+	data, err := io.ReadAll(idleReader)
+
+	require.NoError(t, err)
+	assert.Equal(t, "datadatadatadatadata", string(data))
+	assert.NoError(t, ctx.Err(), "context should not be cancelled when bytes flow continuously")
+}
+
+func Test_ReadThroughIdleTimeoutReader_WhenNoBytesTransmitted_CancelsContext(t *testing.T) {
+	ctx, cancel := context.WithCancelCause(t.Context())
+	defer cancel(nil)
+
+	pr, _ := io.Pipe()
+
+	idleReader := NewIdleTimeoutReader(pr, 100*time.Millisecond, cancel)
+	defer idleReader.Stop()
+
+	time.Sleep(200 * time.Millisecond)
+
+	assert.Error(t, ctx.Err(), "context should be cancelled when no bytes are transmitted")
+	assert.Contains(t, context.Cause(ctx).Error(), "upload idle timeout")
+}
+
+func Test_ReadThroughIdleTimeoutReader_WhenBytesStopMidStream_CancelsContext(t *testing.T) {
+	ctx, cancel := context.WithCancelCause(t.Context())
+	defer cancel(nil)
+
+	pr, pw := io.Pipe()
+
+	idleReader := NewIdleTimeoutReader(pr, 100*time.Millisecond, cancel)
+	defer idleReader.Stop()
+
+	go func() {
+		_, _ = pw.Write([]byte("initial"))
+		// Stop writing — simulate stalled source
+	}()
+
+	buf := make([]byte, 1024)
+	n, _ := idleReader.Read(buf)
+	assert.Equal(t, "initial", string(buf[:n]))
+
+	time.Sleep(200 * time.Millisecond)
+
+	assert.Error(t, ctx.Err(), "context should be cancelled when bytes stop mid-stream")
+	assert.Contains(t, context.Cause(ctx).Error(), "upload idle timeout")
+}
+
+func Test_StopIdleTimeoutReader_WhenCalledBeforeTimeout_DoesNotCancelContext(t *testing.T) {
+	ctx, cancel := context.WithCancelCause(t.Context())
+	defer cancel(nil)
+
+	pr, _ := io.Pipe()
+
+	idleReader := NewIdleTimeoutReader(pr, 100*time.Millisecond, cancel)
+	idleReader.Stop()
+
+	time.Sleep(200 * time.Millisecond)
+
+	assert.NoError(t, ctx.Err(), "context should not be cancelled when reader is stopped before timeout")
+}
+
+func Test_ReadThroughIdleTimeoutReader_WhenReaderReturnsError_PropagatesError(t *testing.T) {
+	ctx, cancel := context.WithCancelCause(t.Context())
+	defer cancel(nil)
+
+	pr, pw := io.Pipe()
+
+	idleReader := NewIdleTimeoutReader(pr, 5*time.Second, cancel)
+	defer idleReader.Stop()
+
+	expectedErr := fmt.Errorf("test read error")
+	_ = pw.CloseWithError(expectedErr)
+
+	buf := make([]byte, 1024)
+	_, err := idleReader.Read(buf)
+
+	assert.ErrorIs(t, err, expectedErr)
+
+	// Timer should be stopped after error — context should not be cancelled
+	time.Sleep(100 * time.Millisecond)
+	assert.NoError(t, ctx.Err(), "context should not be cancelled after reader error stops the timer")
+}

agent/internal/features/full_backup/backuper.go

@@ -0,0 +1,316 @@
+package full_backup
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sync/atomic"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+
+	"databasus-agent/internal/config"
+	"databasus-agent/internal/features/api"
+)
+
+const (
+	checkInterval = 30 * time.Second
+	retryDelay    = 1 * time.Minute
+	uploadTimeout = 23 * time.Hour
+)
+
+var uploadIdleTimeout = 5 * time.Minute
+
+var retryDelayOverride *time.Duration
+
+type CmdBuilder func(ctx context.Context) *exec.Cmd
+
+// FullBackuper runs pg_basebackup when the WAL chain is broken or a scheduled backup is due.
+//
+// Every 30 seconds it checks two conditions via the Databasus API:
+//  1. WAL chain validity — if broken or no full backup exists, triggers an immediate basebackup.
+//  2. Scheduled backup time — if the next full backup time has passed, triggers a basebackup.
+//
+// Only one basebackup runs at a time (guarded by atomic bool).
+// On failure the error is reported to the server and the backup retries after 1 minute, indefinitely.
+// WAL segment uploads (handled by wal.Streamer) continue independently and are not paused.
+//
+// pg_basebackup runs as "pg_basebackup -Ft -D - -X fetch --verbose --checkpoint=fast".
+// Stdout (tar) is zstd-compressed and uploaded to the server.
+// Stderr is parsed for WAL start/stop segment names (LSN → segment arithmetic).
+type FullBackuper struct {
+	cfg        *config.Config
+	apiClient  *api.Client
+	log        *slog.Logger
+	isRunning  atomic.Bool
+	cmdBuilder CmdBuilder
+}
+
+func NewFullBackuper(cfg *config.Config, apiClient *api.Client, log *slog.Logger) *FullBackuper {
+	backuper := &FullBackuper{
+		cfg:       cfg,
+		apiClient: apiClient,
+		log:       log,
+	}
+
+	backuper.cmdBuilder = backuper.defaultCmdBuilder
+
+	return backuper
+}
+
+func (backuper *FullBackuper) Run(ctx context.Context) {
+	backuper.log.Info("Full backuper started")
+
+	backuper.checkAndRunIfNeeded(ctx)
+
+	ticker := time.NewTicker(checkInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			backuper.log.Info("Full backuper stopping")
+			return
+		case <-ticker.C:
+			backuper.checkAndRunIfNeeded(ctx)
+		}
+	}
+}
+
+func (backuper *FullBackuper) checkAndRunIfNeeded(ctx context.Context) {
+	if backuper.isRunning.Load() {
+		backuper.log.Debug("Skipping check: basebackup already in progress")
+		return
+	}
+
+	chainResp, err := backuper.apiClient.CheckWalChainValidity(ctx)
+	if err != nil {
+		backuper.log.Error("Failed to check WAL chain validity", "error", err)
+		return
+	}
+
+	if !chainResp.IsValid {
+		backuper.log.Info("WAL chain is invalid, triggering basebackup",
+			"error", chainResp.Error,
+			"lastContiguousSegment", chainResp.LastContiguousSegment,
+		)
+
+		backuper.runBasebackupWithRetry(ctx)
+
+		return
+	}
+
+	nextTimeResp, err := backuper.apiClient.GetNextFullBackupTime(ctx)
+	if err != nil {
+		backuper.log.Error("Failed to check next full backup time", "error", err)
+		return
+	}
+
+	if nextTimeResp.NextFullBackupTime == nil || !nextTimeResp.NextFullBackupTime.After(time.Now().UTC()) {
+		backuper.log.Info("Scheduled full backup is due, triggering basebackup")
+		backuper.runBasebackupWithRetry(ctx)
+
+		return
+	}
+
+	backuper.log.Debug("No basebackup needed",
+		"nextFullBackupTime", nextTimeResp.NextFullBackupTime,
+	)
+}
+
+func (backuper *FullBackuper) runBasebackupWithRetry(ctx context.Context) {
+	if !backuper.isRunning.CompareAndSwap(false, true) {
+		backuper.log.Debug("Skipping basebackup: already running")
+		return
+	}
+	defer backuper.isRunning.Store(false)
+
+	for {
+		if ctx.Err() != nil {
+			return
+		}
+
+		backuper.log.Info("Starting pg_basebackup")
+
+		err := backuper.executeAndUploadBasebackup(ctx)
+		if err == nil {
+			backuper.log.Info("Basebackup completed successfully")
+			return
+		}
+
+		backuper.log.Error("Basebackup failed", "error", err)
+		backuper.reportError(ctx, err.Error())
+
+		delay := retryDelay
+		if retryDelayOverride != nil {
+			delay = *retryDelayOverride
+		}
+
+		backuper.log.Info("Retrying basebackup after delay", "delay", delay)
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(delay):
+		}
+	}
+}
+
+func (backuper *FullBackuper) executeAndUploadBasebackup(ctx context.Context) error {
+	cmd := backuper.cmdBuilder(ctx)
+
+	var stderrBuf bytes.Buffer
+	cmd.Stderr = &stderrBuf
+
+	stdoutPipe, err := cmd.StdoutPipe()
+	if err != nil {
+		return fmt.Errorf("create stdout pipe: %w", err)
+	}
+
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("start pg_basebackup: %w", err)
+	}
+
+	// Phase 1: Stream compressed data via io.Pipe directly to the API.
+	pipeReader, pipeWriter := io.Pipe()
+	defer func() { _ = pipeReader.Close() }()
+
+	go backuper.compressAndStream(pipeWriter, stdoutPipe)
+
+	uploadCtx, timeoutCancel := context.WithTimeout(ctx, uploadTimeout)
+	defer timeoutCancel()
+
+	idleCtx, idleCancel := context.WithCancelCause(uploadCtx)
+	defer idleCancel(nil)
+
+	idleReader := api.NewIdleTimeoutReader(pipeReader, uploadIdleTimeout, idleCancel)
+	defer idleReader.Stop()
+
+	uploadResp, uploadErr := backuper.apiClient.UploadBasebackup(idleCtx, idleReader)
+
+	if uploadErr != nil && cmd.Process != nil {
+		_ = cmd.Process.Kill()
+	}
+
+	cmdErr := cmd.Wait()
+
+	if uploadErr != nil {
+		if cause := context.Cause(idleCtx); cause != nil {
+			uploadErr = cause
+		}
+
+		stderrStr := stderrBuf.String()
+		if stderrStr != "" {
+			return fmt.Errorf("upload basebackup: %w (pg_basebackup stderr: %s)", uploadErr, stderrStr)
+		}
+
+		return fmt.Errorf("upload basebackup: %w", uploadErr)
+	}
+
+	if cmdErr != nil {
+		errMsg := fmt.Sprintf("pg_basebackup exited with error: %v (stderr: %s)", cmdErr, stderrBuf.String())
+		_ = backuper.apiClient.FinalizeBasebackupWithError(ctx, uploadResp.BackupID, errMsg)
+
+		return fmt.Errorf("%s", errMsg)
+	}
+
+	// Phase 2: Parse stderr for WAL segments and finalize the backup.
+	stderrStr := stderrBuf.String()
+	backuper.log.Debug("pg_basebackup stderr", "stderr", stderrStr)
+
+	startSegment, stopSegment, err := ParseBasebackupStderr(stderrStr)
+	if err != nil {
+		errMsg := fmt.Sprintf("parse pg_basebackup stderr: %v", err)
+		_ = backuper.apiClient.FinalizeBasebackupWithError(ctx, uploadResp.BackupID, errMsg)
+
+		return fmt.Errorf("parse pg_basebackup stderr: %w", err)
+	}
+
+	backuper.log.Info("Basebackup WAL segments parsed",
+		"startSegment", startSegment,
+		"stopSegment", stopSegment,
+		"backupId", uploadResp.BackupID,
+	)
+
+	if err := backuper.apiClient.FinalizeBasebackup(ctx, uploadResp.BackupID, startSegment, stopSegment); err != nil {
+		return fmt.Errorf("finalize basebackup: %w", err)
+	}
+
+	return nil
+}
+
+func (backuper *FullBackuper) compressAndStream(pipeWriter *io.PipeWriter, reader io.Reader) {
+	encoder, err := zstd.NewWriter(pipeWriter,
+		zstd.WithEncoderLevel(zstd.EncoderLevelFromZstd(5)),
+		zstd.WithEncoderCRC(true),
+	)
+	if err != nil {
+		_ = pipeWriter.CloseWithError(fmt.Errorf("create zstd encoder: %w", err))
+		return
+	}
+
+	if _, err := io.Copy(encoder, reader); err != nil {
+		_ = encoder.Close()
+		_ = pipeWriter.CloseWithError(fmt.Errorf("compress: %w", err))
+		return
+	}
+
+	if err := encoder.Close(); err != nil {
+		_ = pipeWriter.CloseWithError(fmt.Errorf("close encoder: %w", err))
+		return
+	}
+
+	_ = pipeWriter.Close()
+}
+
+func (backuper *FullBackuper) reportError(ctx context.Context, errMsg string) {
+	if err := backuper.apiClient.ReportBackupError(ctx, errMsg); err != nil {
+		backuper.log.Error("Failed to report error to server", "error", err)
+	}
+}
+
+func (backuper *FullBackuper) defaultCmdBuilder(ctx context.Context) *exec.Cmd {
+	switch backuper.cfg.PgType {
+	case "docker":
+		return backuper.buildDockerCmd(ctx)
+	default:
+		return backuper.buildHostCmd(ctx)
+	}
+}
+
+func (backuper *FullBackuper) buildHostCmd(ctx context.Context) *exec.Cmd {
+	binary := "pg_basebackup"
+	if backuper.cfg.PgHostBinDir != "" {
+		binary = filepath.Join(backuper.cfg.PgHostBinDir, "pg_basebackup")
+	}
+
+	cmd := exec.CommandContext(ctx, binary,
+		"-Ft", "-D", "-", "-X", "fetch", "--verbose", "--checkpoint=fast",
+		"-h", backuper.cfg.PgHost,
+		"-p", fmt.Sprintf("%d", backuper.cfg.PgPort),
+		"-U", backuper.cfg.PgUser,
+	)
+
+	cmd.Env = append(os.Environ(), "PGPASSWORD="+backuper.cfg.PgPassword)
+
+	return cmd
+}
+
+func (backuper *FullBackuper) buildDockerCmd(ctx context.Context) *exec.Cmd {
+	cmd := exec.CommandContext(ctx, "docker", "exec",
+		"-e", "PGPASSWORD="+backuper.cfg.PgPassword,
+		"-i", backuper.cfg.PgDockerContainerName,
+		"pg_basebackup",
+		"-Ft", "-D", "-", "-X", "fetch", "--verbose", "--checkpoint=fast",
+		"-h", "localhost",
+		"-p", "5432",
+		"-U", backuper.cfg.PgUser,
+	)
+
+	return cmd
+}

agent/internal/features/full_backup/backuper_test.go

@@ -0,0 +1,735 @@
+package full_backup
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"databasus-agent/internal/config"
+	"databasus-agent/internal/features/api"
+	"databasus-agent/internal/logger"
+)
+
+const (
+	testChainValidPath     = "/api/v1/backups/postgres/wal/is-wal-chain-valid-since-last-full-backup"
+	testNextBackupTimePath = "/api/v1/backups/postgres/wal/next-full-backup-time"
+	testFullStartPath      = "/api/v1/backups/postgres/wal/upload/full-start"
+	testFullCompletePath   = "/api/v1/backups/postgres/wal/upload/full-complete"
+	testReportErrorPath    = "/api/v1/backups/postgres/wal/error"
+
+	testBackupID = "test-backup-id-1234"
+)
+
+func Test_RunFullBackup_WhenChainBroken_BasebackupTriggered(t *testing.T) {
+	var mu sync.Mutex
+	var uploadReceived bool
+	var uploadHeaders http.Header
+	var finalizeReceived bool
+	var finalizeBody map[string]any
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid:               false,
+				Error:                 "wal_chain_broken",
+				LastContiguousSegment: "000000010000000100000011",
+			})
+		case testFullStartPath:
+			mu.Lock()
+			uploadReceived = true
+			uploadHeaders = r.Header.Clone()
+			mu.Unlock()
+
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			mu.Lock()
+			finalizeReceived = true
+			_ = json.NewDecoder(r.Body).Decode(&finalizeBody)
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "test-backup-data", validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return finalizeReceived
+	}, 5*time.Second)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	assert.True(t, uploadReceived)
+	assert.Equal(t, "application/octet-stream", uploadHeaders.Get("Content-Type"))
+	assert.Equal(t, "test-token", uploadHeaders.Get("Authorization"))
+
+	assert.True(t, finalizeReceived)
+	assert.Equal(t, testBackupID, finalizeBody["backupId"])
+	assert.Equal(t, "000000010000000000000002", finalizeBody["startSegment"])
+	assert.Equal(t, "000000010000000000000002", finalizeBody["stopSegment"])
+}
+
+func Test_RunFullBackup_WhenScheduledBackupDue_BasebackupTriggered(t *testing.T) {
+	var mu sync.Mutex
+	var finalizeReceived bool
+
+	pastTime := time.Now().UTC().Add(-1 * time.Hour)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{IsValid: true})
+		case testNextBackupTimePath:
+			writeJSON(w, api.NextFullBackupTimeResponse{NextFullBackupTime: &pastTime})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			mu.Lock()
+			finalizeReceived = true
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "scheduled-backup-data", validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return finalizeReceived
+	}, 5*time.Second)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	assert.True(t, finalizeReceived)
+}
+
+func Test_RunFullBackup_WhenNoFullBackupExists_ImmediateBasebackupTriggered(t *testing.T) {
+	var mu sync.Mutex
+	var finalizeReceived bool
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid: false,
+				Error:   "no_full_backup",
+			})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			mu.Lock()
+			finalizeReceived = true
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "first-backup-data", validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return finalizeReceived
+	}, 5*time.Second)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	assert.True(t, finalizeReceived)
+}
+
+func Test_RunFullBackup_WhenUploadFails_RetriesAfterDelay(t *testing.T) {
+	var mu sync.Mutex
+	var uploadAttempts int
+	var errorReported bool
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid: false,
+				Error:   "no_full_backup",
+			})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+
+			mu.Lock()
+			uploadAttempts++
+			attempt := uploadAttempts
+			mu.Unlock()
+
+			if attempt == 1 {
+				w.WriteHeader(http.StatusInternalServerError)
+				_, _ = w.Write([]byte(`{"error":"storage unavailable"}`))
+				return
+			}
+
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			w.WriteHeader(http.StatusOK)
+		case testReportErrorPath:
+			mu.Lock()
+			errorReported = true
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "retry-backup-data", validStderr())
+
+	origRetryDelay := retryDelay
+	setRetryDelay(100 * time.Millisecond)
+	defer setRetryDelay(origRetryDelay)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return uploadAttempts >= 2
+	}, 10*time.Second)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	assert.GreaterOrEqual(t, uploadAttempts, 2)
+	assert.True(t, errorReported)
+}
+
+func Test_RunFullBackup_WhenAlreadyRunning_SkipsExecution(t *testing.T) {
+	var mu sync.Mutex
+	var uploadCount int
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid: false,
+				Error:   "no_full_backup",
+			})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+
+			mu.Lock()
+			uploadCount++
+			mu.Unlock()
+
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "data", validStderr())
+
+	fb.isRunning.Store(true)
+
+	fb.checkAndRunIfNeeded(t.Context())
+
+	mu.Lock()
+	count := uploadCount
+	mu.Unlock()
+
+	assert.Equal(t, 0, count, "should not trigger backup when already running")
+}
+
+func Test_RunFullBackup_WhenContextCancelled_StopsCleanly(t *testing.T) {
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid: false,
+				Error:   "no_full_backup",
+			})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+			w.WriteHeader(http.StatusInternalServerError)
+		case testFullCompletePath:
+			w.WriteHeader(http.StatusOK)
+		case testReportErrorPath:
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "data", validStderr())
+
+	origRetryDelay := retryDelay
+	setRetryDelay(5 * time.Second)
+	defer setRetryDelay(origRetryDelay)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 500*time.Millisecond)
+	defer cancel()
+
+	done := make(chan struct{})
+	go func() {
+		fb.Run(ctx)
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Run should have stopped after context cancellation")
+	}
+}
+
+func Test_RunFullBackup_WhenChainValidAndNotScheduled_NoBasebackupTriggered(t *testing.T) {
+	var uploadReceived atomic.Bool
+
+	futureTime := time.Now().UTC().Add(24 * time.Hour)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{IsValid: true})
+		case testNextBackupTimePath:
+			writeJSON(w, api.NextFullBackupTimeResponse{NextFullBackupTime: &futureTime})
+		case testFullStartPath:
+			uploadReceived.Store(true)
+
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "data", validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 2*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	assert.False(t, uploadReceived.Load(), "should not trigger backup when chain valid and not scheduled")
+}
+
+func Test_RunFullBackup_WhenStderrParsingFails_FinalizesWithErrorAndRetries(t *testing.T) {
+	var mu sync.Mutex
+	var errorReported bool
+	var finalizeWithErrorReceived bool
+	var finalizeBody map[string]any
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid: false,
+				Error:   "no_full_backup",
+			})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			mu.Lock()
+			finalizeWithErrorReceived = true
+			_ = json.NewDecoder(r.Body).Decode(&finalizeBody)
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		case testReportErrorPath:
+			mu.Lock()
+			errorReported = true
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "data", "pg_basebackup: unexpected output with no LSN info")
+
+	origRetryDelay := retryDelay
+	setRetryDelay(100 * time.Millisecond)
+	defer setRetryDelay(origRetryDelay)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 2*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return errorReported
+	}, 2*time.Second)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	assert.True(t, errorReported)
+	assert.True(t, finalizeWithErrorReceived, "should finalize with error when stderr parsing fails")
+	assert.Equal(t, testBackupID, finalizeBody["backupId"])
+	assert.NotNil(t, finalizeBody["error"], "finalize should include error message")
+}
+
+func Test_RunFullBackup_WhenNextBackupTimeNull_BasebackupTriggered(t *testing.T) {
+	var mu sync.Mutex
+	var finalizeReceived bool
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{IsValid: true})
+		case testNextBackupTimePath:
+			writeJSON(w, api.NextFullBackupTimeResponse{NextFullBackupTime: nil})
+		case testFullStartPath:
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			mu.Lock()
+			finalizeReceived = true
+			mu.Unlock()
+
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "first-run-data", validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return finalizeReceived
+	}, 5*time.Second)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	assert.True(t, finalizeReceived)
+}
+
+func Test_RunFullBackup_WhenChainValidityReturns401_NoBasebackupTriggered(t *testing.T) {
+	var uploadReceived atomic.Bool
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			w.WriteHeader(http.StatusUnauthorized)
+			_, _ = w.Write([]byte(`{"error":"invalid token"}`))
+		case testFullStartPath:
+			uploadReceived.Store(true)
+
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, "data", validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 2*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	assert.False(t, uploadReceived.Load(), "should not trigger backup when API returns 401")
+}
+
+func Test_RunFullBackup_WhenUploadSucceeds_BodyIsZstdCompressed(t *testing.T) {
+	var mu sync.Mutex
+	var receivedBody []byte
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testChainValidPath:
+			writeJSON(w, api.WalChainValidityResponse{
+				IsValid: false,
+				Error:   "no_full_backup",
+			})
+		case testFullStartPath:
+			body, _ := io.ReadAll(r.Body)
+
+			mu.Lock()
+			receivedBody = body
+			mu.Unlock()
+
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		case testFullCompletePath:
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	originalContent := "test-backup-content-for-compression-check"
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = mockCmdBuilder(t, originalContent, validStderr())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+
+	go fb.Run(ctx)
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return len(receivedBody) > 0
+	}, 5*time.Second)
+	cancel()
+
+	mu.Lock()
+	body := receivedBody
+	mu.Unlock()
+
+	decoder, err := zstd.NewReader(nil)
+	require.NoError(t, err)
+	defer decoder.Close()
+
+	decompressed, err := decoder.DecodeAll(body, nil)
+	require.NoError(t, err)
+	assert.Equal(t, originalContent, string(decompressed))
+}
+
+func Test_RunFullBackup_WhenUploadStalls_FailsWithIdleTimeout(t *testing.T) {
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testFullStartPath:
+			// Server reads body normally — it will block until connection is closed
+			_, _ = io.ReadAll(r.Body)
+			writeJSON(w, map[string]string{"backupId": testBackupID})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	fb := newTestFullBackuper(server.URL)
+	fb.cmdBuilder = stallingCmdBuilder(t)
+
+	origIdleTimeout := uploadIdleTimeout
+	uploadIdleTimeout = 200 * time.Millisecond
+	defer func() { uploadIdleTimeout = origIdleTimeout }()
+
+	ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+	defer cancel()
+
+	err := fb.executeAndUploadBasebackup(ctx)
+
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "idle timeout", "error should mention idle timeout")
+}
+
+func stallingCmdBuilder(t *testing.T) CmdBuilder {
+	t.Helper()
+
+	return func(ctx context.Context) *exec.Cmd {
+		cmd := exec.CommandContext(ctx, os.Args[0],
+			"-test.run=TestHelperProcessStalling",
+			"--",
+		)
+
+		cmd.Env = append(os.Environ(), "GO_TEST_HELPER_PROCESS_STALLING=1")
+
+		return cmd
+	}
+}
+
+func TestHelperProcessStalling(t *testing.T) {
+	if os.Getenv("GO_TEST_HELPER_PROCESS_STALLING") != "1" {
+		return
+	}
+
+	// Write enough data to flush through the zstd encoder's internal buffer (~128KB blocks).
+	// Without enough data, zstd buffers everything and the pipe never receives bytes.
+	data := make([]byte, 256*1024)
+	for i := range data {
+		data[i] = byte(i)
+	}
+	_, _ = os.Stdout.Write(data)
+
+	// Stall with stdout open — the compress goroutine blocks on its next read.
+	// The parent process will kill us when the context is cancelled.
+	time.Sleep(time.Hour)
+	os.Exit(0)
+}
+
+func newTestServer(t *testing.T, handler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+
+	server := httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+
+	return server
+}
+
+func newTestFullBackuper(serverURL string) *FullBackuper {
+	cfg := &config.Config{
+		DatabasusHost: serverURL,
+		DbID:          "test-db-id",
+		Token:         "test-token",
+		PgHost:        "localhost",
+		PgPort:        5432,
+		PgUser:        "postgres",
+		PgPassword:    "password",
+		PgType:        "host",
+	}
+
+	apiClient := api.NewClient(serverURL, cfg.Token, logger.GetLogger())
+
+	return NewFullBackuper(cfg, apiClient, logger.GetLogger())
+}
+
+func mockCmdBuilder(t *testing.T, stdoutContent, stderrContent string) CmdBuilder {
+	t.Helper()
+
+	return func(ctx context.Context) *exec.Cmd {
+		cmd := exec.CommandContext(ctx, os.Args[0],
+			"-test.run=TestHelperProcess",
+			"--",
+			stdoutContent,
+			stderrContent,
+		)
+
+		cmd.Env = append(os.Environ(), "GO_TEST_HELPER_PROCESS=1")
+
+		return cmd
+	}
+}
+
+func TestHelperProcess(t *testing.T) {
+	if os.Getenv("GO_TEST_HELPER_PROCESS") != "1" {
+		return
+	}
+
+	args := os.Args
+	for i, arg := range args {
+		if arg == "--" {
+			args = args[i+1:]
+			break
+		}
+	}
+
+	if len(args) >= 1 {
+		_, _ = fmt.Fprint(os.Stdout, args[0])
+	}
+
+	if len(args) >= 2 {
+		_, _ = fmt.Fprint(os.Stderr, args[1])
+	}
+
+	os.Exit(0)
+}
+
+func validStderr() string {
+	return `pg_basebackup: initiating base backup, waiting for checkpoint to complete
+pg_basebackup: checkpoint completed
+pg_basebackup: write-ahead log start point: 0/2000028 on timeline 1
+pg_basebackup: starting background WAL receiver
+pg_basebackup: write-ahead log end point: 0/2000100
+pg_basebackup: waiting for background process to finish streaming ...
+pg_basebackup: syncing data to disk ...
+pg_basebackup: base backup completed`
+}
+
+func writeJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(v); err != nil {
+		w.WriteHeader(http.StatusInternalServerError)
+	}
+}
+
+func waitForCondition(t *testing.T, condition func() bool, timeout time.Duration) {
+	t.Helper()
+
+	deadline := time.Now().Add(timeout)
+
+	for time.Now().Before(deadline) {
+		if condition() {
+			return
+		}
+
+		time.Sleep(50 * time.Millisecond)
+	}
+
+	t.Fatalf("condition not met within %v", timeout)
+}
+
+func setRetryDelay(d time.Duration) {
+	retryDelayOverride = &d
+}
+
+func init() {
+	retryDelayOverride = nil
+}

agent/internal/features/full_backup/stderr_parser.go

@@ -0,0 +1,75 @@
+package full_backup
+
+import (
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+const defaultWalSegmentSize uint32 = 16 * 1024 * 1024 // 16 MB
+
+var (
+	startLSNRegex = regexp.MustCompile(`write-ahead log start point: ([0-9A-Fa-f]+/[0-9A-Fa-f]+)`)
+	stopLSNRegex  = regexp.MustCompile(`write-ahead log end point: ([0-9A-Fa-f]+/[0-9A-Fa-f]+)`)
+)
+
+func ParseBasebackupStderr(stderr string) (startSegment, stopSegment string, err error) {
+	startMatch := startLSNRegex.FindStringSubmatch(stderr)
+	if len(startMatch) < 2 {
+		return "", "", fmt.Errorf("failed to parse start WAL location from pg_basebackup stderr")
+	}
+
+	stopMatch := stopLSNRegex.FindStringSubmatch(stderr)
+	if len(stopMatch) < 2 {
+		return "", "", fmt.Errorf("failed to parse stop WAL location from pg_basebackup stderr")
+	}
+
+	startSegment, err = LSNToSegmentName(startMatch[1], 1, defaultWalSegmentSize)
+	if err != nil {
+		return "", "", fmt.Errorf("failed to convert start LSN to segment name: %w", err)
+	}
+
+	stopSegment, err = LSNToSegmentName(stopMatch[1], 1, defaultWalSegmentSize)
+	if err != nil {
+		return "", "", fmt.Errorf("failed to convert stop LSN to segment name: %w", err)
+	}
+
+	return startSegment, stopSegment, nil
+}
+
+func LSNToSegmentName(lsn string, timelineID, walSegmentSize uint32) (string, error) {
+	high, low, err := parseLSN(lsn)
+	if err != nil {
+		return "", err
+	}
+
+	segmentsPerXLogID := uint32(0x100000000 / uint64(walSegmentSize))
+	logID := high
+	segmentOffset := low / walSegmentSize
+
+	if segmentOffset >= segmentsPerXLogID {
+		return "", fmt.Errorf("segment offset %d exceeds segments per XLogId %d", segmentOffset, segmentsPerXLogID)
+	}
+
+	return fmt.Sprintf("%08X%08X%08X", timelineID, logID, segmentOffset), nil
+}
+
+func parseLSN(lsn string) (high, low uint32, err error) {
+	parts := strings.SplitN(lsn, "/", 2)
+	if len(parts) != 2 {
+		return 0, 0, fmt.Errorf("invalid LSN format: %q (expected X/Y)", lsn)
+	}
+
+	highVal, err := strconv.ParseUint(parts[0], 16, 32)
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid LSN high part %q: %w", parts[0], err)
+	}
+
+	lowVal, err := strconv.ParseUint(parts[1], 16, 32)
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid LSN low part %q: %w", parts[1], err)
+	}
+
+	return uint32(highVal), uint32(lowVal), nil
+}

agent/internal/features/full_backup/stderr_parser_test.go

@@ -0,0 +1,157 @@
+package full_backup
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_ParseBasebackupStderr_WithPG17FetchOutput_ExtractsCorrectSegments(t *testing.T) {
+	stderr := `pg_basebackup: initiating base backup, waiting for checkpoint to complete
+pg_basebackup: checkpoint completed
+pg_basebackup: write-ahead log start point: 0/2000028 on timeline 1
+pg_basebackup: starting background WAL receiver
+pg_basebackup: write-ahead log end point: 0/2000100
+pg_basebackup: waiting for background process to finish streaming ...
+pg_basebackup: syncing data to disk ...
+pg_basebackup: renaming backup_manifest.tmp to backup_manifest
+pg_basebackup: base backup completed`
+
+	startSeg, stopSeg, err := ParseBasebackupStderr(stderr)
+
+	require.NoError(t, err)
+	assert.Equal(t, "000000010000000000000002", startSeg)
+	assert.Equal(t, "000000010000000000000002", stopSeg)
+}
+
+func Test_ParseBasebackupStderr_WithHighLSNValues_ExtractsCorrectSegments(t *testing.T) {
+	stderr := `pg_basebackup: write-ahead log start point: 1/AB000028 on timeline 1
+pg_basebackup: write-ahead log end point: 1/AC000000`
+
+	startSeg, stopSeg, err := ParseBasebackupStderr(stderr)
+
+	require.NoError(t, err)
+	assert.Equal(t, "0000000100000001000000AB", startSeg)
+	assert.Equal(t, "0000000100000001000000AC", stopSeg)
+}
+
+func Test_ParseBasebackupStderr_WithHighLogID_ExtractsCorrectSegments(t *testing.T) {
+	stderr := `pg_basebackup: write-ahead log start point: A/FF000028 on timeline 1
+pg_basebackup: write-ahead log end point: B/1000000`
+
+	startSeg, stopSeg, err := ParseBasebackupStderr(stderr)
+
+	require.NoError(t, err)
+	assert.Equal(t, "000000010000000A000000FF", startSeg)
+	assert.Equal(t, "000000010000000B00000001", stopSeg)
+}
+
+func Test_ParseBasebackupStderr_WhenStartLSNMissing_ReturnsError(t *testing.T) {
+	stderr := `pg_basebackup: write-ahead log end point: 0/2000100
+pg_basebackup: base backup completed`
+
+	_, _, err := ParseBasebackupStderr(stderr)
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to parse start WAL location")
+}
+
+func Test_ParseBasebackupStderr_WhenStopLSNMissing_ReturnsError(t *testing.T) {
+	stderr := `pg_basebackup: write-ahead log start point: 0/2000028 on timeline 1
+pg_basebackup: base backup completed`
+
+	_, _, err := ParseBasebackupStderr(stderr)
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to parse stop WAL location")
+}
+
+func Test_ParseBasebackupStderr_WhenEmptyStderr_ReturnsError(t *testing.T) {
+	_, _, err := ParseBasebackupStderr("")
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to parse start WAL location")
+}
+
+func Test_LSNToSegmentName_WithBoundaryValues_ConvertsCorrectly(t *testing.T) {
+	tests := []struct {
+		name     string
+		lsn      string
+		timeline uint32
+		segSize  uint32
+		expected string
+	}{
+		{
+			name:     "first segment",
+			lsn:      "0/1000000",
+			timeline: 1,
+			segSize:  16 * 1024 * 1024,
+			expected: "000000010000000000000001",
+		},
+		{
+			name:     "segment at boundary FF",
+			lsn:      "0/FF000000",
+			timeline: 1,
+			segSize:  16 * 1024 * 1024,
+			expected: "0000000100000000000000FF",
+		},
+		{
+			name:     "segment in second log file",
+			lsn:      "1/0",
+			timeline: 1,
+			segSize:  16 * 1024 * 1024,
+			expected: "000000010000000100000000",
+		},
+		{
+			name:     "segment with offset within 16MB",
+			lsn:      "0/200ABCD",
+			timeline: 1,
+			segSize:  16 * 1024 * 1024,
+			expected: "000000010000000000000002",
+		},
+		{
+			name:     "zero LSN",
+			lsn:      "0/0",
+			timeline: 1,
+			segSize:  16 * 1024 * 1024,
+			expected: "000000010000000000000000",
+		},
+		{
+			name:     "high timeline ID",
+			lsn:      "0/1000000",
+			timeline: 2,
+			segSize:  16 * 1024 * 1024,
+			expected: "000000020000000000000001",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := LSNToSegmentName(tt.lsn, tt.timeline, tt.segSize)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func Test_LSNToSegmentName_WithInvalidLSN_ReturnsError(t *testing.T) {
+	tests := []struct {
+		name string
+		lsn  string
+	}{
+		{name: "no slash", lsn: "012345"},
+		{name: "empty string", lsn: ""},
+		{name: "invalid hex high", lsn: "GG/0"},
+		{name: "invalid hex low", lsn: "0/ZZ"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := LSNToSegmentName(tt.lsn, 1, 16*1024*1024)
+
+			require.Error(t, err)
+		})
+	}
+}

agent/internal/features/restore/restorer.go

@@ -0,0 +1,444 @@
+package restore
+
+import (
+	"archive/tar"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+
+	"databasus-agent/internal/features/api"
+)
+
+const (
+	walRestoreDir            = "databasus-wal-restore"
+	maxRetryAttempts         = 3
+	retryBaseDelay           = 1 * time.Second
+	recoverySignalFile       = "recovery.signal"
+	autoConfFile             = "postgresql.auto.conf"
+	dockerContainerPgDataDir = "/var/lib/postgresql/data"
+)
+
+var retryDelayOverride *time.Duration
+
+type Restorer struct {
+	apiClient       *api.Client
+	log             *slog.Logger
+	targetPgDataDir string
+	backupID        string
+	targetTime      string
+	pgType          string
+}
+
+func NewRestorer(
+	apiClient *api.Client,
+	log *slog.Logger,
+	targetPgDataDir string,
+	backupID string,
+	targetTime string,
+	pgType string,
+) *Restorer {
+	return &Restorer{
+		apiClient,
+		log,
+		targetPgDataDir,
+		backupID,
+		targetTime,
+		pgType,
+	}
+}
+
+func (r *Restorer) Run(ctx context.Context) error {
+	var parsedTargetTime *time.Time
+
+	if r.targetTime != "" {
+		parsed, err := time.Parse(time.RFC3339, r.targetTime)
+		if err != nil {
+			return fmt.Errorf("invalid --target-time format (expected RFC3339, e.g. 2026-02-28T14:30:00Z): %w", err)
+		}
+
+		parsedTargetTime = &parsed
+	}
+
+	if err := r.validateTargetPgDataDir(); err != nil {
+		return err
+	}
+
+	plan, err := r.getRestorePlanFromServer(ctx)
+	if err != nil {
+		return err
+	}
+
+	r.logRestorePlan(plan, parsedTargetTime)
+
+	r.log.Info("Downloading and extracting basebackup...")
+	if err := r.downloadAndExtractBasebackup(ctx, plan.FullBackup.BackupID); err != nil {
+		return fmt.Errorf("basebackup download failed: %w", err)
+	}
+	r.log.Info("Basebackup extracted successfully")
+
+	if err := r.downloadAllWalSegments(ctx, plan.WalSegments); err != nil {
+		return err
+	}
+
+	if err := r.configurePostgresRecovery(parsedTargetTime); err != nil {
+		return fmt.Errorf("failed to configure recovery: %w", err)
+	}
+
+	if err := os.Chmod(r.targetPgDataDir, 0o700); err != nil {
+		return fmt.Errorf("set PGDATA permissions: %w", err)
+	}
+
+	r.printCompletionMessage()
+
+	return nil
+}
+
+func (r *Restorer) validateTargetPgDataDir() error {
+	info, err := os.Stat(r.targetPgDataDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("target pgdata directory does not exist: %s", r.targetPgDataDir)
+		}
+
+		return fmt.Errorf("cannot access target pgdata directory: %w", err)
+	}
+
+	if !info.IsDir() {
+		return fmt.Errorf("target pgdata path is not a directory: %s", r.targetPgDataDir)
+	}
+
+	entries, err := os.ReadDir(r.targetPgDataDir)
+	if err != nil {
+		return fmt.Errorf("cannot read target pgdata directory: %w", err)
+	}
+
+	if len(entries) > 0 {
+		return fmt.Errorf("target pgdata directory is not empty: %s", r.targetPgDataDir)
+	}
+
+	return nil
+}
+
+func (r *Restorer) getRestorePlanFromServer(ctx context.Context) (*api.GetRestorePlanResponse, error) {
+	plan, planErr, err := r.apiClient.GetRestorePlan(ctx, r.backupID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch restore plan: %w", err)
+	}
+
+	if planErr != nil {
+		if planErr.LastContiguousSegment != "" {
+			return nil, fmt.Errorf("restore plan error: %s (last contiguous segment: %s)",
+				planErr.Message, planErr.LastContiguousSegment)
+		}
+
+		return nil, fmt.Errorf("restore plan error: %s", planErr.Message)
+	}
+
+	return plan, nil
+}
+
+func (r *Restorer) logRestorePlan(plan *api.GetRestorePlanResponse, parsedTargetTime *time.Time) {
+	recoveryTarget := "full recovery (all available WAL)"
+	if parsedTargetTime != nil {
+		recoveryTarget = parsedTargetTime.Format(time.RFC3339)
+	}
+
+	r.log.Info("Restore plan",
+		"fullBackupID", plan.FullBackup.BackupID,
+		"fullBackupCreatedAt", plan.FullBackup.CreatedAt.Format(time.RFC3339),
+		"pgVersion", plan.FullBackup.PgVersion,
+		"walSegmentCount", len(plan.WalSegments),
+		"totalDownloadSize", formatSizeBytes(plan.TotalSizeBytes),
+		"latestAvailableSegment", plan.LatestAvailableSegment,
+		"recoveryTarget", recoveryTarget,
+	)
+}
+
+func (r *Restorer) downloadAndExtractBasebackup(ctx context.Context, backupID string) error {
+	body, err := r.apiClient.DownloadBackupFile(ctx, backupID)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = body.Close() }()
+
+	zstdReader, err := zstd.NewReader(body)
+	if err != nil {
+		return fmt.Errorf("create zstd decompressor: %w", err)
+	}
+	defer zstdReader.Close()
+
+	tarReader := tar.NewReader(zstdReader)
+
+	return r.extractTarArchive(tarReader)
+}
+
+func (r *Restorer) extractTarArchive(tarReader *tar.Reader) error {
+	for {
+		header, err := tarReader.Next()
+		if errors.Is(err, io.EOF) {
+			return nil
+		}
+
+		if err != nil {
+			return fmt.Errorf("read tar entry: %w", err)
+		}
+
+		targetPath := filepath.Join(r.targetPgDataDir, header.Name)
+
+		relativePath, err := filepath.Rel(r.targetPgDataDir, targetPath)
+		if err != nil || strings.HasPrefix(relativePath, "..") {
+			return fmt.Errorf("tar entry attempts path traversal: %s", header.Name)
+		}
+
+		switch header.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(targetPath, os.FileMode(header.Mode)); err != nil {
+				return fmt.Errorf("create directory %s: %w", header.Name, err)
+			}
+
+		case tar.TypeReg:
+			parentDir := filepath.Dir(targetPath)
+			if err := os.MkdirAll(parentDir, 0o755); err != nil {
+				return fmt.Errorf("create parent directory for %s: %w", header.Name, err)
+			}
+
+			file, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, os.FileMode(header.Mode))
+			if err != nil {
+				return fmt.Errorf("create file %s: %w", header.Name, err)
+			}
+
+			if _, err := io.Copy(file, tarReader); err != nil {
+				_ = file.Close()
+				return fmt.Errorf("write file %s: %w", header.Name, err)
+			}
+
+			_ = file.Close()
+
+		case tar.TypeSymlink:
+			if err := os.Symlink(header.Linkname, targetPath); err != nil {
+				return fmt.Errorf("create symlink %s: %w", header.Name, err)
+			}
+
+		case tar.TypeLink:
+			linkTarget := filepath.Join(r.targetPgDataDir, header.Linkname)
+			if err := os.Link(linkTarget, targetPath); err != nil {
+				return fmt.Errorf("create hard link %s: %w", header.Name, err)
+			}
+
+		default:
+			r.log.Warn("Skipping unsupported tar entry type",
+				"name", header.Name,
+				"type", header.Typeflag,
+			)
+		}
+	}
+}
+
+func (r *Restorer) downloadAllWalSegments(ctx context.Context, segments []api.RestorePlanWalSegment) error {
+	walRestorePath := filepath.Join(r.targetPgDataDir, walRestoreDir)
+	if err := os.MkdirAll(walRestorePath, 0o755); err != nil {
+		return fmt.Errorf("create WAL restore directory: %w", err)
+	}
+
+	for segmentIndex, segment := range segments {
+		if err := r.downloadWalSegmentWithRetry(ctx, segment, segmentIndex, len(segments)); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (r *Restorer) downloadWalSegmentWithRetry(
+	ctx context.Context,
+	segment api.RestorePlanWalSegment,
+	segmentIndex int,
+	segmentsTotal int,
+) error {
+	r.log.Info("Downloading WAL segment",
+		"segment", segment.SegmentName,
+		"progress", fmt.Sprintf("%d/%d", segmentIndex+1, segmentsTotal),
+	)
+
+	var lastErr error
+
+	for attempt := range maxRetryAttempts {
+		if err := r.downloadWalSegment(ctx, segment); err != nil {
+			lastErr = err
+
+			delay := r.getRetryDelay(attempt)
+			r.log.Warn("WAL segment download failed, retrying",
+				"segment", segment.SegmentName,
+				"attempt", attempt+1,
+				"maxAttempts", maxRetryAttempts,
+				"retryDelay", delay,
+				"error", err,
+			)
+
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(delay):
+				continue
+			}
+		}
+
+		return nil
+	}
+
+	return fmt.Errorf("failed to download WAL segment %s after %d attempts: %w",
+		segment.SegmentName, maxRetryAttempts, lastErr)
+}
+
+func (r *Restorer) downloadWalSegment(ctx context.Context, segment api.RestorePlanWalSegment) error {
+	body, err := r.apiClient.DownloadBackupFile(ctx, segment.BackupID)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = body.Close() }()
+
+	zstdReader, err := zstd.NewReader(body)
+	if err != nil {
+		return fmt.Errorf("create zstd decompressor: %w", err)
+	}
+	defer zstdReader.Close()
+
+	segmentPath := filepath.Join(r.targetPgDataDir, walRestoreDir, segment.SegmentName)
+
+	file, err := os.Create(segmentPath)
+	if err != nil {
+		return fmt.Errorf("create WAL segment file: %w", err)
+	}
+	defer func() { _ = file.Close() }()
+
+	if _, err := io.Copy(file, zstdReader); err != nil {
+		return fmt.Errorf("write WAL segment: %w", err)
+	}
+
+	return nil
+}
+
+func (r *Restorer) configurePostgresRecovery(parsedTargetTime *time.Time) error {
+	recoverySignalPath := filepath.Join(r.targetPgDataDir, recoverySignalFile)
+	if err := os.WriteFile(recoverySignalPath, []byte{}, 0o644); err != nil {
+		return fmt.Errorf("create recovery.signal: %w", err)
+	}
+
+	walRestoreAbsPath, err := r.resolveWalRestorePath()
+	if err != nil {
+		return err
+	}
+
+	autoConfPath := filepath.Join(r.targetPgDataDir, autoConfFile)
+
+	autoConfFile, err := os.OpenFile(autoConfPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		return fmt.Errorf("open postgresql.auto.conf: %w", err)
+	}
+	defer func() { _ = autoConfFile.Close() }()
+
+	var configLines strings.Builder
+	configLines.WriteString("\n# Added by databasus-agent restore\n")
+	fmt.Fprintf(&configLines, "restore_command = 'cp %s/%%f %%p'\n", walRestoreAbsPath)
+	fmt.Fprintf(&configLines, "recovery_end_command = 'rm -rf %s'\n", walRestoreAbsPath)
+	configLines.WriteString("recovery_target_action = 'promote'\n")
+
+	if parsedTargetTime != nil {
+		fmt.Fprintf(&configLines, "recovery_target_time = '%s'\n", parsedTargetTime.Format(time.RFC3339))
+	}
+
+	if _, err := autoConfFile.WriteString(configLines.String()); err != nil {
+		return fmt.Errorf("write to postgresql.auto.conf: %w", err)
+	}
+
+	return nil
+}
+
+func (r *Restorer) printCompletionMessage() {
+	absPgDataDir, _ := filepath.Abs(r.targetPgDataDir)
+	isDocker := r.pgType == "docker"
+
+	fmt.Printf("\nRestore complete. PGDATA directory is ready at %s.\n", absPgDataDir)
+
+	fmt.Print(`
+What happens when you start PostgreSQL:
+  1. PostgreSQL detects recovery.signal and enters recovery mode
+  2. It replays WAL from the basebackup's consistency point
+  3. It executes restore_command to fetch WAL segments from databasus-wal-restore/
+  4. WAL replay continues until target_time (if PITR) or end of available WAL
+  5. recovery_end_command automatically removes databasus-wal-restore/
+  6. PostgreSQL promotes to primary and removes recovery.signal
+  7. Normal operations resume
+`)
+
+	if isDocker {
+		fmt.Printf(`
+Start PostgreSQL by launching a container with the restored data mounted:
+  docker run -d -v %s:%s postgres:<VERSION>
+
+Or if you have an existing container:
+  docker start <CONTAINER_NAME>
+
+Ensure %s is mounted as the container's pgdata volume at %s.
+`, absPgDataDir, dockerContainerPgDataDir, absPgDataDir, dockerContainerPgDataDir)
+	} else {
+		fmt.Printf(`
+Start PostgreSQL:
+  pg_ctl -D %s start
+
+Note: If you move the PGDATA directory before starting PostgreSQL,
+update restore_command and recovery_end_command paths in
+postgresql.auto.conf accordingly.
+`, absPgDataDir)
+	}
+}
+
+func (r *Restorer) resolveWalRestorePath() (string, error) {
+	if r.pgType == "docker" {
+		return dockerContainerPgDataDir + "/" + walRestoreDir, nil
+	}
+
+	absPgDataDir, err := filepath.Abs(r.targetPgDataDir)
+	if err != nil {
+		return "", fmt.Errorf("resolve absolute path: %w", err)
+	}
+
+	absPgDataDir = filepath.ToSlash(absPgDataDir)
+
+	return absPgDataDir + "/" + walRestoreDir, nil
+}
+
+func (r *Restorer) getRetryDelay(attempt int) time.Duration {
+	if retryDelayOverride != nil {
+		return *retryDelayOverride
+	}
+
+	return retryBaseDelay * time.Duration(1<<attempt)
+}
+
+func formatSizeBytes(sizeBytes int64) string {
+	const (
+		kilobyte = 1024
+		megabyte = 1024 * kilobyte
+		gigabyte = 1024 * megabyte
+	)
+
+	switch {
+	case sizeBytes >= gigabyte:
+		return fmt.Sprintf("%.2f GB", float64(sizeBytes)/float64(gigabyte))
+	case sizeBytes >= megabyte:
+		return fmt.Sprintf("%.2f MB", float64(sizeBytes)/float64(megabyte))
+	case sizeBytes >= kilobyte:
+		return fmt.Sprintf("%.2f KB", float64(sizeBytes)/float64(kilobyte))
+	default:
+		return fmt.Sprintf("%d B", sizeBytes)
+	}
+}

agent/internal/features/restore/restorer_test.go

@@ -0,0 +1,711 @@
+package restore
+
+import (
+	"archive/tar"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"databasus-agent/internal/features/api"
+	"databasus-agent/internal/logger"
+)
+
+const (
+	testRestorePlanPath     = "/api/v1/backups/postgres/wal/restore/plan"
+	testRestoreDownloadPath = "/api/v1/backups/postgres/wal/restore/download"
+
+	testFullBackupID = "full-backup-id-1234"
+	testWalSegment1  = "000000010000000100000001"
+	testWalSegment2  = "000000010000000100000002"
+)
+
+func Test_RunRestore_WhenBasebackupAndWalSegmentsAvailable_FilesExtractedAndRecoveryConfigured(t *testing.T) {
+	tarFiles := map[string][]byte{
+		"PG_VERSION":      []byte("16"),
+		"base/1/somefile": []byte("table-data"),
+	}
+	zstdTarData := createZstdTar(t, tarFiles)
+	walData1 := createZstdData(t, []byte("wal-segment-1-data"))
+	walData2 := createZstdData(t, []byte("wal-segment-2-data"))
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:                  testFullBackupID,
+					FullBackupWalStartSegment: testWalSegment1,
+					FullBackupWalStopSegment:  testWalSegment1,
+					PgVersion:                 "16",
+					CreatedAt:                 time.Now().UTC(),
+					SizeBytes:                 1024,
+				},
+				WalSegments: []api.RestorePlanWalSegment{
+					{BackupID: "wal-1", SegmentName: testWalSegment1, SizeBytes: 512},
+					{BackupID: "wal-2", SegmentName: testWalSegment2, SizeBytes: 512},
+				},
+				TotalSizeBytes:         2048,
+				LatestAvailableSegment: testWalSegment2,
+			})
+
+		case testRestoreDownloadPath:
+			backupID := r.URL.Query().Get("backupId")
+			switch backupID {
+			case testFullBackupID:
+				w.Header().Set("Content-Type", "application/octet-stream")
+				_, _ = w.Write(zstdTarData)
+			case "wal-1":
+				w.Header().Set("Content-Type", "application/octet-stream")
+				_, _ = w.Write(walData1)
+			case "wal-2":
+				w.Header().Set("Content-Type", "application/octet-stream")
+				_, _ = w.Write(walData2)
+			default:
+				w.WriteHeader(http.StatusBadRequest)
+			}
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	pgVersionContent, err := os.ReadFile(filepath.Join(targetDir, "PG_VERSION"))
+	require.NoError(t, err)
+	assert.Equal(t, "16", string(pgVersionContent))
+
+	someFileContent, err := os.ReadFile(filepath.Join(targetDir, "base", "1", "somefile"))
+	require.NoError(t, err)
+	assert.Equal(t, "table-data", string(someFileContent))
+
+	walSegment1Content, err := os.ReadFile(filepath.Join(targetDir, walRestoreDir, testWalSegment1))
+	require.NoError(t, err)
+	assert.Equal(t, "wal-segment-1-data", string(walSegment1Content))
+
+	walSegment2Content, err := os.ReadFile(filepath.Join(targetDir, walRestoreDir, testWalSegment2))
+	require.NoError(t, err)
+	assert.Equal(t, "wal-segment-2-data", string(walSegment2Content))
+
+	recoverySignalPath := filepath.Join(targetDir, "recovery.signal")
+	recoverySignalInfo, err := os.Stat(recoverySignalPath)
+	require.NoError(t, err)
+	assert.Equal(t, int64(0), recoverySignalInfo.Size())
+
+	autoConfContent, err := os.ReadFile(filepath.Join(targetDir, "postgresql.auto.conf"))
+	require.NoError(t, err)
+	autoConfStr := string(autoConfContent)
+
+	assert.Contains(t, autoConfStr, "restore_command")
+	assert.Contains(t, autoConfStr, walRestoreDir)
+	assert.Contains(t, autoConfStr, "recovery_target_action = 'promote'")
+	assert.Contains(t, autoConfStr, "recovery_end_command")
+	assert.NotContains(t, autoConfStr, "recovery_target_time")
+}
+
+func Test_RunRestore_WhenTargetTimeProvided_RecoveryTargetTimeWrittenToConfig(t *testing.T) {
+	tarFiles := map[string][]byte{"PG_VERSION": []byte("16")}
+	zstdTarData := createZstdTar(t, tarFiles)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments:            []api.RestorePlanWalSegment{},
+				TotalSizeBytes:         1024,
+				LatestAvailableSegment: "",
+			})
+
+		case testRestoreDownloadPath:
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write(zstdTarData)
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "2026-02-28T14:30:00Z", "")
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	autoConfContent, err := os.ReadFile(filepath.Join(targetDir, "postgresql.auto.conf"))
+	require.NoError(t, err)
+
+	assert.Contains(t, string(autoConfContent), "recovery_target_time = '2026-02-28T14:30:00Z'")
+}
+
+func Test_RunRestore_WhenPgDataDirNotEmpty_ReturnsError(t *testing.T) {
+	targetDir := createTestTargetDir(t)
+
+	err := os.WriteFile(filepath.Join(targetDir, "existing-file"), []byte("data"), 0o644)
+	require.NoError(t, err)
+
+	restorer := newTestRestorer("http://localhost:0", targetDir, "", "", "")
+
+	err = restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "not empty")
+}
+
+func Test_RunRestore_WhenPgDataDirDoesNotExist_ReturnsError(t *testing.T) {
+	nonExistentDir := filepath.Join(os.TempDir(), "databasus-test-nonexistent-dir-12345")
+
+	restorer := newTestRestorer("http://localhost:0", nonExistentDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "does not exist")
+}
+
+func Test_RunRestore_WhenNoBackupsAvailable_ReturnsError(t *testing.T) {
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		_ = json.NewEncoder(w).Encode(api.GetRestorePlanErrorResponse{
+			Error:   "no_backups",
+			Message: "No full backups available",
+		})
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "No full backups available")
+}
+
+func Test_RunRestore_WhenWalChainBroken_ReturnsError(t *testing.T) {
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		_ = json.NewEncoder(w).Encode(api.GetRestorePlanErrorResponse{
+			Error:                 "wal_chain_broken",
+			Message:               "WAL chain broken",
+			LastContiguousSegment: testWalSegment1,
+		})
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "WAL chain broken")
+	assert.Contains(t, err.Error(), testWalSegment1)
+}
+
+func Test_DownloadWalSegment_WhenFirstAttemptFails_RetriesAndSucceeds(t *testing.T) {
+	tarFiles := map[string][]byte{"PG_VERSION": []byte("16")}
+	zstdTarData := createZstdTar(t, tarFiles)
+	walData := createZstdData(t, []byte("wal-segment-data"))
+
+	var mu sync.Mutex
+	var walDownloadAttempts int
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments: []api.RestorePlanWalSegment{
+					{BackupID: "wal-1", SegmentName: testWalSegment1, SizeBytes: 512},
+				},
+				TotalSizeBytes:         1536,
+				LatestAvailableSegment: testWalSegment1,
+			})
+
+		case testRestoreDownloadPath:
+			backupID := r.URL.Query().Get("backupId")
+			if backupID == testFullBackupID {
+				w.Header().Set("Content-Type", "application/octet-stream")
+				_, _ = w.Write(zstdTarData)
+				return
+			}
+
+			mu.Lock()
+			walDownloadAttempts++
+			attempt := walDownloadAttempts
+			mu.Unlock()
+
+			if attempt == 1 {
+				w.WriteHeader(http.StatusInternalServerError)
+				_, _ = w.Write([]byte(`{"error":"storage unavailable"}`))
+				return
+			}
+
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write(walData)
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	origDelay := retryDelayOverride
+	testDelay := 10 * time.Millisecond
+	retryDelayOverride = &testDelay
+	defer func() { retryDelayOverride = origDelay }()
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	mu.Lock()
+	attempts := walDownloadAttempts
+	mu.Unlock()
+
+	assert.Equal(t, 2, attempts)
+
+	walContent, err := os.ReadFile(filepath.Join(targetDir, walRestoreDir, testWalSegment1))
+	require.NoError(t, err)
+	assert.Equal(t, "wal-segment-data", string(walContent))
+}
+
+func Test_DownloadWalSegment_WhenAllAttemptsFail_ReturnsErrorWithSegmentName(t *testing.T) {
+	tarFiles := map[string][]byte{"PG_VERSION": []byte("16")}
+	zstdTarData := createZstdTar(t, tarFiles)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments: []api.RestorePlanWalSegment{
+					{BackupID: "wal-1", SegmentName: testWalSegment1, SizeBytes: 512},
+				},
+				TotalSizeBytes:         1536,
+				LatestAvailableSegment: testWalSegment1,
+			})
+
+		case testRestoreDownloadPath:
+			backupID := r.URL.Query().Get("backupId")
+			if backupID == testFullBackupID {
+				w.Header().Set("Content-Type", "application/octet-stream")
+				_, _ = w.Write(zstdTarData)
+				return
+			}
+
+			w.WriteHeader(http.StatusInternalServerError)
+			_, _ = w.Write([]byte(`{"error":"storage unavailable"}`))
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	origDelay := retryDelayOverride
+	testDelay := 10 * time.Millisecond
+	retryDelayOverride = &testDelay
+	defer func() { retryDelayOverride = origDelay }()
+
+	err := restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), testWalSegment1)
+	assert.Contains(t, err.Error(), "3 attempts")
+}
+
+func Test_RunRestore_WhenInvalidTargetTimeFormat_ReturnsError(t *testing.T) {
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer("http://localhost:0", targetDir, "", "not-a-valid-time", "")
+
+	err := restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid --target-time format")
+}
+
+func Test_RunRestore_WhenBasebackupDownloadFails_ReturnsError(t *testing.T) {
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments:            []api.RestorePlanWalSegment{},
+				TotalSizeBytes:         1024,
+				LatestAvailableSegment: "",
+			})
+
+		case testRestoreDownloadPath:
+			w.WriteHeader(http.StatusInternalServerError)
+			_, _ = w.Write([]byte(`{"error":"storage error"}`))
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "basebackup download failed")
+}
+
+func Test_RunRestore_WhenNoWalSegmentsInPlan_BasebackupRestoredSuccessfully(t *testing.T) {
+	tarFiles := map[string][]byte{
+		"PG_VERSION":        []byte("16"),
+		"global/pg_control": []byte("control-data"),
+	}
+	zstdTarData := createZstdTar(t, tarFiles)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments:            []api.RestorePlanWalSegment{},
+				TotalSizeBytes:         1024,
+				LatestAvailableSegment: "",
+			})
+
+		case testRestoreDownloadPath:
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write(zstdTarData)
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	pgVersionContent, err := os.ReadFile(filepath.Join(targetDir, "PG_VERSION"))
+	require.NoError(t, err)
+	assert.Equal(t, "16", string(pgVersionContent))
+
+	walRestoreDirInfo, err := os.Stat(filepath.Join(targetDir, walRestoreDir))
+	require.NoError(t, err)
+	assert.True(t, walRestoreDirInfo.IsDir())
+
+	_, err = os.Stat(filepath.Join(targetDir, "recovery.signal"))
+	require.NoError(t, err)
+
+	autoConfContent, err := os.ReadFile(filepath.Join(targetDir, "postgresql.auto.conf"))
+	require.NoError(t, err)
+	assert.Contains(t, string(autoConfContent), "restore_command")
+}
+
+func Test_RunRestore_WhenMakingApiCalls_AuthTokenIncludedInRequests(t *testing.T) {
+	tarFiles := map[string][]byte{"PG_VERSION": []byte("16")}
+	zstdTarData := createZstdTar(t, tarFiles)
+
+	var receivedAuthHeaders atomic.Int32
+	var mu sync.Mutex
+	var authHeaderValues []string
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		authHeader := r.Header.Get("Authorization")
+		if authHeader != "" {
+			receivedAuthHeaders.Add(1)
+
+			mu.Lock()
+			authHeaderValues = append(authHeaderValues, authHeader)
+			mu.Unlock()
+		}
+
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments:            []api.RestorePlanWalSegment{},
+				TotalSizeBytes:         1024,
+				LatestAvailableSegment: "",
+			})
+
+		case testRestoreDownloadPath:
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write(zstdTarData)
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "")
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	assert.GreaterOrEqual(t, int(receivedAuthHeaders.Load()), 2)
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	for _, headerValue := range authHeaderValues {
+		assert.Equal(t, "test-token", headerValue)
+	}
+}
+
+func Test_ConfigurePostgresRecovery_WhenPgTypeHost_UsesHostAbsolutePath(t *testing.T) {
+	tarFiles := map[string][]byte{"PG_VERSION": []byte("16")}
+	zstdTarData := createZstdTar(t, tarFiles)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments:            []api.RestorePlanWalSegment{},
+				TotalSizeBytes:         1024,
+				LatestAvailableSegment: "",
+			})
+
+		case testRestoreDownloadPath:
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write(zstdTarData)
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "host")
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	autoConfContent, err := os.ReadFile(filepath.Join(targetDir, "postgresql.auto.conf"))
+	require.NoError(t, err)
+	autoConfStr := string(autoConfContent)
+
+	absTargetDir, _ := filepath.Abs(targetDir)
+	absTargetDir = filepath.ToSlash(absTargetDir)
+	expectedWalPath := absTargetDir + "/" + walRestoreDir
+
+	assert.Contains(t, autoConfStr, fmt.Sprintf("restore_command = 'cp %s/%%f %%p'", expectedWalPath))
+	assert.Contains(t, autoConfStr, fmt.Sprintf("recovery_end_command = 'rm -rf %s'", expectedWalPath))
+	assert.NotContains(t, autoConfStr, "/var/lib/postgresql/data")
+}
+
+func Test_ConfigurePostgresRecovery_WhenPgTypeDocker_UsesContainerPath(t *testing.T) {
+	tarFiles := map[string][]byte{"PG_VERSION": []byte("16")}
+	zstdTarData := createZstdTar(t, tarFiles)
+
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case testRestorePlanPath:
+			writeJSON(w, api.GetRestorePlanResponse{
+				FullBackup: api.RestorePlanFullBackup{
+					BackupID:  testFullBackupID,
+					PgVersion: "16",
+					CreatedAt: time.Now().UTC(),
+					SizeBytes: 1024,
+				},
+				WalSegments:            []api.RestorePlanWalSegment{},
+				TotalSizeBytes:         1024,
+				LatestAvailableSegment: "",
+			})
+
+		case testRestoreDownloadPath:
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write(zstdTarData)
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	targetDir := createTestTargetDir(t)
+	restorer := newTestRestorer(server.URL, targetDir, "", "", "docker")
+
+	err := restorer.Run(t.Context())
+	require.NoError(t, err)
+
+	autoConfContent, err := os.ReadFile(filepath.Join(targetDir, "postgresql.auto.conf"))
+	require.NoError(t, err)
+	autoConfStr := string(autoConfContent)
+
+	expectedWalPath := "/var/lib/postgresql/data/" + walRestoreDir
+
+	assert.Contains(t, autoConfStr, fmt.Sprintf("restore_command = 'cp %s/%%f %%p'", expectedWalPath))
+	assert.Contains(t, autoConfStr, fmt.Sprintf("recovery_end_command = 'rm -rf %s'", expectedWalPath))
+
+	absTargetDir, _ := filepath.Abs(targetDir)
+	absTargetDir = filepath.ToSlash(absTargetDir)
+	assert.NotContains(t, autoConfStr, absTargetDir)
+}
+
+func newTestServer(t *testing.T, handler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+
+	server := httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+
+	return server
+}
+
+func createTestTargetDir(t *testing.T) string {
+	t.Helper()
+
+	baseDir := filepath.Join(".", ".test-tmp")
+	if err := os.MkdirAll(baseDir, 0o755); err != nil {
+		t.Fatalf("failed to create base test dir: %v", err)
+	}
+
+	dir, err := os.MkdirTemp(baseDir, t.Name()+"-*")
+	if err != nil {
+		t.Fatalf("failed to create test target dir: %v", err)
+	}
+
+	t.Cleanup(func() {
+		_ = os.RemoveAll(dir)
+	})
+
+	return dir
+}
+
+func createZstdTar(t *testing.T, files map[string][]byte) []byte {
+	t.Helper()
+
+	var tarBuffer bytes.Buffer
+	tarWriter := tar.NewWriter(&tarBuffer)
+
+	createdDirs := make(map[string]bool)
+
+	for name, content := range files {
+		dir := filepath.Dir(name)
+		if dir != "." && !createdDirs[dir] {
+			parts := strings.Split(filepath.ToSlash(dir), "/")
+			for partIndex := range parts {
+				partialDir := strings.Join(parts[:partIndex+1], "/")
+				if !createdDirs[partialDir] {
+					err := tarWriter.WriteHeader(&tar.Header{
+						Name:     partialDir + "/",
+						Typeflag: tar.TypeDir,
+						Mode:     0o755,
+					})
+					require.NoError(t, err)
+
+					createdDirs[partialDir] = true
+				}
+			}
+		}
+
+		err := tarWriter.WriteHeader(&tar.Header{
+			Name:     name,
+			Size:     int64(len(content)),
+			Mode:     0o644,
+			Typeflag: tar.TypeReg,
+		})
+		require.NoError(t, err)
+
+		_, err = tarWriter.Write(content)
+		require.NoError(t, err)
+	}
+
+	require.NoError(t, tarWriter.Close())
+
+	var zstdBuffer bytes.Buffer
+
+	encoder, err := zstd.NewWriter(&zstdBuffer,
+		zstd.WithEncoderLevel(zstd.EncoderLevelFromZstd(5)),
+		zstd.WithEncoderCRC(true),
+	)
+	require.NoError(t, err)
+
+	_, err = encoder.Write(tarBuffer.Bytes())
+	require.NoError(t, err)
+	require.NoError(t, encoder.Close())
+
+	return zstdBuffer.Bytes()
+}
+
+func createZstdData(t *testing.T, data []byte) []byte {
+	t.Helper()
+
+	var buffer bytes.Buffer
+
+	encoder, err := zstd.NewWriter(&buffer,
+		zstd.WithEncoderLevel(zstd.EncoderLevelFromZstd(5)),
+		zstd.WithEncoderCRC(true),
+	)
+	require.NoError(t, err)
+
+	_, err = encoder.Write(data)
+	require.NoError(t, err)
+	require.NoError(t, encoder.Close())
+
+	return buffer.Bytes()
+}
+
+func newTestRestorer(serverURL, targetPgDataDir, backupID, targetTime, pgType string) *Restorer {
+	apiClient := api.NewClient(serverURL, "test-token", logger.GetLogger())
+
+	return NewRestorer(apiClient, logger.GetLogger(), targetPgDataDir, backupID, targetTime, pgType)
+}
+
+func writeJSON(w http.ResponseWriter, value any) {
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(value); err != nil {
+		w.WriteHeader(http.StatusInternalServerError)
+	}
+}

agent/internal/features/start/daemon.go

@@ -0,0 +1,121 @@
+//go:build !windows
+
+package start
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"os/exec"
+	"syscall"
+	"time"
+)
+
+const (
+	logFileName        = "databasus.log"
+	stopTimeout        = 30 * time.Second
+	stopPollInterval   = 500 * time.Millisecond
+	daemonStartupDelay = 500 * time.Millisecond
+)
+
+func Stop(log *slog.Logger) error {
+	pid, err := ReadLockFilePID()
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return errors.New("agent is not running (no lock file found)")
+		}
+
+		return fmt.Errorf("failed to read lock file: %w", err)
+	}
+
+	if !isProcessAlive(pid) {
+		_ = os.Remove(lockFileName)
+		return fmt.Errorf("agent is not running (stale lock file removed, PID %d)", pid)
+	}
+
+	log.Info("Sending SIGTERM to agent", "pid", pid)
+
+	if err := syscall.Kill(pid, syscall.SIGTERM); err != nil {
+		return fmt.Errorf("failed to send SIGTERM to PID %d: %w", pid, err)
+	}
+
+	deadline := time.Now().Add(stopTimeout)
+	for time.Now().Before(deadline) {
+		if !isProcessAlive(pid) {
+			log.Info("Agent stopped", "pid", pid)
+			return nil
+		}
+
+		time.Sleep(stopPollInterval)
+	}
+
+	return fmt.Errorf("agent (PID %d) did not stop within %s — process may be stuck", pid, stopTimeout)
+}
+
+func Status(log *slog.Logger) error {
+	pid, err := ReadLockFilePID()
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			fmt.Println("Agent is not running")
+			return nil
+		}
+
+		return fmt.Errorf("failed to read lock file: %w", err)
+	}
+
+	if isProcessAlive(pid) {
+		fmt.Printf("Agent is running (PID %d)\n", pid)
+	} else {
+		fmt.Println("Agent is not running (stale lock file)")
+		_ = os.Remove(lockFileName)
+	}
+
+	return nil
+}
+
+func spawnDaemon(log *slog.Logger) (int, error) {
+	execPath, err := os.Executable()
+	if err != nil {
+		return 0, fmt.Errorf("failed to resolve executable path: %w", err)
+	}
+
+	args := []string{"_run"}
+
+	logFile, err := os.OpenFile(logFileName, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		return 0, fmt.Errorf("failed to open log file %s: %w", logFileName, err)
+	}
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		_ = logFile.Close()
+		return 0, fmt.Errorf("failed to get working directory: %w", err)
+	}
+
+	cmd := exec.CommandContext(context.Background(), execPath, args...)
+	cmd.Dir = cwd
+	cmd.Stderr = logFile
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+
+	if err := cmd.Start(); err != nil {
+		_ = logFile.Close()
+		return 0, fmt.Errorf("failed to start daemon process: %w", err)
+	}
+
+	pid := cmd.Process.Pid
+
+	// Detach — we don't wait for the child
+	_ = logFile.Close()
+
+	time.Sleep(daemonStartupDelay)
+
+	if !isProcessAlive(pid) {
+		return 0, fmt.Errorf("daemon process (PID %d) exited immediately — check %s for details", pid, logFileName)
+	}
+
+	log.Info("Daemon spawned", "pid", pid, "log", logFileName)
+
+	return pid, nil
+}

agent/internal/features/start/daemon_windows.go

@@ -0,0 +1,20 @@
+//go:build windows
+
+package start
+
+import (
+	"errors"
+	"log/slog"
+)
+
+func Stop(log *slog.Logger) error {
+	return errors.New("stop is not supported on Windows — use Ctrl+C in the terminal where the agent is running")
+}
+
+func Status(log *slog.Logger) error {
+	return errors.New("status is not supported on Windows — check the terminal where the agent is running")
+}
+
+func spawnDaemon(_ *slog.Logger) (int, error) {
+	return 0, errors.New("daemon mode is not supported on Windows")
+}

agent/internal/features/start/lock.go

@@ -0,0 +1,132 @@
+//go:build !windows
+
+package start
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"strconv"
+	"strings"
+	"syscall"
+)
+
+const lockFileName = "databasus.lock"
+
+func AcquireLock(log *slog.Logger) (*os.File, error) {
+	f, err := os.OpenFile(lockFileName, os.O_CREATE|os.O_RDWR, 0o644)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open lock file: %w", err)
+	}
+
+	err = syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
+	if err == nil {
+		if err := writePID(f); err != nil {
+			_ = f.Close()
+			return nil, err
+		}
+
+		log.Info("Process lock acquired", "pid", os.Getpid(), "lockFile", lockFileName)
+
+		return f, nil
+	}
+
+	if !errors.Is(err, syscall.EWOULDBLOCK) {
+		_ = f.Close()
+		return nil, fmt.Errorf("failed to acquire lock: %w", err)
+	}
+
+	pid, pidErr := readLockPID(f)
+	_ = f.Close()
+
+	if pidErr != nil {
+		return nil, fmt.Errorf("another instance is already running")
+	}
+
+	return nil, fmt.Errorf("another instance is already running (PID %d)", pid)
+}
+
+func ReleaseLock(f *os.File) {
+	_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+
+	lockedStat, lockedErr := f.Stat()
+	_ = f.Close()
+
+	if lockedErr != nil {
+		_ = os.Remove(lockFileName)
+		return
+	}
+
+	diskStat, diskErr := os.Stat(lockFileName)
+	if diskErr != nil {
+		return
+	}
+
+	if os.SameFile(lockedStat, diskStat) {
+		_ = os.Remove(lockFileName)
+	}
+}
+
+func ReadLockFilePID() (int, error) {
+	f, err := os.Open(lockFileName)
+	if err != nil {
+		return 0, err
+	}
+	defer func() { _ = f.Close() }()
+
+	return readLockPID(f)
+}
+
+func writePID(f *os.File) error {
+	if err := f.Truncate(0); err != nil {
+		return fmt.Errorf("failed to truncate lock file: %w", err)
+	}
+
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return fmt.Errorf("failed to seek lock file: %w", err)
+	}
+
+	if _, err := fmt.Fprintf(f, "%d\n", os.Getpid()); err != nil {
+		return fmt.Errorf("failed to write PID to lock file: %w", err)
+	}
+
+	return f.Sync()
+}
+
+func readLockPID(f *os.File) (int, error) {
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return 0, err
+	}
+
+	data, err := io.ReadAll(f)
+	if err != nil {
+		return 0, err
+	}
+
+	s := strings.TrimSpace(string(data))
+	if s == "" {
+		return 0, errors.New("lock file is empty")
+	}
+
+	pid, err := strconv.Atoi(s)
+	if err != nil {
+		return 0, fmt.Errorf("invalid PID in lock file: %w", err)
+	}
+
+	return pid, nil
+}
+
+func isProcessAlive(pid int) bool {
+	err := syscall.Kill(pid, 0)
+	if err == nil {
+		return true
+	}
+
+	if errors.Is(err, syscall.EPERM) {
+		return true
+	}
+
+	return false
+}

agent/internal/features/start/lock_test.go

@@ -0,0 +1,148 @@
+//go:build !windows
+
+package start
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"databasus-agent/internal/logger"
+)
+
+func Test_AcquireLock_LockFileCreatedWithPID(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(lockFile)
+
+	data, err := os.ReadFile(lockFileName)
+	require.NoError(t, err)
+
+	pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	require.NoError(t, err)
+	assert.Equal(t, os.Getpid(), pid)
+}
+
+func Test_AcquireLock_SecondAcquireFails_WhenFirstHeld(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	first, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(first)
+
+	second, err := AcquireLock(log)
+	assert.Nil(t, second)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "another instance is already running")
+	assert.Contains(t, err.Error(), fmt.Sprintf("PID %d", os.Getpid()))
+}
+
+func Test_AcquireLock_StaleLockReacquired_WhenProcessDead(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	err := os.WriteFile(lockFileName, []byte("999999999\n"), 0o644)
+	require.NoError(t, err)
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(lockFile)
+
+	data, err := os.ReadFile(lockFileName)
+	require.NoError(t, err)
+
+	pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	require.NoError(t, err)
+	assert.Equal(t, os.Getpid(), pid)
+}
+
+func Test_ReleaseLock_LockFileRemoved(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+
+	ReleaseLock(lockFile)
+
+	_, err = os.Stat(lockFileName)
+	assert.True(t, os.IsNotExist(err))
+}
+
+func Test_AcquireLock_ReacquiredAfterRelease(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	first, err := AcquireLock(log)
+	require.NoError(t, err)
+	ReleaseLock(first)
+
+	second, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(second)
+
+	data, err := os.ReadFile(lockFileName)
+	require.NoError(t, err)
+
+	pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	require.NoError(t, err)
+	assert.Equal(t, os.Getpid(), pid)
+}
+
+func Test_isProcessAlive_ReturnsTrueForSelf(t *testing.T) {
+	assert.True(t, isProcessAlive(os.Getpid()))
+}
+
+func Test_isProcessAlive_ReturnsFalseForNonExistentPID(t *testing.T) {
+	assert.False(t, isProcessAlive(999999999))
+}
+
+func Test_readLockPID_ParsesValidPID(t *testing.T) {
+	setupTempDir(t)
+
+	f, err := os.CreateTemp("", "lock-test-*")
+	require.NoError(t, err)
+	defer os.Remove(f.Name())
+
+	_, err = f.WriteString("12345\n")
+	require.NoError(t, err)
+
+	pid, err := readLockPID(f)
+	require.NoError(t, err)
+	assert.Equal(t, 12345, pid)
+}
+
+func Test_readLockPID_ReturnsErrorForEmptyFile(t *testing.T) {
+	setupTempDir(t)
+
+	f, err := os.CreateTemp("", "lock-test-*")
+	require.NoError(t, err)
+	defer os.Remove(f.Name())
+
+	_, err = readLockPID(f)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "lock file is empty")
+}
+
+func setupTempDir(t *testing.T) string {
+	t.Helper()
+
+	origDir, err := os.Getwd()
+	require.NoError(t, err)
+
+	dir := t.TempDir()
+	require.NoError(t, os.Chdir(dir))
+
+	t.Cleanup(func() { _ = os.Chdir(origDir) })
+
+	return dir
+}

agent/internal/features/start/lock_watcher.go

@@ -0,0 +1,90 @@
+//go:build !windows
+
+package start
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"syscall"
+	"time"
+)
+
+const lockWatchInterval = 5 * time.Second
+
+type LockWatcher struct {
+	originalInode uint64
+	cancel        context.CancelFunc
+	log           *slog.Logger
+}
+
+func NewLockWatcher(lockFile *os.File, cancel context.CancelFunc, log *slog.Logger) (*LockWatcher, error) {
+	inode, err := getFileInode(lockFile)
+	if err != nil {
+		return nil, err
+	}
+
+	return &LockWatcher{
+		originalInode: inode,
+		cancel:        cancel,
+		log:           log,
+	}, nil
+}
+
+func (w *LockWatcher) Run(ctx context.Context) {
+	ticker := time.NewTicker(lockWatchInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			w.check()
+		}
+	}
+}
+
+func (w *LockWatcher) check() {
+	info, err := os.Stat(lockFileName)
+	if err != nil {
+		w.log.Error("Lock file disappeared, shutting down", "file", lockFileName, "error", err)
+		w.cancel()
+
+		return
+	}
+
+	currentInode, err := getStatInode(info)
+	if err != nil {
+		w.log.Error("Failed to read lock file inode, shutting down", "error", err)
+		w.cancel()
+
+		return
+	}
+
+	if currentInode != w.originalInode {
+		w.log.Error("Lock file was replaced (inode changed), shutting down",
+			"originalInode", w.originalInode,
+			"currentInode", currentInode,
+		)
+		w.cancel()
+	}
+}
+
+func getFileInode(f *os.File) (uint64, error) {
+	info, err := f.Stat()
+	if err != nil {
+		return 0, err
+	}
+
+	return getStatInode(info)
+}
+
+func getStatInode(info os.FileInfo) (uint64, error) {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, os.ErrInvalid
+	}
+
+	return stat.Ino, nil
+}

agent/internal/features/start/lock_watcher_test.go

@@ -0,0 +1,110 @@
+//go:build !windows
+
+package start
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"databasus-agent/internal/logger"
+)
+
+func Test_NewLockWatcher_CapturesInode(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(lockFile)
+
+	_, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	watcher, err := NewLockWatcher(lockFile, cancel, log)
+	require.NoError(t, err)
+	assert.NotZero(t, watcher.originalInode)
+}
+
+func Test_LockWatcher_FileUnchanged_ContextNotCancelled(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(lockFile)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	watcher, err := NewLockWatcher(lockFile, cancel, log)
+	require.NoError(t, err)
+
+	watcher.check()
+	watcher.check()
+	watcher.check()
+
+	select {
+	case <-ctx.Done():
+		t.Fatal("context should not be cancelled when lock file is unchanged")
+	default:
+	}
+}
+
+func Test_LockWatcher_FileDeleted_CancelsContext(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(lockFile)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	watcher, err := NewLockWatcher(lockFile, cancel, log)
+	require.NoError(t, err)
+
+	err = os.Remove(lockFileName)
+	require.NoError(t, err)
+
+	watcher.check()
+
+	select {
+	case <-ctx.Done():
+	default:
+		t.Fatal("context should be cancelled when lock file is deleted")
+	}
+}
+
+func Test_LockWatcher_FileReplacedWithDifferentInode_CancelsContext(t *testing.T) {
+	setupTempDir(t)
+	log := logger.GetLogger()
+
+	lockFile, err := AcquireLock(log)
+	require.NoError(t, err)
+	defer ReleaseLock(lockFile)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	watcher, err := NewLockWatcher(lockFile, cancel, log)
+	require.NoError(t, err)
+
+	err = os.Remove(lockFileName)
+	require.NoError(t, err)
+
+	err = os.WriteFile(lockFileName, []byte("99999\n"), 0o644)
+	require.NoError(t, err)
+
+	watcher.check()
+
+	select {
+	case <-ctx.Done():
+	default:
+		t.Fatal("context should be cancelled when lock file inode changes")
+	}
+}

agent/internal/features/start/lock_watcher_windows.go

@@ -0,0 +1,17 @@
+//go:build windows
+
+package start
+
+import (
+	"context"
+	"log/slog"
+	"os"
+)
+
+type LockWatcher struct{}
+
+func NewLockWatcher(_ *os.File, _ context.CancelFunc, _ *slog.Logger) (*LockWatcher, error) {
+	return &LockWatcher{}, nil
+}
+
+func (w *LockWatcher) Run(_ context.Context) {}

agent/internal/features/start/lock_windows.go

@@ -0,0 +1,18 @@
+package start
+
+import (
+	"log/slog"
+	"os"
+)
+
+func AcquireLock(log *slog.Logger) (*os.File, error) {
+	log.Warn("Process locking is not supported on Windows, skipping")
+
+	return nil, nil
+}
+
+func ReleaseLock(f *os.File) {
+	if f != nil {
+		_ = f.Close()
+	}
+}

agent/internal/features/start/start.go

@@ -0,0 +1,325 @@
+package start
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"databasus-agent/internal/config"
+	"databasus-agent/internal/features/api"
+	full_backup "databasus-agent/internal/features/full_backup"
+	"databasus-agent/internal/features/upgrade"
+	"databasus-agent/internal/features/wal"
+)
+
+const (
+	pgBasebackupVerifyTimeout = 10 * time.Second
+	dbVerifyTimeout           = 10 * time.Second
+	minPgMajorVersion         = 15
+)
+
+func Start(cfg *config.Config, agentVersion string, isDev bool, log *slog.Logger) error {
+	if err := validateConfig(cfg); err != nil {
+		return err
+	}
+
+	if err := verifyPgBasebackup(cfg, log); err != nil {
+		return err
+	}
+
+	if err := verifyDatabase(cfg, log); err != nil {
+		return err
+	}
+
+	if runtime.GOOS == "windows" {
+		return RunDaemon(cfg, agentVersion, isDev, log)
+	}
+
+	pid, err := spawnDaemon(log)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Agent started in background (PID %d)\n", pid)
+
+	return nil
+}
+
+func RunDaemon(cfg *config.Config, agentVersion string, isDev bool, log *slog.Logger) error {
+	lockFile, err := AcquireLock(log)
+	if err != nil {
+		return err
+	}
+	defer ReleaseLock(lockFile)
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+
+	watcher, err := NewLockWatcher(lockFile, cancel, log)
+	if err != nil {
+		return fmt.Errorf("failed to initialize lock watcher: %w", err)
+	}
+	go watcher.Run(ctx)
+
+	apiClient := api.NewClient(cfg.DatabasusHost, cfg.Token, log)
+
+	var backgroundUpgrader *upgrade.BackgroundUpgrader
+	if agentVersion != "dev" && runtime.GOOS != "windows" {
+		backgroundUpgrader = upgrade.NewBackgroundUpgrader(apiClient, agentVersion, isDev, cancel, log)
+		go backgroundUpgrader.Run(ctx)
+	}
+
+	fullBackuper := full_backup.NewFullBackuper(cfg, apiClient, log)
+	go fullBackuper.Run(ctx)
+
+	streamer := wal.NewStreamer(cfg, apiClient, log)
+	streamer.Run(ctx)
+
+	if backgroundUpgrader != nil {
+		backgroundUpgrader.WaitForCompletion(30 * time.Second)
+
+		if backgroundUpgrader.IsUpgraded() {
+			return upgrade.ErrUpgradeRestart
+		}
+	}
+
+	log.Info("Agent stopped")
+
+	return nil
+}
+
+func validateConfig(cfg *config.Config) error {
+	if cfg.DatabasusHost == "" {
+		return errors.New("argument databasus-host is required")
+	}
+
+	if cfg.DbID == "" {
+		return errors.New("argument db-id is required")
+	}
+
+	if cfg.Token == "" {
+		return errors.New("argument token is required")
+	}
+
+	if cfg.PgHost == "" {
+		return errors.New("argument pg-host is required")
+	}
+
+	if cfg.PgPort <= 0 {
+		return errors.New("argument pg-port must be a positive number")
+	}
+
+	if cfg.PgUser == "" {
+		return errors.New("argument pg-user is required")
+	}
+
+	if cfg.PgType != "host" && cfg.PgType != "docker" {
+		return fmt.Errorf("argument pg-type must be 'host' or 'docker', got '%s'", cfg.PgType)
+	}
+
+	if cfg.PgWalDir == "" {
+		return errors.New("argument pg-wal-dir is required")
+	}
+
+	if cfg.PgType == "docker" && cfg.PgDockerContainerName == "" {
+		return errors.New("argument pg-docker-container-name is required when pg-type is 'docker'")
+	}
+
+	return nil
+}
+
+func verifyPgBasebackup(cfg *config.Config, log *slog.Logger) error {
+	switch cfg.PgType {
+	case "host":
+		return verifyPgBasebackupHost(cfg, log)
+	case "docker":
+		return verifyPgBasebackupDocker(cfg, log)
+	default:
+		return fmt.Errorf("unexpected pg-type: %s", cfg.PgType)
+	}
+}
+
+func verifyPgBasebackupHost(cfg *config.Config, log *slog.Logger) error {
+	binary := "pg_basebackup"
+	if cfg.PgHostBinDir != "" {
+		binary = filepath.Join(cfg.PgHostBinDir, "pg_basebackup")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), pgBasebackupVerifyTimeout)
+	defer cancel()
+
+	output, err := exec.CommandContext(ctx, binary, "--version").CombinedOutput()
+	if err != nil {
+		if cfg.PgHostBinDir != "" {
+			return fmt.Errorf(
+				"pg_basebackup not found at '%s': %w. Verify pg-host-bin-dir is correct",
+				binary, err,
+			)
+		}
+
+		return fmt.Errorf(
+			"pg_basebackup not found in PATH: %w. Install PostgreSQL client tools or set pg-host-bin-dir",
+			err,
+		)
+	}
+
+	log.Info("pg_basebackup verified", "version", strings.TrimSpace(string(output)))
+
+	return nil
+}
+
+func verifyPgBasebackupDocker(cfg *config.Config, log *slog.Logger) error {
+	ctx, cancel := context.WithTimeout(context.Background(), pgBasebackupVerifyTimeout)
+	defer cancel()
+
+	output, err := exec.CommandContext(ctx,
+		"docker", "exec", cfg.PgDockerContainerName,
+		"pg_basebackup", "--version",
+	).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf(
+			"pg_basebackup not available in container '%s': %w. "+
+				"Check that the container is running and pg_basebackup is installed inside it",
+			cfg.PgDockerContainerName, err,
+		)
+	}
+
+	log.Info("pg_basebackup verified (docker)",
+		"container", cfg.PgDockerContainerName,
+		"version", strings.TrimSpace(string(output)),
+	)
+
+	return nil
+}
+
+func verifyDatabase(cfg *config.Config, log *slog.Logger) error {
+	switch cfg.PgType {
+	case "docker":
+		return verifyDatabaseDocker(cfg, log)
+	default:
+		return verifyDatabaseHost(cfg, log)
+	}
+}
+
+func verifyDatabaseHost(cfg *config.Config, log *slog.Logger) error {
+	connStr := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=postgres sslmode=disable",
+		cfg.PgHost, cfg.PgPort, cfg.PgUser, cfg.PgPassword,
+	)
+
+	ctx, cancel := context.WithTimeout(context.Background(), dbVerifyTimeout)
+	defer cancel()
+
+	conn, err := pgx.Connect(ctx, connStr)
+	if err != nil {
+		return fmt.Errorf(
+			"failed to connect to PostgreSQL at %s:%d as user '%s': %w",
+			cfg.PgHost, cfg.PgPort, cfg.PgUser, err,
+		)
+	}
+	defer func() { _ = conn.Close(ctx) }()
+
+	if err := conn.Ping(ctx); err != nil {
+		return fmt.Errorf("PostgreSQL ping failed at %s:%d: %w",
+			cfg.PgHost, cfg.PgPort, err,
+		)
+	}
+
+	var versionNumStr string
+	if err := conn.QueryRow(ctx, "SHOW server_version_num").Scan(&versionNumStr); err != nil {
+		return fmt.Errorf("failed to query PostgreSQL version: %w", err)
+	}
+
+	majorVersion, err := parsePgVersionNum(versionNumStr)
+	if err != nil {
+		return fmt.Errorf("failed to parse PostgreSQL version '%s': %w", versionNumStr, err)
+	}
+
+	if majorVersion < minPgMajorVersion {
+		return fmt.Errorf(
+			"PostgreSQL %d is not supported, minimum required version is %d",
+			majorVersion, minPgMajorVersion,
+		)
+	}
+
+	log.Info("PostgreSQL connection verified",
+		"host", cfg.PgHost,
+		"port", cfg.PgPort,
+		"user", cfg.PgUser,
+		"version", majorVersion,
+	)
+
+	return nil
+}
+
+func verifyDatabaseDocker(cfg *config.Config, log *slog.Logger) error {
+	ctx, cancel := context.WithTimeout(context.Background(), dbVerifyTimeout)
+	defer cancel()
+
+	query := "SELECT current_setting('server_version_num')"
+
+	cmd := exec.CommandContext(ctx,
+		"docker", "exec",
+		"-e", "PGPASSWORD="+cfg.PgPassword,
+		cfg.PgDockerContainerName,
+		"psql", "-h", "localhost", "-p", "5432", "-U", cfg.PgUser,
+		"-d", "postgres", "-t", "-A", "-c", query,
+	)
+
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf(
+			"failed to connect to PostgreSQL in container '%s' as user '%s': %w (output: %s)",
+			cfg.PgDockerContainerName, cfg.PgUser, err, strings.TrimSpace(string(output)),
+		)
+	}
+
+	versionNumStr := strings.TrimSpace(string(output))
+
+	majorVersion, err := parsePgVersionNum(versionNumStr)
+	if err != nil {
+		return fmt.Errorf("failed to parse PostgreSQL version '%s': %w", versionNumStr, err)
+	}
+
+	if majorVersion < minPgMajorVersion {
+		return fmt.Errorf(
+			"PostgreSQL %d is not supported, minimum required version is %d",
+			majorVersion, minPgMajorVersion,
+		)
+	}
+
+	log.Info("PostgreSQL connection verified (docker)",
+		"container", cfg.PgDockerContainerName,
+		"user", cfg.PgUser,
+		"version", majorVersion,
+	)
+
+	return nil
+}
+
+func parsePgVersionNum(versionNumStr string) (int, error) {
+	versionNum, err := strconv.Atoi(strings.TrimSpace(versionNumStr))
+	if err != nil {
+		return 0, fmt.Errorf("invalid version number: %w", err)
+	}
+
+	if versionNum <= 0 {
+		return 0, fmt.Errorf("invalid version number: %d", versionNum)
+	}
+
+	majorVersion := versionNum / 10000
+
+	return majorVersion, nil
+}

agent/internal/features/start/start_test.go

@@ -0,0 +1,84 @@
+package start
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_ParsePgVersionNum_SupportedVersions_ReturnsMajorVersion(t *testing.T) {
+	tests := []struct {
+		name          string
+		versionNumStr string
+		expectedMajor int
+	}{
+		{name: "PG 15.0", versionNumStr: "150000", expectedMajor: 15},
+		{name: "PG 15.4", versionNumStr: "150004", expectedMajor: 15},
+		{name: "PG 16.0", versionNumStr: "160000", expectedMajor: 16},
+		{name: "PG 16.3", versionNumStr: "160003", expectedMajor: 16},
+		{name: "PG 17.2", versionNumStr: "170002", expectedMajor: 17},
+		{name: "PG 18.0", versionNumStr: "180000", expectedMajor: 18},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			major, err := parsePgVersionNum(tt.versionNumStr)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expectedMajor, major)
+			assert.GreaterOrEqual(t, major, minPgMajorVersion)
+		})
+	}
+}
+
+func Test_ParsePgVersionNum_UnsupportedVersions_ReturnsMajorVersionBelow15(t *testing.T) {
+	tests := []struct {
+		name          string
+		versionNumStr string
+		expectedMajor int
+	}{
+		{name: "PG 12.5", versionNumStr: "120005", expectedMajor: 12},
+		{name: "PG 13.0", versionNumStr: "130000", expectedMajor: 13},
+		{name: "PG 14.12", versionNumStr: "140012", expectedMajor: 14},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			major, err := parsePgVersionNum(tt.versionNumStr)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expectedMajor, major)
+			assert.Less(t, major, minPgMajorVersion)
+		})
+	}
+}
+
+func Test_ParsePgVersionNum_InvalidInput_ReturnsError(t *testing.T) {
+	tests := []struct {
+		name          string
+		versionNumStr string
+	}{
+		{name: "empty string", versionNumStr: ""},
+		{name: "non-numeric", versionNumStr: "abc"},
+		{name: "negative number", versionNumStr: "-1"},
+		{name: "zero", versionNumStr: "0"},
+		{name: "float", versionNumStr: "15.4"},
+		{name: "whitespace only", versionNumStr: "   "},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := parsePgVersionNum(tt.versionNumStr)
+
+			require.Error(t, err)
+		})
+	}
+}
+
+func Test_ParsePgVersionNum_WithWhitespace_ParsesCorrectly(t *testing.T) {
+	major, err := parsePgVersionNum("  150004  ")
+
+	require.NoError(t, err)
+	assert.Equal(t, 15, major)
+}

agent/internal/features/upgrade/background_upgrader.go

@@ -0,0 +1,88 @@
+package upgrade
+
+import (
+	"context"
+	"log/slog"
+	"sync/atomic"
+	"time"
+
+	"databasus-agent/internal/features/api"
+)
+
+const backgroundCheckInterval = 10 * time.Second
+
+type BackgroundUpgrader struct {
+	apiClient      *api.Client
+	currentVersion string
+	isDev          bool
+	cancel         context.CancelFunc
+	isUpgraded     atomic.Bool
+	log            *slog.Logger
+	done           chan struct{}
+}
+
+func NewBackgroundUpgrader(
+	apiClient *api.Client,
+	currentVersion string,
+	isDev bool,
+	cancel context.CancelFunc,
+	log *slog.Logger,
+) *BackgroundUpgrader {
+	return &BackgroundUpgrader{
+		apiClient,
+		currentVersion,
+		isDev,
+		cancel,
+		atomic.Bool{},
+		log,
+		make(chan struct{}),
+	}
+}
+
+func (u *BackgroundUpgrader) Run(ctx context.Context) {
+	defer close(u.done)
+
+	ticker := time.NewTicker(backgroundCheckInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			if u.checkAndUpgrade() {
+				return
+			}
+		}
+	}
+}
+
+func (u *BackgroundUpgrader) IsUpgraded() bool {
+	return u.isUpgraded.Load()
+}
+
+func (u *BackgroundUpgrader) WaitForCompletion(timeout time.Duration) {
+	select {
+	case <-u.done:
+	case <-time.After(timeout):
+	}
+}
+
+func (u *BackgroundUpgrader) checkAndUpgrade() bool {
+	isUpgraded, err := CheckAndUpdate(u.apiClient, u.currentVersion, u.isDev, u.log)
+	if err != nil {
+		u.log.Warn("Background update check failed", "error", err)
+
+		return false
+	}
+
+	if !isUpgraded {
+		return false
+	}
+
+	u.log.Info("Background upgrade complete, restarting...")
+	u.isUpgraded.Store(true)
+	u.cancel()
+
+	return true
+}

agent/internal/features/upgrade/errors.go

@@ -0,0 +1,5 @@
+package upgrade
+
+import "errors"
+
+var ErrUpgradeRestart = errors.New("agent upgraded, restart required")

agent/internal/features/upgrade/upgrader.go

@@ -0,0 +1,89 @@
+package upgrade
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"os/exec"
+	"runtime"
+	"strings"
+
+	"databasus-agent/internal/features/api"
+)
+
+// CheckAndUpdate checks if a new version is available and upgrades the binary on disk.
+// Returns (true, nil) if the binary was upgraded, (false, nil) if already up to date,
+// or (false, err) on failure. Callers are responsible for re-exec or restart signaling.
+func CheckAndUpdate(apiClient *api.Client, currentVersion string, isDev bool, log *slog.Logger) (bool, error) {
+	if isDev {
+		log.Info("Skipping update check (development mode)")
+
+		return false, nil
+	}
+
+	serverVersion, err := apiClient.FetchServerVersion(context.Background())
+	if err != nil {
+		log.Warn("Could not reach server for update check", "error", err)
+
+		return false, fmt.Errorf(
+			"unable to check version, please verify Databasus server is available: %w",
+			err,
+		)
+	}
+
+	if serverVersion == currentVersion {
+		log.Info("Agent version is up to date", "version", currentVersion)
+
+		return false, nil
+	}
+
+	log.Info("Updating agent...", "current", currentVersion, "target", serverVersion)
+
+	selfPath, err := os.Executable()
+	if err != nil {
+		return false, fmt.Errorf("failed to determine executable path: %w", err)
+	}
+
+	tempPath := selfPath + ".update"
+
+	defer func() {
+		_ = os.Remove(tempPath)
+	}()
+
+	if err := apiClient.DownloadAgentBinary(context.Background(), runtime.GOARCH, tempPath); err != nil {
+		return false, fmt.Errorf("failed to download update: %w", err)
+	}
+
+	if err := os.Chmod(tempPath, 0o755); err != nil {
+		return false, fmt.Errorf("failed to set permissions on update: %w", err)
+	}
+
+	if err := verifyBinary(tempPath, serverVersion); err != nil {
+		return false, fmt.Errorf("update verification failed: %w", err)
+	}
+
+	if err := os.Rename(tempPath, selfPath); err != nil {
+		return false, fmt.Errorf("failed to replace binary (try --skip-update if this persists): %w", err)
+	}
+
+	log.Info("Agent binary updated", "version", serverVersion)
+
+	return true, nil
+}
+
+func verifyBinary(binaryPath, expectedVersion string) error {
+	cmd := exec.CommandContext(context.Background(), binaryPath, "version")
+
+	output, err := cmd.Output()
+	if err != nil {
+		return fmt.Errorf("binary failed to execute: %w", err)
+	}
+
+	got := strings.TrimSpace(string(output))
+	if got != expectedVersion {
+		return fmt.Errorf("version mismatch: expected %q, got %q", expectedVersion, got)
+	}
+
+	return nil
+}

agent/internal/features/wal/streamer.go

@@ -0,0 +1,204 @@
+package wal
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+
+	"databasus-agent/internal/config"
+	"databasus-agent/internal/features/api"
+)
+
+var uploadIdleTimeout = 5 * time.Minute
+
+const (
+	pollInterval  = 10 * time.Second
+	uploadTimeout = 5 * time.Minute
+)
+
+var segmentNameRegex = regexp.MustCompile(`^[0-9A-Fa-f]{24}$`)
+
+type Streamer struct {
+	cfg       *config.Config
+	apiClient *api.Client
+	log       *slog.Logger
+}
+
+func NewStreamer(cfg *config.Config, apiClient *api.Client, log *slog.Logger) *Streamer {
+	return &Streamer{
+		cfg:       cfg,
+		apiClient: apiClient,
+		log:       log,
+	}
+}
+
+func (s *Streamer) Run(ctx context.Context) {
+	s.log.Info("WAL streamer started", "pgWalDir", s.cfg.PgWalDir)
+
+	s.processQueue(ctx)
+
+	ticker := time.NewTicker(pollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			s.log.Info("WAL streamer stopping")
+			return
+		case <-ticker.C:
+			s.processQueue(ctx)
+		}
+	}
+}
+
+func (s *Streamer) processQueue(ctx context.Context) {
+	segments, err := s.listSegments()
+	if err != nil {
+		s.log.Error("Failed to list WAL segments", "error", err)
+		return
+	}
+
+	if len(segments) == 0 {
+		s.log.Info("No WAL segments pending", "dir", s.cfg.PgWalDir)
+		return
+	}
+
+	s.log.Info("WAL segments pending upload", "dir", s.cfg.PgWalDir, "count", len(segments))
+
+	for _, segmentName := range segments {
+		if ctx.Err() != nil {
+			return
+		}
+
+		if err := s.uploadSegment(ctx, segmentName); err != nil {
+			s.log.Error("Failed to upload WAL segment",
+				"segment", segmentName,
+				"error", err,
+			)
+			return
+		}
+	}
+}
+
+func (s *Streamer) listSegments() ([]string, error) {
+	entries, err := os.ReadDir(s.cfg.PgWalDir)
+	if err != nil {
+		return nil, fmt.Errorf("read wal dir: %w", err)
+	}
+
+	var segments []string
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+
+		name := entry.Name()
+
+		if strings.HasSuffix(name, ".tmp") {
+			continue
+		}
+
+		if !segmentNameRegex.MatchString(name) {
+			continue
+		}
+
+		segments = append(segments, name)
+	}
+
+	slices.Sort(segments)
+
+	return segments, nil
+}
+
+func (s *Streamer) uploadSegment(ctx context.Context, segmentName string) error {
+	filePath := filepath.Join(s.cfg.PgWalDir, segmentName)
+
+	pr, pw := io.Pipe()
+	defer func() { _ = pr.Close() }()
+
+	go s.compressAndStream(pw, filePath)
+
+	uploadCtx, timeoutCancel := context.WithTimeout(ctx, uploadTimeout)
+	defer timeoutCancel()
+
+	idleCtx, idleCancel := context.WithCancelCause(uploadCtx)
+	defer idleCancel(nil)
+
+	idleReader := api.NewIdleTimeoutReader(pr, uploadIdleTimeout, idleCancel)
+	defer idleReader.Stop()
+
+	s.log.Info("Uploading WAL segment", "segment", segmentName)
+
+	result, err := s.apiClient.UploadWalSegment(idleCtx, segmentName, idleReader)
+	if err != nil {
+		if cause := context.Cause(idleCtx); cause != nil {
+			return fmt.Errorf("upload WAL segment: %w", cause)
+		}
+
+		return err
+	}
+
+	if result.IsGapDetected {
+		s.log.Warn("WAL chain gap detected",
+			"segment", segmentName,
+			"expected", result.ExpectedSegmentName,
+			"received", result.ReceivedSegmentName,
+		)
+
+		return fmt.Errorf("gap detected for segment %s", segmentName)
+	}
+
+	s.log.Info("WAL segment uploaded", "segment", segmentName)
+
+	if *s.cfg.IsDeleteWalAfterUpload {
+		if err := os.Remove(filePath); err != nil {
+			s.log.Warn("Failed to delete uploaded WAL segment",
+				"segment", segmentName,
+				"error", err,
+			)
+		}
+	}
+
+	return nil
+}
+
+func (s *Streamer) compressAndStream(pw *io.PipeWriter, filePath string) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		_ = pw.CloseWithError(fmt.Errorf("open file: %w", err))
+		return
+	}
+	defer func() { _ = f.Close() }()
+
+	encoder, err := zstd.NewWriter(pw,
+		zstd.WithEncoderLevel(zstd.EncoderLevelFromZstd(5)),
+		zstd.WithEncoderCRC(true),
+	)
+	if err != nil {
+		_ = pw.CloseWithError(fmt.Errorf("create zstd encoder: %w", err))
+		return
+	}
+
+	if _, err := io.Copy(encoder, f); err != nil {
+		_ = encoder.Close()
+		_ = pw.CloseWithError(fmt.Errorf("compress: %w", err))
+		return
+	}
+
+	if err := encoder.Close(); err != nil {
+		_ = pw.CloseWithError(fmt.Errorf("close encoder: %w", err))
+		return
+	}
+
+	_ = pw.Close()
+}

agent/internal/features/wal/streamer_test.go

@@ -0,0 +1,393 @@
+package wal
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"databasus-agent/internal/config"
+	"databasus-agent/internal/features/api"
+	"databasus-agent/internal/logger"
+)
+
+func Test_UploadSegment_SingleSegment_ServerReceivesCorrectHeadersAndBody(t *testing.T) {
+	walDir := createTestWalDir(t)
+	segmentContent := []byte("test-wal-segment-data-for-upload")
+	writeTestSegment(t, walDir, "000000010000000100000001", segmentContent)
+
+	var receivedHeaders http.Header
+	var receivedBody []byte
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedHeaders = r.Header.Clone()
+
+		body, err := io.ReadAll(r.Body)
+		require.NoError(t, err)
+		receivedBody = body
+
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	require.NotNil(t, receivedHeaders)
+	assert.Equal(t, "test-token", receivedHeaders.Get("Authorization"))
+	assert.Equal(t, "application/octet-stream", receivedHeaders.Get("Content-Type"))
+	assert.Equal(t, "000000010000000100000001", receivedHeaders.Get("X-Wal-Segment-Name"))
+
+	decompressed := decompressZstd(t, receivedBody)
+	assert.Equal(t, segmentContent, decompressed)
+}
+
+func Test_UploadSegments_MultipleSegmentsOutOfOrder_UploadedInAscendingOrder(t *testing.T) {
+	walDir := createTestWalDir(t)
+	writeTestSegment(t, walDir, "000000010000000100000003", []byte("third"))
+	writeTestSegment(t, walDir, "000000010000000100000001", []byte("first"))
+	writeTestSegment(t, walDir, "000000010000000100000002", []byte("second"))
+
+	var mu sync.Mutex
+	var uploadOrder []string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		uploadOrder = append(uploadOrder, r.Header.Get("X-Wal-Segment-Name"))
+		mu.Unlock()
+
+		_, _ = io.ReadAll(r.Body)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	require.Len(t, uploadOrder, 3)
+	assert.Equal(t, "000000010000000100000001", uploadOrder[0])
+	assert.Equal(t, "000000010000000100000002", uploadOrder[1])
+	assert.Equal(t, "000000010000000100000003", uploadOrder[2])
+}
+
+func Test_UploadSegments_DirectoryHasTmpFiles_TmpFilesIgnored(t *testing.T) {
+	walDir := createTestWalDir(t)
+	writeTestSegment(t, walDir, "000000010000000100000001", []byte("real segment"))
+	writeTestSegment(t, walDir, "000000010000000100000002.tmp", []byte("partial copy"))
+
+	var mu sync.Mutex
+	var uploadedSegments []string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		uploadedSegments = append(uploadedSegments, r.Header.Get("X-Wal-Segment-Name"))
+		mu.Unlock()
+
+		_, _ = io.ReadAll(r.Body)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	require.Len(t, uploadedSegments, 1)
+	assert.Equal(t, "000000010000000100000001", uploadedSegments[0])
+}
+
+func Test_UploadSegment_DeleteEnabled_FileRemovedAfterUpload(t *testing.T) {
+	walDir := createTestWalDir(t)
+	segmentName := "000000010000000100000001"
+	writeTestSegment(t, walDir, segmentName, []byte("segment data"))
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.ReadAll(r.Body)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	isDeleteEnabled := true
+	cfg := createTestConfig(walDir, server.URL)
+	cfg.IsDeleteWalAfterUpload = &isDeleteEnabled
+	apiClient := api.NewClient(server.URL, cfg.Token, logger.GetLogger())
+	streamer := NewStreamer(cfg, apiClient, logger.GetLogger())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	_, err := os.Stat(filepath.Join(walDir, segmentName))
+	assert.True(t, os.IsNotExist(err), "segment file should be deleted after successful upload")
+}
+
+func Test_UploadSegment_DeleteDisabled_FileKeptAfterUpload(t *testing.T) {
+	walDir := createTestWalDir(t)
+	segmentName := "000000010000000100000001"
+	writeTestSegment(t, walDir, segmentName, []byte("segment data"))
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.ReadAll(r.Body)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	isDeleteDisabled := false
+	cfg := createTestConfig(walDir, server.URL)
+	cfg.IsDeleteWalAfterUpload = &isDeleteDisabled
+	apiClient := api.NewClient(server.URL, cfg.Token, logger.GetLogger())
+	streamer := NewStreamer(cfg, apiClient, logger.GetLogger())
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	_, err := os.Stat(filepath.Join(walDir, segmentName))
+	assert.NoError(t, err, "segment file should be kept when delete is disabled")
+}
+
+func Test_UploadSegment_ServerReturns500_FileKeptInQueue(t *testing.T) {
+	walDir := createTestWalDir(t)
+	segmentName := "000000010000000100000001"
+	writeTestSegment(t, walDir, segmentName, []byte("segment data"))
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.ReadAll(r.Body)
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte(`{"error":"internal server error"}`))
+	}))
+	defer server.Close()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	_, err := os.Stat(filepath.Join(walDir, segmentName))
+	assert.NoError(t, err, "segment file should remain in queue after server error")
+}
+
+func Test_ProcessQueue_EmptyDirectory_NoUploads(t *testing.T) {
+	walDir := createTestWalDir(t)
+
+	uploadCount := 0
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		uploadCount++
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	assert.Equal(t, 0, uploadCount, "no uploads should occur for empty directory")
+}
+
+func Test_Run_ContextCancelled_StopsImmediately(t *testing.T) {
+	walDir := createTestWalDir(t)
+
+	streamer := newTestStreamer(walDir, "http://localhost:0")
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	done := make(chan struct{})
+	go func() {
+		streamer.Run(ctx)
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("Run should have stopped immediately when context is already cancelled")
+	}
+}
+
+func Test_UploadSegment_ServerReturns409_FileNotDeleted(t *testing.T) {
+	walDir := createTestWalDir(t)
+	segmentName := "000000010000000100000005"
+	writeTestSegment(t, walDir, segmentName, []byte("gap segment"))
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.ReadAll(r.Body)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusConflict)
+
+		resp := map[string]string{
+			"error":               "gap_detected",
+			"expectedSegmentName": "000000010000000100000003",
+			"receivedSegmentName": segmentName,
+		}
+		_ = json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+
+	go streamer.Run(ctx)
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	_, err := os.Stat(filepath.Join(walDir, segmentName))
+	assert.NoError(t, err, "segment file should not be deleted on gap detection")
+}
+
+func Test_UploadSegment_WhenUploadStalls_FailsWithIdleTimeout(t *testing.T) {
+	walDir := createTestWalDir(t)
+
+	// Use incompressible random data to ensure TCP buffers fill up
+	segmentContent := make([]byte, 1024*1024)
+	_, err := rand.Read(segmentContent)
+	require.NoError(t, err)
+
+	writeTestSegment(t, walDir, "000000010000000100000001", segmentContent)
+
+	var requestReceived atomic.Bool
+	handlerDone := make(chan struct{})
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestReceived.Store(true)
+
+		// Read one byte then stall — simulates a network stall
+		buf := make([]byte, 1)
+		_, _ = r.Body.Read(buf)
+		<-handlerDone
+	}))
+	defer server.Close()
+	defer close(handlerDone)
+
+	origIdleTimeout := uploadIdleTimeout
+	uploadIdleTimeout = 200 * time.Millisecond
+	defer func() { uploadIdleTimeout = origIdleTimeout }()
+
+	streamer := newTestStreamer(walDir, server.URL)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+	defer cancel()
+
+	uploadErr := streamer.uploadSegment(ctx, "000000010000000100000001")
+
+	assert.Error(t, uploadErr, "upload should fail when stalled")
+	assert.True(t, requestReceived.Load(), "server should have received the request")
+	assert.Contains(t, uploadErr.Error(), "idle timeout", "error should mention idle timeout")
+
+	_, statErr := os.Stat(filepath.Join(walDir, "000000010000000100000001"))
+	assert.NoError(t, statErr, "segment file should remain in queue after idle timeout")
+}
+
+func newTestStreamer(walDir, serverURL string) *Streamer {
+	cfg := createTestConfig(walDir, serverURL)
+	apiClient := api.NewClient(serverURL, cfg.Token, logger.GetLogger())
+
+	return NewStreamer(cfg, apiClient, logger.GetLogger())
+}
+
+func createTestWalDir(t *testing.T) string {
+	t.Helper()
+
+	baseDir := filepath.Join(".", ".test-tmp")
+	if err := os.MkdirAll(baseDir, 0o755); err != nil {
+		t.Fatalf("failed to create base test dir: %v", err)
+	}
+
+	dir, err := os.MkdirTemp(baseDir, t.Name()+"-*")
+	if err != nil {
+		t.Fatalf("failed to create test wal dir: %v", err)
+	}
+
+	t.Cleanup(func() {
+		_ = os.RemoveAll(dir)
+	})
+
+	return dir
+}
+
+func writeTestSegment(t *testing.T, dir, name string, content []byte) {
+	t.Helper()
+
+	if err := os.WriteFile(filepath.Join(dir, name), content, 0o644); err != nil {
+		t.Fatalf("failed to write test segment %s: %v", name, err)
+	}
+}
+
+func createTestConfig(walDir, serverURL string) *config.Config {
+	isDeleteEnabled := true
+
+	return &config.Config{
+		DatabasusHost:          serverURL,
+		DbID:                   "test-db-id",
+		Token:                  "test-token",
+		PgWalDir:               walDir,
+		IsDeleteWalAfterUpload: &isDeleteEnabled,
+	}
+}
+
+func decompressZstd(t *testing.T, data []byte) []byte {
+	t.Helper()
+
+	decoder, err := zstd.NewReader(nil)
+	require.NoError(t, err)
+	defer decoder.Close()
+
+	decoded, err := decoder.DecodeAll(data, nil)
+	require.NoError(t, err)
+
+	return decoded
+}

agent/internal/logger/logger.go

@@ -0,0 +1,115 @@
+package logger
+
+import (
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"sync"
+	"time"
+)
+
+const (
+	logFileName    = "databasus.log"
+	oldLogFileName = "databasus.log.old"
+	maxLogFileSize = 5 * 1024 * 1024 // 5MB
+)
+
+type rotatingWriter struct {
+	mu          sync.Mutex
+	file        *os.File
+	currentSize int64
+	maxSize     int64
+	logPath     string
+	oldLogPath  string
+}
+
+func (w *rotatingWriter) Write(p []byte) (int, error) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+
+	if w.currentSize+int64(len(p)) > w.maxSize {
+		if err := w.rotate(); err != nil {
+			return 0, fmt.Errorf("failed to rotate log file: %w", err)
+		}
+	}
+
+	n, err := w.file.Write(p)
+	w.currentSize += int64(n)
+
+	return n, err
+}
+
+func (w *rotatingWriter) rotate() error {
+	if err := w.file.Close(); err != nil {
+		return fmt.Errorf("failed to close %s: %w", w.logPath, err)
+	}
+
+	if err := os.Remove(w.oldLogPath); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("failed to remove %s: %w", w.oldLogPath, err)
+	}
+
+	if err := os.Rename(w.logPath, w.oldLogPath); err != nil {
+		return fmt.Errorf("failed to rename %s to %s: %w", w.logPath, w.oldLogPath, err)
+	}
+
+	f, err := os.OpenFile(w.logPath, os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		return fmt.Errorf("failed to create new %s: %w", w.logPath, err)
+	}
+
+	w.file = f
+	w.currentSize = 0
+
+	return nil
+}
+
+var loggerInstance *slog.Logger
+
+var initLogger = sync.OnceFunc(initialize)
+
+func GetLogger() *slog.Logger {
+	initLogger()
+	return loggerInstance
+}
+
+func initialize() {
+	writer := buildWriter()
+
+	loggerInstance = slog.New(slog.NewTextHandler(writer, &slog.HandlerOptions{
+		Level: slog.LevelInfo,
+		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
+			if a.Key == slog.TimeKey {
+				a.Value = slog.StringValue(time.Now().Format("2006/01/02 15:04:05"))
+			}
+			if a.Key == slog.LevelKey {
+				return slog.Attr{}
+			}
+
+			return a
+		},
+	}))
+}
+
+func buildWriter() io.Writer {
+	f, err := os.OpenFile(logFileName, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Warning: failed to open %s for logging: %v\n", logFileName, err)
+		return os.Stdout
+	}
+
+	var currentSize int64
+	if info, err := f.Stat(); err == nil {
+		currentSize = info.Size()
+	}
+
+	rw := &rotatingWriter{
+		file:        f,
+		currentSize: currentSize,
+		maxSize:     maxLogFileSize,
+		logPath:     logFileName,
+		oldLogPath:  oldLogFileName,
+	}
+
+	return io.MultiWriter(os.Stdout, rw)
+}

agent/internal/logger/logger_test.go

@@ -0,0 +1,128 @@
+package logger
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_Write_DataWrittenToFile(t *testing.T) {
+	rw, logPath, _ := setupRotatingWriter(t, 1024)
+
+	data := []byte("hello world\n")
+	n, err := rw.Write(data)
+
+	require.NoError(t, err)
+	assert.Equal(t, len(data), n)
+	assert.Equal(t, int64(len(data)), rw.currentSize)
+
+	content, err := os.ReadFile(logPath)
+	require.NoError(t, err)
+	assert.Equal(t, string(data), string(content))
+}
+
+func Test_Write_WhenLimitExceeded_FileRotated(t *testing.T) {
+	rw, logPath, oldLogPath := setupRotatingWriter(t, 100)
+
+	firstData := []byte(strings.Repeat("A", 80))
+	_, err := rw.Write(firstData)
+	require.NoError(t, err)
+
+	secondData := []byte(strings.Repeat("B", 30))
+	_, err = rw.Write(secondData)
+	require.NoError(t, err)
+
+	oldContent, err := os.ReadFile(oldLogPath)
+	require.NoError(t, err)
+	assert.Equal(t, string(firstData), string(oldContent))
+
+	newContent, err := os.ReadFile(logPath)
+	require.NoError(t, err)
+	assert.Equal(t, string(secondData), string(newContent))
+
+	assert.Equal(t, int64(len(secondData)), rw.currentSize)
+}
+
+func Test_Write_WhenOldFileExists_OldFileReplaced(t *testing.T) {
+	rw, _, oldLogPath := setupRotatingWriter(t, 100)
+
+	require.NoError(t, os.WriteFile(oldLogPath, []byte("stale data"), 0o644))
+
+	_, err := rw.Write([]byte(strings.Repeat("A", 80)))
+	require.NoError(t, err)
+
+	_, err = rw.Write([]byte(strings.Repeat("B", 30)))
+	require.NoError(t, err)
+
+	oldContent, err := os.ReadFile(oldLogPath)
+	require.NoError(t, err)
+	assert.Equal(t, strings.Repeat("A", 80), string(oldContent))
+}
+
+func Test_Write_MultipleSmallWrites_CurrentSizeAccumulated(t *testing.T) {
+	rw, _, _ := setupRotatingWriter(t, 1024)
+
+	var totalWritten int64
+	for range 10 {
+		data := []byte("line\n")
+		n, err := rw.Write(data)
+		require.NoError(t, err)
+
+		totalWritten += int64(n)
+	}
+
+	assert.Equal(t, totalWritten, rw.currentSize)
+	assert.Equal(t, int64(50), rw.currentSize)
+}
+
+func Test_Write_ExactlyAtBoundary_NoRotationUntilNextByte(t *testing.T) {
+	rw, logPath, oldLogPath := setupRotatingWriter(t, 100)
+
+	exactData := []byte(strings.Repeat("X", 100))
+	_, err := rw.Write(exactData)
+	require.NoError(t, err)
+
+	_, err = os.Stat(oldLogPath)
+	assert.True(t, os.IsNotExist(err), ".old file should not exist yet")
+
+	content, err := os.ReadFile(logPath)
+	require.NoError(t, err)
+	assert.Equal(t, string(exactData), string(content))
+
+	_, err = rw.Write([]byte("Z"))
+	require.NoError(t, err)
+
+	_, err = os.Stat(oldLogPath)
+	assert.NoError(t, err, ".old file should exist after exceeding limit")
+
+	assert.Equal(t, int64(1), rw.currentSize)
+}
+
+func setupRotatingWriter(t *testing.T, maxSize int64) (*rotatingWriter, string, string) {
+	t.Helper()
+
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "test.log")
+	oldLogPath := filepath.Join(dir, "test.log.old")
+
+	f, err := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY, 0o644)
+	require.NoError(t, err)
+
+	rw := &rotatingWriter{
+		file:        f,
+		currentSize: 0,
+		maxSize:     maxSize,
+		logPath:     logPath,
+		oldLogPath:  oldLogPath,
+	}
+
+	t.Cleanup(func() {
+		rw.file.Close()
+	})
+
+	return rw, logPath, oldLogPath
+}

assets/logo-square.svg

@@ -0,0 +1,12 @@
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_287_1020)">
+<path d="M50.1522 115.189C50.1522 121.189 57.1564 121.193 59 118C60.1547 116 61 114 61 108C61 102 58.1044 96.9536 55.3194 91.5175C54.6026 90.1184 53.8323 88.6149 53.0128 86.9234C51.6073 84.0225 49.8868 81.3469 47.3885 79.2139C47.0053 78.8867 46.8935 78.0093 46.9624 77.422C47.2351 75.1036 47.5317 72.7876 47.8283 70.4718C48.3186 66.6436 48.8088 62.8156 49.1909 58.9766C49.459 56.2872 49.4542 53.5119 49.1156 50.8329C48.3833 45.0344 45.1292 40.7783 40.1351 37.9114C38.6818 37.0771 38.2533 36.1455 38.4347 34.5853C38.9402 30.2473 40.6551 26.3306 42.8342 22.6642C44.8356 19.297 47.1037 16.0858 49.3676 12.8804C49.6576 12.4699 49.9475 12.0594 50.2367 11.6488C50.6069 11.1231 51.5231 10.7245 52.1971 10.7075C60.4129 10.5017 68.6303 10.3648 76.8477 10.2636C77.4123 10.2563 78.1584 10.5196 78.5221 10.9246C83.6483 16.634 88.2284 22.712 90.9778 29.9784C91.1658 30.4758 91.3221 30.9869 91.4655 31.4997C92.4976 35.1683 92.4804 35.1803 89.5401 37.2499L89.4071 37.3436C83.8702 41.2433 81.8458 46.8198 82.0921 53.349C82.374 60.8552 84.0622 68.1313 85.9869 75.3539C86.3782 76.8218 86.6318 77.9073 85.2206 79.2609C82.3951 81.9698 81.2196 85.6872 80.6575 89.4687C80.0724 93.4081 79.599 97.3637 79.1254 101.32C78.8627 103.515 78.8497 105.368 78.318 107.904C76.2819 117.611 71 128 63 128H50.1522C45 128 41 123.189 41 115.189H50.1522Z" fill="#155DFC"/>
+<path d="M46.2429 6.56033C43.3387 11.1 40.3642 15.4031 37.7614 19.9209C35.413 23.9964 33.8487 28.4226 33.0913 33.1211C32.0998 39.2728 33.694 44.7189 38.0765 48.9775C41.6846 52.4835 42.6153 56.4472 42.152 61.1675C41.1426 71.4587 39.1174 81.5401 36.2052 91.4522C36.1769 91.5477 36.0886 91.6255 35.8974 91.8977C34.1517 91.3525 32.3161 90.8446 30.5266 90.2095C5.53011 81.3376 -12.7225 64.953 -24.1842 41.0298C-25.175 38.9625 -26.079 36.8498 -26.9263 34.7202C-27.0875 34.3151 -26.9749 33.5294 -26.6785 33.2531C-17.1479 24.3723 -7.64007 15.4647 2.00468 6.70938C8.64568 0.681612 16.5812 -1.21558 25.2457 0.739942C31.9378 2.24992 38.5131 4.27834 45.1363 6.09048C45.5843 6.2128 45.9998 6.45502 46.2429 6.56033Z" fill="#155DFC"/>
+<path d="M96.9586 89.3257C95.5888 84.7456 94.0796 80.4011 93.0111 75.9514C91.6065 70.0978 90.4683 64.1753 89.3739 58.2529C88.755 54.9056 89.3998 51.8176 91.89 49.2108C98.2669 42.5358 98.3933 34.7971 95.3312 26.7037C92.7471 19.8739 88.593 13.9904 83.7026 8.60904C83.1298 7.9788 82.5693 7.33641 81.918 6.60491C82.2874 6.40239 82.5709 6.18773 82.8909 6.07999C90.1281 3.64085 97.4495 1.54842 105.041 0.488845C112.781 -0.591795 119.379 1.81818 125.045 6.97592C130.017 11.5018 134.805 16.2327 139.812 20.7188C143.822 24.3115 148.013 27.7066 152.19 31.1073C152.945 31.7205 153.137 32.2154 152.913 33.1041C149.059 48.4591 141.312 61.4883 129.457 71.9877C120.113 80.2626 109.35 85.9785 96.9586 89.3265V89.3257Z" fill="#155DFC"/>
+</g>
+<defs>
+<clipPath id="clip0_287_1020">
+<rect width="128" height="128" rx="6" fill="white"/>
+</clipPath>
+</defs>
+</svg>

assets/tools/README.md

@@ -0,0 +1,17 @@
+We keep binaries here to speed up CI \ CD tasks and building.
+
+Docker image needs:
+- PostgreSQL client tools (versions 12-18)
+- MySQL client tools (versions 5.7, 8.0, 8.4, 9)
+- MariaDB client tools (versions 10.6, 12.1)
+- MongoDB Database Tools (latest)
+
+For the most of tools, we need a couple of binaries for each version. However, if we download them on each run, it will download a couple of GBs each time.
+
+So, for speed up we keep only required executables (like pg_dump, mysqldump, mariadb-dump, mongodump, etc.).
+
+It takes:
+- ~ 100MB for ARM
+- ~ 100MB for x64
+
+Instead of GBs. See Dockefile for usage details.