pbdeploy v0.0.1

A unified developer toolkit that combines CLI tools for managing PocketBase projects through pbdeploy with a PocketBase-compatible client facade.

PocketBase Compatibility: 0.26.3

Quick Start

Installation

npm install -g pbdeploy

CLI Usage

# Authenticate with pbdeploy
pbdeploy login

# Initialize a new project
pbdeploy init

# Sync project from pbdeploy
pbdeploy sync

Client Usage

// Simple usage with pre-configured client
const pb = require('./pbdeploy/pbdeploy.js');

// Quick authentication
const user = await pb.auth('[email protected]', 'password');

// Use collections
const records = await pb.collection('posts').getList(1, 50);

// Call cloud functions (auto-generated from deployed functions)
const result = await pb.functions.myFunctionName({ param: 'value' });

// Or use the lower-level API
const result2 = await pb.pbdeploy.extras.functions.call('myFunctionName', data);

// Access project info
console.log(pb.project.name);

CLI Tools

Commands

| Command | Description | Network Target | Interaction | | ------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------- | ---------------------------- | | pbdeploy login | Authenticates with pbdeploy's /api/login and stores a local session token | pbdeploy server | Prompts for email + password | | pbdeploy init | Interactive project setup: choose or create an app, then scaffold required folders and config files | pbdeploy /api/apps | Prompts to create/select | | pbdeploy sync | Pulls the latest app definition from pbdeploy, shows a dry-run diff, confirms before overwrite/delete | pbdeploy /api/apps/:id/definition | Prompts before apply | | pbdeploy migrate apply | Apply pending migrations (auto-generates from schema comparison if needed) | pbdeploy /api/apps/:id/schema | Applies schema changes | | pbdeploy migrate status | Show migration status and pending changes | pbdeploy /api/apps/:id/schema | Read-only | | pbdeploy migrate generate | Generate migrations by comparing online schema with local schema | pbdeploy /api/apps/:id/schema | Generates migration files |

Generated Structure

your-project/
├── pbdeploy.json          # Project configuration
└── pbdeploy/
    ├── schema/            # Database schema files
    ├── functions/         # Cloud function files
    ├── migrations/        # Database migration files
    ├── endpoints/         # LLM-friendly API documentation
    └── pbdeploy.js        # Ready-to-use PocketBase client

pbdeploy.json Configuration

{
  "name": "<app-name>",
  "appId": "<appId>",
  "pocketbase": {
    "url": "<pbUrl>"
  },
  "schema": {
    "dir": "pbdeploy/schema"
  },
  "functions": {
    "dir": "pbdeploy/functions"
  },
  "migrations": {
    "dir": "pbdeploy/migrations"
  }
}

Safety Features

• Requires prior pbdeploy login
• Sync is read-only (server → local)
• Always shows diff; asks before overwrite/delete
• Uses git for version control (no backup files)
• Never writes secrets into repo files

Client Facade

Purpose

Provide a drop-in replacement for the official PocketBase 0.26.3 JavaScript client.

Behavior

• Pure pass-through: Delegates all calls to the real SDK
• Identical API surface, responses, and error objects
• No pbdeploy-specific logic yet — ready for future extensions

Public Surface (matching PB 0.26.3)

// Create client
createClient(baseUrl, options?)

// Collection operations
.collection(name) → {
  getList, getOne, create, update, delete, subscribe, unsubscribe
}

// Authentication store
.authStore → {
  isValid, model, token, clear, onChange
}

// File URLs
.getFileUrl(record, fileName, opts?)

// Realtime methods
subscribe, unsubscribe

pbdeploy-specific Features

// Call cloud functions (after pbdeploy sync)
const result = await pb.functions.myFunctionName(data);
// Convenience wrapper for deployed functions

const result2 = await pb.pbdeploy.extras.functions.call('myFunctionName', data);
// Lower-level API for function calls

// Access project metadata
console.log(pb.project.name);    // Project name
console.log(pb.project.appId);   // App ID
console.log(pb.project.baseUrl); // PocketBase URL

// Collection name constants (type-safe references)
pb.collection(pb.collections.users);
pb.collection(pb.collections.posts);

// Access API documentation
const apiDocs = pb.api;

CLI Command Details

pbdeploy login

Authenticates with the pbdeploy service and stores a session token locally.

pbdeploy login
# Interactive prompts for email and password

pbdeploy login --email [email protected] --password mypassword
# Non-interactive with credentials

pbdeploy init

Sets up a new pbdeploy project directory with the required structure.

pbdeploy init
# Interactive setup

pbdeploy init --name myapp
# Skip name prompt

pbdeploy sync

Pulls the latest app definition from pbdeploy and updates local files.

pbdeploy sync
# Interactive with diff preview and confirmation

pbdeploy sync --yes
# Skip confirmation prompts

pbdeploy sync --dry-run
# Show diff without applying changes

pbdeploy migrate

Manage database migrations for schema changes.

# Check migration status
pbdeploy migrate status

# Generate migrations from schema changes
pbdeploy migrate generate

# Apply pending migrations
pbdeploy migrate apply

# Apply with options
pbdeploy migrate apply --dry-run
# Preview what would be applied

pbdeploy migrate apply --no-rollback-on-error
# Don't rollback on error

# Rollback migrations
pbdeploy migrate rollback
# Rollback last migration

pbdeploy migrate rollback --count 3
# Rollback last 3 migrations

Migration Workflow:

1. Make changes to your local schema files in pbdeploy/schema/
2. Run pbdeploy migrate generate to create migration files
3. Review the generated migrations in pbdeploy/migrations/
4. Run pbdeploy migrate apply to apply changes to the remote database
5. Migrations are tracked to prevent double-application

## Advanced Usage

### Programmatic CLI Usage

```javascript
const { config, auth, backup } = require("pbdeploy");

// Load project configuration
const projectConfig = await config.loadProjectConfig();

// Check authentication status
const isAuthed = await config.isAuthenticated();

// Create backups
await backup.createBackup(["schema", "functions"], process.cwd(), "manual");

Realtime Enhancements

const { createClient, RealtimeService } = require("pbdeploy");

const pb = createClient("http://127.0.0.1:8090");

// Create subscription manager
const manager = RealtimeService.createSubscriptionManager(pb);

// Subscribe with automatic tracking
const subId = manager.subscribe("posts", (event) => {
  console.log("Post event:", event);
});

// Unsubscribe by ID
manager.unsubscribeById(subId);

// Subscribe with retry logic
const unsubscribe = RealtimeService.subscribeWithRetry(
  pb,
  "comments",
  (event) => console.log("Comment:", event),
  { maxRetries: 3, retryDelay: 1000 }
);

Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Lint code
npm run lint

# Test new structure
node examples/test-new-structure.js

Dependencies

Runtime Dependencies

• pocketbase: ^0.26.3 (official PocketBase SDK)
• axios: HTTP client for API calls
• commander: CLI framework
• inquirer: Interactive prompts
• chalk: Terminal colors
• fs-extra: Enhanced file system operations
• diff: Text diffing for sync preview

Development Dependencies

• jest: Testing framework
• eslint: Code linting
• supertest: HTTP testing

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• PocketBase
• pbdeploy
• Issues

pbdeploy v0.0.1 - Unified PocketBase development toolkit