{"id":29086644,"url":"https://github.com/stacksjs/backupx","last_synced_at":"2025-06-28T01:01:40.989Z","repository":{"id":298053395,"uuid":"998700518","full_name":"stacksjs/backupx","owner":"stacksjs","description":"💾 Comprehensive \u0026 performant database and file backup solution.","archived":false,"fork":false,"pushed_at":"2025-06-15T07:58:14.000Z","size":981,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T09:23:45.342Z","etag":null,"topics":["backups","cli","database","files","library","typescript"],"latest_commit_sha":null,"homepage":"https://backupx.netlify.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacksjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["stacksjs","chrisbbreuer"],"open_collective":"stacksjs"}},"created_at":"2025-06-09T05:37:02.000Z","updated_at":"2025-06-09T20:33:30.000Z","dependencies_parsed_at":"2025-06-09T06:42:28.233Z","dependency_job_id":null,"html_url":"https://github.com/stacksjs/backupx","commit_stats":null,"previous_names":["stacksjs/ts-backups","stacksjs/backupx"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/stacksjs/backupx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fbackupx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fbackupx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fbackupx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fbackupx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacksjs","download_url":"https://codeload.github.com/stacksjs/backupx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fbackupx/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261540690,"owners_count":23174220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backups","cli","database","files","library","typescript"],"created_at":"2025-06-28T01:01:00.382Z","updated_at":"2025-06-28T01:01:40.830Z","avatar_url":"https://github.com/stacksjs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/stacksjs","https://github.com/sponsors/chrisbbreuer","https://opencollective.com/stacksjs"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\".github/art/cover.jpg\" alt=\"Social Card of this repo\"\u003e\u003c/p\u003e\n\n[![npm version][npm-version-src]][npm-version-href]\n[![GitHub Actions][github-actions-src]][github-actions-href]\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\u003c!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] --\u003e\n\u003c!-- [![Codecov][codecov-src]][codecov-href] --\u003e\n\n# backupx\n\n\u003e A comprehensive TypeScript backup library for databases, files, and directories.\n\n## Features\n\n- 🗄️ **Multi-Database Support** - SQLite, PostgreSQL, and MySQL (via Bun's native drivers)\n- 📁 **File \u0026 Directory Backups** - Backup individual files or entire directories with filtering\n- 🗜️ **Compression Support** - Optional gzip compression for all backup types\n- 🎯 **Advanced Filtering** - Include/exclude patterns with glob support for directory backups\n- 🔄 **Retention Policies** - Configure backup retention by count or age\n- 📁 **Flexible Output** - Customizable backup file naming and output directories\n- ⚡ **Performance** - Built with Bun for fast execution\n- 🧪 **Thoroughly Tested** - Comprehensive test suite with 95%+ coverage\n- 🔧 **TypeScript First** - Fully typed APIs for better developer experience\n- 📦 **CLI \u0026 Programmatic** - Use as a library or command-line tool\n\n## Installation\n\n```bash\n# Using Bun (recommended)\nbun add backupx\n```\n\n## Quick Start\n\n### Programmatic Usage\n\n```ts\nimport { createBackup } from 'backupx'\n\nconst config = {\n  verbose: true,\n  outputPath: './backups',\n  databases: [\n    {\n      type: 'sqlite',\n      name: 'my-app-db',\n      path: './data/app.sqlite'\n    },\n    {\n      type: 'postgresql',\n      name: 'users-db',\n      connection: 'postgres://user:pass@localhost:5432/myapp'\n    }\n  ],\n  files: [\n    {\n      name: 'uploads',\n      path: './public/uploads', // Automatically detected as directory\n      compress: true,\n      include: ['*.jpg', '*.png', '*.pdf'],\n      exclude: ['temp/*']\n    },\n    {\n      name: 'config',\n      path: './config/app.json', // Automatically detected as file\n      compress: false\n    }\n  ],\n  retention: {\n    count: 5, // Keep 5 most recent backups\n    maxAge: 30 // Delete backups older than 30 days\n  }\n}\n\nconst summary = await createBackup(config)\nconsole.log(`✅ ${summary.successCount} backups completed`)\nconsole.log(`📊 Database backups: ${summary.databaseBackups.length}`)\nconsole.log(`📁 File backups: ${summary.fileBackups.length}`)\n```\n\n### CLI Usage\n\n```bash\n# Create backups.config.ts file first\n./backups start --verbose\n```\n\n## Testing\n\nThe library includes a comprehensive test suite covering:\n\n- ✅ **Type Safety** - TypeScript configuration validation\n- ✅ **SQLite Backups** - Schema extraction, data export, special characters\n- ✅ **File Backups** - Individual file backup with compression and metadata preservation\n- ✅ **Directory Backups** - Full directory backup with glob filtering and size limits\n- ✅ **Backup Manager** - Multi-database and file coordination, error handling\n- ✅ **Retention Policies** - Count-based and age-based cleanup for all backup types\n- ✅ **Error Scenarios** - Database connection failures, permission issues, missing files\n- ✅ **CLI Integration** - Command-line interface functionality\n\n### Running Tests\n\n```bash\n# Run all tests\nbun test\n\n# Run tests in watch mode\nbun run test:watch\n\n# Run with coverage\nbun run test:coverage\n\n# Run specific test files\nbun test test/sqlite.test.ts\nbun test test/backup-manager.test.ts\n```\n\n### Test Structure\n\n```\ntest/\n├── types.test.ts          # Type definitions and configurations\n├── config.test.ts         # Default configuration validation\n├── sqlite.test.ts         # SQLite backup functionality\n├── file.test.ts           # Individual file backup functionality\n├── directory.test.ts      # Directory backup with filtering\n├── backup-manager.test.ts # Multi-database and file coordination\n└── index.test.ts          # Integration tests and exports\n```\n\n## Configuration\n\nCreate a `backups.config.ts` file:\n\n```ts\nimport { BackupConfig } from 'backupx'\n\nexport const config: BackupConfig = {\n  verbose: true,\n  outputPath: './backups',\n  retention: {\n    count: 10, // Keep 10 most recent backups\n    maxAge: 90 // Delete backups older than 90 days\n  },\n  databases: [\n    // SQLite\n    {\n      type: 'sqlite',\n      name: 'app-database',\n      path: './data/app.sqlite',\n      compress: true\n    },\n\n    // PostgreSQL\n    {\n      type: 'postgresql',\n      name: 'user-data',\n      connection: {\n        hostname: 'localhost',\n        port: 5432,\n        database: 'myapp',\n        username: 'postgres',\n        password: 'secret'\n      },\n      tables: ['users', 'orders'], // Specific tables only\n      includeSchema: true,\n      includeData: true\n    },\n\n    // MySQL (when Bun adds support)\n    {\n      type: 'mysql',\n      name: 'analytics',\n      connection: 'mysql://user:pass@localhost:3306/analytics',\n      excludeTables: ['temp_logs', 'cache']\n    }\n  ],\n\n  files: [\n    // Directory backups (automatically detected from path)\n    {\n      name: 'app-uploads',\n      path: './public/uploads',\n      compress: true,\n      include: ['*.jpg', '*.png', '*.pdf', '*.doc*'],\n      exclude: ['temp/*', '*.tmp'],\n      maxFileSize: 50 * 1024 * 1024, // 50MB max file size\n      preserveMetadata: true,\n      followSymlinks: false\n    },\n\n    {\n      name: 'user-data',\n      path: './data/users',\n      compress: false,\n      exclude: ['*.cache', 'temp/*', '*.log'],\n      preserveMetadata: true\n    },\n\n    // Individual file backups (automatically detected from path)\n    {\n      name: 'app-config',\n      path: './config/app.json',\n      compress: false,\n      preserveMetadata: true\n    },\n\n    {\n      name: 'env-file',\n      path: './.env.production',\n      compress: true,\n      filename: 'production-env' // Custom filename\n    }\n  ]\n}\n```\n\n## Backup Support\n\n### Database Backups\n\n#### SQLite ✅ Fully Supported\n- Native `bun:sqlite` driver\n- Complete schema export (tables, indexes, triggers, views)\n- Efficient data export with proper escaping\n- Binary data support (BLOB fields)\n\n#### PostgreSQL ✅ Fully Supported\n- Native Bun SQL class\n- Connection strings or configuration objects\n- Schema extraction and data export\n- Batch processing for large datasets\n\n#### MySQL ⏳ Coming Soon\n- Waiting for Bun's native MySQL driver\n- Placeholder implementation ready\n\n### File \u0026 Directory Backups\n\n#### Directory Backups ✅ Fully Supported\n- Recursive directory scanning with configurable depth\n- Advanced glob pattern filtering (include/exclude)\n- File size limits and symbolic link handling\n- Metadata preservation (timestamps, permissions)\n- Custom archive format with compression support\n\n#### Individual File Backups ✅ Fully Supported\n- Single file backup with original extension preservation\n- Optional gzip compression for any file type\n- Metadata preservation in separate `.meta` files\n- Binary and text file support\n- Custom filename and output path configuration\n\n## API Reference\n\n### `createBackup(config: BackupConfig): Promise\u003cBackupSummary\u003e`\n\nCreates backups for all configured databases.\n\n### `BackupManager`\n\n```ts\nconst manager = new BackupManager(config)\nconst summary = await manager.createBackup()\n```\n\n### Database-Specific Functions\n\n```ts\nimport { backupPostgreSQL, backupSQLite } from 'backupx'\n\nconst result = await backupSQLite(sqliteConfig, './output')\nconst result = await backupPostgreSQL(pgConfig, './output')\n```\n\n## Changelog\n\nPlease see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.\n\n## Contributing\n\nPlease see the [Contributing Guide](https://github.com/stacksjs/contributing) for details.\n\n## Community\n\nFor help, discussion about best practices, or any other conversation that would benefit from being searchable:\n\n[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)\n\nFor casual chit-chat with others using this package:\n\n[Join the Stacks Discord Server](https://discord.gg/stacksjs)\n\n## Postcardware\n\n“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.\n\nOur address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎\n\n## Sponsors\n\nWe would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.\n\n- [JetBrains](https://www.jetbrains.com/)\n- [The Solana Foundation](https://solana.com/)\n\n## License\n\nThe MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.\n\nMade with 💙\n\n\u003c!-- Badges --\u003e\n[npm-version-src]: https://img.shields.io/npm/v/backupx?style=flat-square\n[npm-version-href]: https://npmjs.com/package/backupx\n[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/backupx/ci.yml?style=flat-square\u0026branch=main\n[github-actions-href]: https://github.com/stacksjs/backupx/actions?query=workflow%3Aci\n\n\u003c!-- [codecov-src]: https://img.shields.io/codecov/c/gh/stacksjs/backupx/main?style=flat-square\n[codecov-href]: https://codecov.io/gh/stacksjs/backupx --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacksjs%2Fbackupx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacksjs%2Fbackupx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacksjs%2Fbackupx/lists"}