Greenseed is a small CLI tool to seed a PostgreSQL database from JSON files.
pnpm add greenseedOr install it globally:
pnpm add -g greenseedInstall via npm:
npm install greenseednpm install -g greenseedInstall via bun:
bun install greenseedbun install -g greenseedOr install the standalone binary (no runtime required):
curl -fsSL https://raw.githubusercontent.com/mohit4bug/greenseed/main/install.sh | bashGenerate a seed configuration file:
greenseed initThen run the seed:
greenseed pushGreenseed reads a seed.config.json file in the current directory. You can specify a custom path with the -c flag.
Allowed seed file extensions. Currently only .json is supported.
[".json"]The name of the environment variable containing the PostgreSQL connection string.
"DATABASE_URL"Behaviour when a source data file does not exist.
"error"— throws an error and stops the seed (default)"skip"— silently skips the table
When true (default), the entire seed runs inside a single database transaction. If any insert fails, all changes are rolled back.
trueArray of table configurations. Each entry defines a table to seed.
| Option | Required | Default | Description |
|---|---|---|---|
table |
Yes | — | Database table name |
schema |
No | "public" |
Database schema the table belongs to |
primaryKeys |
Yes | — | Column names used for conflict detection |
source |
Yes | — | Path to the JSON data file (relative to config) |
updateOnConflict |
No | null |
Columns to update on conflict (upsert) |
conflictTargetWhere |
No | null |
Predicate for partial unique indexes |
{
"$schema": "./node_modules/greenseed/dist/schema/configuration_schema.json",
"seedFileExtensions": [".json"],
"databaseUrlEnvVar": "DATABASE_URL",
"onMissingFile": "error",
"useTransaction": true,
"tables": [
{
"table": "users",
"schema": "public",
"primaryKeys": ["id"],
"source": "./data/users.json"
},
{
"table": "orders",
"schema": "public",
"primaryKeys": ["id"],
"source": "./data/orders.json",
"updateOnConflict": ["status", "updated_at"],
"conflictTargetWhere": "is_active = true"
}
]
}Each source file must be a valid JSON array of objects. Extra object properties that do not exist as columns in the target table are automatically ignored.
[
{ "id": 1, "name": "Alice", "email": "alice@example.com" },
{ "id": 2, "name": "Bob", "email": "bob@example.com" }
]Generates a seed.config.json file with example configuration.
| Option | Description | Default |
|---|---|---|
-c, --config <file> |
Config file path | seed.config.json |
Connects to the database and seeds all configured tables.
| Option | Description | Default |
|---|---|---|
-c, --config <file> |
Config file path | seed.config.json |
-d, --dbvar <name> |
Override the database URL environment variable name | Value from config |
The push command:
- Loads and validates the configuration
- Reads the database URL from the environment variable
- Connects to PostgreSQL and verifies all tables exist
- Reads each table's source JSON file and inserts data in batches
- Reports progress and a final summary
The database connection URL must be set in the environment. By default, Greenseed reads from DATABASE_URL.
export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
greenseed pushOverride the variable name at runtime with the -d flag:
export MY_DB="postgresql://user:password@localhost:5432/mydb"
greenseed push --dbvar MY_DBMIT