SDK

JavaScript/TypeScript SDK для Node.js, Bun и Deno.

Установка

bash

npm install dbsend
# или
bun add dbsend
# или
yarn add dbsend

⚠️

Требует Node.js 18+ или Bun 1.0+. Для Deno используйте npm: спецификатор npm:dbsend.

Инициализация

typescript

import { dbsend } from 'dbsend'

const client = new dbsend({
  apiKey: process.env.DBSEND_API_KEY!,  // обязательно
  apiUrl: 'https://api.dbsend.ru/v1',  // опционально, по умолчанию prod
})

Параметр	Тип	Описание
apiKey	string	API ключ вида `sqv_pk_...`. Получите в дашборде → API Ключи
apiUrl	string?	Базовый URL API. По умолчанию `https://api.dbsend.ru/v1`

client.backup()

Создаёт резервную копию файла базы данных. Автоматически выбирает простую или chunked загрузку в зависимости от размера файла (порог: 50 MB).

typescript

const version = await client.backup('./data.db', {
  engine: 'sqlite',           // тип БД
  label: 'pre-migration',     // метка (опционально)
  metadata: {                 // доп. данные (опционально)
    commit: 'abc123',
    environment: 'production'
  }
})

console.log(version.versionNumber)  // 1
console.log(version.id)             // "uuid"
console.log(version.checksumSha256) // sha256 оригинала

Параметр engine:

sqlite

SQLite файл (.db, .sqlite)

duckdb

DuckDB файл (.ddb)

postgresql_dump

pg_dump output

mysql_dump

mysqldump output

generic_file

Любой файл

BackupResult

typescript

interface BackupResult {
  id: string              // UUID версии
  versionNumber: number   // порядковый номер
  size: number            // размер оригинала в байтах
  checksumSha256: string  // SHA-256 от оригинала
  createdAt: string       // ISO datetime
}

client.restore()

Скачивает и сохраняет бэкап из указанной версии. При включённом шифровании — расшифровывает автоматически.

typescript

const result = await client.restore(
  '4865db6a-5281-44f6-b627-a8d41212955b',  // ID версии (backupVersionId)
  './restored.db'                           // путь для сохранения
)

console.log(result.success)   // true
console.log(result.version)   // 3
console.log(result.filename)  // "data.db"

client.schedule()

Запускает автоматические бэкапы по cron-расписанию. Работает пока процесс Node.js/Bun активен. Требует node-cron.

typescript

const task = client.schedule('./data.db', {
  cron: '0 * * * *',   // каждый час (cron-выражение)
  engine: 'sqlite',
  onSuccess: (version) => {
    console.log(`✅ Backup v${version.versionNumber} saved`)
  },
  onError: (error) => {
    console.error('❌ Backup failed:', error.message)
  }
})

// Остановить расписание
task.stop()

Примеры cron-выражений:

0 * * * *	каждый час
0 /6 * *	каждые 6 часов
0 2 * * *	каждый день в 02:00
0 2 * * 0	каждое воскресенье в 02:00
/5 * * *	каждые 5 минут (тариф Команда+)

Примеры интеграций

Express.js / Fastify

typescript

import { dbsend } from 'dbsend'

const backup = new dbsend({ apiKey: process.env.DBSEND_API_KEY! })

// Запуск при старте сервера
backup.schedule('./prisma/dev.db', {
  cron: '0 */2 * * *',
  engine: 'sqlite',
  onSuccess: (v) => console.log(`Backup v${v.versionNumber}`),
  onError: (err) => console.error('Backup error:', err.message),
})

Бэкап перед миграцией

typescript

import { dbsend } from 'dbsend'

async function runMigration() {
  const client = new dbsend({ apiKey: process.env.DBSEND_API_KEY! })

  // Снимок перед изменением схемы
  const snapshot = await client.backup('./data.db', {
    label: 'pre-migration',
    metadata: { migration: '0042_add_users_table' }
  })

  try {
    await executeMigration()
    console.log('Migration done ✅')
  } catch (err) {
    // Откат к снимку
    await client.restore(snapshot.id, './data.db')
    console.log('Rolled back to v' + snapshot.versionNumber)
    throw err
  }
}

GitHub Actions CI/CD

yaml

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Backup production DB
        run: npx dbsend backup ./prod.db --api-key ${{ secrets.DBSEND_API_KEY }} --label "deploy-${{ github.sha }}"
      
      - name: Deploy application
        run: ./deploy.sh

Внутренняя логика загрузки

read file → sha256(raw) → gzip(raw)

↓ если < 50 MB

POST /backups/upload (multipart)

↓ если > 50 MB

init → upload chunks (10 MB each) → complete

encrypt(AES-256-GCM) → S3 storage