@ddl-tech/wappler-pocketbase/INSTALLATION.md

PocketBase CRUD module for Wappler Server Connect with complete database operations, authentication, and file management

# PocketBase CRUD Module Installation Guide

## Files Created

This PocketBase CRUD module consists of the following files:

### Core Module Files
1. **`extensions/server_connect/modules/pocketbase.js`** - Main module implementation
2. **`extensions/server_connect/modules/pocketbase.hjson`** - UI definition for Wappler interface

### Documentation Files
3. **`README.md`** - Comprehensive documentation and API reference
4. **`example-usage.md`** - Practical examples and usage patterns
5. **`INSTALLATION.md`** - This installation guide

## Installation Steps

### 1. Copy Module Files
Copy the following files to your Wappler project:

```
your-wappler-project/
├── extensions/
│   └── server_connect/
│       └── modules/
│           ├── pocketbase.js
│           └── pocketbase.hjson
```

### 2. Verify Directory Structure
Ensure the `extensions/server_connect/modules/` directory exists in your project root. If it doesn't exist, create it:

```bash
mkdir -p extensions/server_connect/modules
```

### 3. Restart Wappler
After copying the files, restart Wappler to load the new module.

### 4. Verify Installation
1. Open Wappler
2. Create a new Server Action
3. Look for "PocketBase" actions in the action picker
4. You should see groups like:
   - **PocketBase** (Connect, Authenticate, Logout)
   - **PocketBase CRUD** (Create, Read, Update, Delete operations)
   - **PocketBase Files** (File management)
   - **PocketBase Admin** (Collections, Health Check)
   - **PocketBase Advanced** (Batch operations)

## Quick Test

### Test Connection
1. Create a new Server Action
2. Add "Connect to PocketBase" action
3. Set URL to your PocketBase instance (e.g., `http://127.0.0.1:8090`)
4. Run the action to test connectivity

### Test Authentication
1. Add "Authenticate User" action
2. Provide test user credentials
3. Verify successful authentication

## Module Features

### ✅ Complete CRUD Operations
- Create records with file uploads
- Read single records or paginated lists
- Update records with partial data
- Delete records by ID

### ✅ Authentication & Session Management
- User login/logout
- Automatic token handling
- Session persistence
- Multi-collection auth support

### ✅ Advanced Querying
- Complex filtering expressions
- Sorting and pagination
- Relation expansion
- Field selection

### ✅ File Management
- File upload support
- File URL generation
- Thumbnail support
- Multiple file handling

### ✅ Batch Operations
- Transaction support
- Multiple operations in single request
- Atomic operations
- Rollback on error

### ✅ Admin Features
- Collection management
- Health monitoring
- Schema inspection

## Dependencies

The module automatically installs the required PocketBase JavaScript SDK:
- **pocketbase**: ^0.21.0

No manual npm installation required - Wappler handles this automatically.

## Requirements

- **Wappler**: Latest version with Node.js server model
- **PocketBase**: Version 0.15.0 or higher
- **Node.js**: Version 14 or higher

## Configuration

### PocketBase Setup
1. Download and run PocketBase from https://pocketbase.io/
2. Create your collections and configure authentication
3. Note your PocketBase URL (default: http://127.0.0.1:8090)

### Wappler Project Setup
1. Ensure your project uses Node.js server model
2. Copy the module files as described above
3. Configure your first connection using the "Connect to PocketBase" action

## Usage Workflow

### Basic Workflow
1. **Connect** → Establish connection to PocketBase
2. **Authenticate** → Login user (optional, for protected operations)
3. **CRUD Operations** → Perform database operations
4. **Logout** → Clear authentication when done

### Example Server Action
```json
{
  "exec": {
    "steps": [
      {
        "name": "connect",
        "module": "pocketbase",
        "action": "connect",
        "options": {
          "url": "http://127.0.0.1:8090"
        }
      },
      {
        "name": "get_posts",
        "module": "pocketbase", 
        "action": "getList",
        "options": {
          "collection": "posts",
          "filter": "status = 'published'",
          "sort": "-created",
          "perPage": "10"
        }
      }
    ]
  }
}
```

## Troubleshooting

### Module Not Appearing
- Verify files are in correct directory structure
- Restart Wappler completely
- Check file permissions

### Connection Issues
- Verify PocketBase is running
- Check URL format (include http://)
- Verify firewall/network settings

### Authentication Problems
- Verify user exists in PocketBase
- Check collection name (default: 'users')
- Verify user credentials

### File Upload Issues
- Check file path format
- Verify file permissions
- Ensure PocketBase storage is configured

## Support Resources

1. **PocketBase Documentation**: https://pocketbase.io/docs/
2. **Wappler Documentation**: https://docs.wappler.io/
3. **Module Examples**: See `example-usage.md`
4. **API Reference**: See `README.md`

## Version Information

- **Module Version**: 1.0.0
- **PocketBase SDK**: ^0.21.0
- **Wappler Compatibility**: Latest versions
- **Node.js Compatibility**: 14+

## License

This module is provided as-is for use with Wappler projects.

---

**Installation Complete!** 🎉

You now have a fully functional PocketBase CRUD module for Wappler Server Connect. Check the `README.md` and `example-usage.md` files for detailed usage instructions and examples.