parse-dbtool

1.2.0 verified Sat Apr 25 auth: no javascript

A CLI tool for Parse Server that creates database migration and seeder files using Parse.Schema. Current stable version 1.2.0 (no frequent releases). It operates as a standalone executable via npx, requiring environment variables (APPLICATION_ID, SERVER_URL, MASTER_KEY) to connect to a Parse Server instance. Unlike ORM-based migration tools, it works natively with Parse Server's schema system and supports strict mode (allowClientClassCreation: false, addField: false). Key differentiator: it generates migrations and seeds specifically for Parse Platform, not general SQL/NoSQL databases.

Common errors

error Error: Parse is not defined ↓

cause The migration/seed function expects Parse as argument, but code references Parse without using the parameter.

fix

Ensure up/down functions accept Parse parameter and use it instead of a global Parse.

error Cannot find module 'databases/migrations/...' ↓

cause Migration file not found; usually due to wrong working directory or missing 'init' step.

fix

Run 'npx parse-dbtool init' first to create the folder structure, then ensure you are in the project root.

error Error: Invalid schema: class name must not be empty ↓

cause Trying to create or modify a schema without specifying a valid class name.

fix

Always provide a non-empty class name to new Parse.Schema('ClassName').

Warnings

breaking All migration files must use CommonJS exports (module.exports), not ES module import/export. ↓

fix Use module.exports = { up, down }; instead of export default.

gotcha The 'down' migration may not fully revert complex schema changes (e.g., adding fields vs deleting fields). ↓

fix Test 'down' thoroughly and manually verify schema state.

gotcha Environment variables must be set before running commands; .env file is only read if present and ENV_FILE not specified. ↓

fix Ensure .env exists or pass env vars inline: APPLICATION_ID=... npx parse-dbtool migrate

gotcha parse-dbtool uses Parse master key for all operations; ensure MASTER_KEY is kept secure and not committed. ↓

fix Use environment variables or secrets manager; never hardcode master key in code or .env files committed to source control.

Install

npm install parse-dbtool

yarn add parse-dbtool

pnpm add parse-dbtool

Imports

default export (migration template)
```
module.exports = (Parse) => { ... }
```
Migration files export a function that receives the Parse instance. Use CommonJS module.exports, not ES modules.
Parse.Schema
wrong
```
Parse.Schema.addField('name', 'String');
```
correct
```
let schema = new Parse.Schema('ClassName'); schema.addField('name', 'String'); schema.save();
```
Parse.Schema is a constructor; you must instantiate it per class. Methods like addField, deleteField return promises or use callbacks.
Parse.Object (for seeders)
wrong
```
let obj = new Parse.Object(); obj.save();
```
correct
```
let obj = new Parse.Object('ClassName'); obj.set('field', 'value'); await obj.save();
```
Seeders create Parse.Object instances. Always use the class name in constructor. Requires async/await or .then().

Quickstart

Shows full workflow: init, create migration, create seeder, and run both using parse-dbtool CLI.

// 1. Initialize folder structure
npx parse-dbtool init

// 2. Set up .env file with Parse Server credentials
// Create a .env file with:
APPLICATION_ID=myAppId
SERVER_URL=http://localhost:1337/parse
MASTER_KEY=myMasterKey

// 3. Create a migration
npx parse-dbtool migration:make create_pet

// 4. Edit generated file databases/migrations/XXXXXXXXXXXXXX-create_pet.js:
'use strict';
module.exports = {
  up: async (Parse) => {
    const schema = new Parse.Schema('Pet');
    schema.addField('name', 'String');
    schema.addField('species', 'String');
    await schema.save();
  },
  down: async (Parse) => {
    const schema = new Parse.Schema('Pet');
    await schema.delete();
  }
};

// 5. Run migration
npx parse-dbtool migrate

// 6. (Optional) Create a seeder
npx parse-dbtool seed:make seed_pets

// Edit databases/seeders/XXXXXXXXXXXXXX-seed_pets.js:
'use strict';
module.exports = {
  up: async (Parse) => {
    const pet1 = new Parse.Object('Pet');
    pet1.set('name', 'Fluffy');
    pet1.set('species', 'Cat');
    await pet1.save();
    const pet2 = new Parse.Object('Pet');
    pet2.set('name', 'Buddy');
    pet2.set('species', 'Dog');
    await pet2.save();
  },
  down: async (Parse) => {
    const query = new Parse.Query('Pet');
    const pets = await query.find({ useMasterKey: true });
    await Parse.Object.destroyAll(pets, { useMasterKey: true });
  }
};

// 7. Run seeder
npx parse-dbtool db:seed