DynamoDB Seeder

Common errors

• Error: Schema could not be found for table: <TableName>

  cause The `_schema` path specified in your JSON data (e.g., `./path/to/Schema.json`) is incorrect or the file does not exist at the resolved location.
  fix Double-check the relative path to your schema file from the directory where you execute the seeding script. Ensure the file exists and is accessible.

• AWS.DynamoDB.createTable is not a function

  cause This error likely indicates a misconfiguration in how `dynongo` (the underlying library used by `dynamo-seeder`) connects to DynamoDB, or an issue with the AWS SDK setup.
  fix Ensure your AWS credentials and region are correctly configured (e.g., via environment variables or a `~/.aws/credentials` file). If using `dynamodb-local`, verify the `local: true` option is passed to `seeder.connect()` and the local instance is running.

• seeder.connect is not a function

  cause You might be attempting to import `dynamo-seeder` using an ES module syntax (`import seeder from 'dynamo-seeder'`) in an environment where it's only exported as a CommonJS module.
  fix Change your import statement to `const seeder = require('dynamo-seeder');` to correctly load the CommonJS module.

Warnings

• breaking As a package in pre-1.0.0 status (v0.5.0), `dynamo-seeder` may introduce breaking changes between minor versions without adhering to semantic versioning guarantees. Developers should test thoroughly when updating.
  Fix: Always pin to exact minor versions (e.g., `"dynamo-seeder": "0.5.0"`) and review release notes if available before upgrading.
• breaking The `dropTables: true` option in `seeder.seed()` will permanently delete existing tables and their data before recreating them. Using this in production environments will lead to severe data loss.
  Fix: Exercise extreme caution with `dropTables: true`. Ensure it is only enabled for development or testing environments where data loss is acceptable. For production, consider using a migration tool or a strategy that only inserts/updates data without dropping tables.
• gotcha The package uses `dynongo` internally, which relies on AWS SDK v2. Its age (last updated 5 years ago) means it may not be compatible with newer Node.js versions or the latest AWS SDK v3, potentially leading to dependency conflicts or unexpected behavior.
  Fix: Test `dynamo-seeder` carefully with your specific Node.js version and other AWS SDK dependencies. Consider using an alternative, more actively maintained DynamoDB seeding solution if compatibility issues arise. For AWS SDK v3, consider tools like `@cloudcomponents/cdk-dynamodb-seeder` or `dyngoose`.
• gotcha Expressions within JSON data, like `"=new Date().toISOString()"` or `"=this.firstName + this.name"`, are evaluated using JavaScript's `eval`-like mechanism. If seed data originates from untrusted sources, this could lead to arbitrary code execution (a supply chain attack vector if malicious data is injected).
  Fix: Ensure all seed data, especially any containing expressions, is thoroughly vetted and comes from trusted sources. Do not use this feature with user-provided or otherwise untrusted input. Consider sanitizing or validating expressions if they must be dynamic.
• gotcha The `_schema` path in the JSON data is relative to where `seeder.seed()` is called. Incorrect relative paths will result in 'schema not found' errors, halting the seeding process.
  Fix: Always verify the `_schema` paths are correct relative to the script executing `seeder.seed()`. Use `path.join(__dirname, 'schema-folder', 'MySchema.json')` for robustness if constructing paths dynamically.
• deprecated This package appears to be abandoned or in deep maintenance, with no recent updates (last publish 5 years ago) and a low version number (0.5.0). It is unlikely to receive bug fixes, security patches, or new features.
  Fix: Consider migrating to more actively maintained DynamoDB seeding or migration tools like those integrated with AWS CDK (`@cloudcomponents/cdk-dynamodb-seeder`, `aws-cdk-dynamodb-seeder`) or general-purpose data loaders for DynamoDB.

Install

• npm install dynamo-seeder npm
• yarn add dynamo-seeder yarn
• pnpm add dynamo-seeder pnpm

Imports

• seeder

  const seeder = require('dynamo-seeder');

  This package is primarily CommonJS-oriented, as indicated by its age and the documentation's `require` usage. Direct ESM import (`import seeder from 'dynamo-seeder'`) may not work without a CommonJS wrapper or bundler configuration.
• seeder.connect

  const seeder = require('dynamo-seeder');
  seeder.connect({ prefix: 'my-app' });

  The `connect` method initializes the DynamoDB client, often requiring configuration like table prefixes. Credentials should ideally be managed via environment variables or IAM roles, though direct credential passing is possible with `dynongo`'s underlying connection.
• seeder.seed

  const seeder = require('dynamo-seeder');
  seeder.seed(data, { dropTables: true });

  The `seed` method initiates the data population process. The `dropTables` option is critical, as `true` will delete and recreate tables, leading to data loss if not used carefully.

Quickstart

This quickstart demonstrates how to use `dynamo-seeder` to connect to DynamoDB (local or remote), define table schemas and data in JSON, and seed the database. It includes an example of dynamic data generation using JavaScript expressions and the `dropTables` option for fresh seeding.

const seeder = require('dynamo-seeder');
const path = require('path');
const fs = require('fs');

// Mock schema data for UserTable.json
const userSchema = {
    "TableName": "User",
    "AttributeDefinitions": [
        { "AttributeName": "email", "AttributeType": "S" }
    ],
    "KeySchema": [
        { "AttributeName": "email", "KeyType": "HASH" }
    ],
    "ProvisionedThroughput": {
        "ReadCapacityUnits": 1,
        "WriteCapacityUnits": 1
    }
};

// Create a dummy schema file for the seeder to find
const schemaPath = path.join(__dirname, 'UserSchema.json');
fs.writeFileSync(schemaPath, JSON.stringify(userSchema, null, 2));

// Mock data for seeding
const seedData = {
    "users": {
        "_schema": "./UserSchema.json",
        "foo": {
            "firstName": "Foo",
            "name": "Bar",
            "fullName": "=this.firstName + ' ' + this.name",
            "email": "foo@bar.com",
            "birthday": "=new Date(1988, 8, 16).toISOString()"
        },
        "bar": {
            "firstName": "Baz",
            "name": "Qux",
            "email": "baz@qux.com"
        }
    }
};

async function runSeeder() {
    try {
        // Connect to DynamoDB (defaults to local DynamoDB if not configured explicitly)
        // For AWS, ensure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION are set as env vars
        seeder.connect({
            prefix: 'mytestapp.', // Prefix for table names
            local: process.env.DYNAMODB_LOCAL === 'true', // Connect to DynamoDB Local
            // For local, you might also need host/port:
            // host: 'localhost',
            // localPort: 8000
        });

        console.log('Seeding DynamoDB tables...');
        await seeder.seed(seedData, { dropTables: true }); // dropTables: true will recreate tables
        console.log('Database successfully seeded!');
    } catch (err) {
        console.error('Error seeding database:', err);
    } finally {
        // Clean up dummy schema file
        fs.unlinkSync(schemaPath);
        // In a real application, you might disconnect or simply exit
        process.exit(0);
    }
}

// Ensure DYNAMODB_LOCAL is set to 'true' to run against local DynamoDB for testing
// Otherwise, ensure AWS credentials are configured for remote DynamoDB
process.env.DYNAMODB_LOCAL = process.env.DYNAMODB_LOCAL ?? 'true'; 

runSeeder();