# @wmfs/supercopy
> Takes a specifically-named directory structure of CSV files and conjures bulk insert, update and delete statements and applies them to a PostgreSQL database.
Latest version **1.56.1** (published 2026-08-13) · MIT license · 0 weekly downloads
## Install
```sh
npm install @wmfs/supercopy
pnpm add @wmfs/supercopy
yarn add @wmfs/supercopy
bun add @wmfs/supercopy
```
## Health
**Score 55/100 (C)** — status: active.
Positive: no vulnerabilities; recently updated; high maintenance score.
Warnings: low downloads; no types; no esm support.
## Facts
| | |
|---|---|
| Version | 1.56.1 |
| Published | 2026-08-13 |
| First published | 2018-06-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 94.6 KB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 5 |
| Author | West Midlands Fire Service |
| Maintainers | wmfsbot |
| Keywords | tymly, package, postgres, postgresql, copy, import, csv |
## Links
- npm: https://www.npmjs.com/package/@wmfs/supercopy
- Repository: https://github.com/wmfs/supercopy
- Homepage: https://github.com/wmfs/supercopy#readme
- Issues: https://github.com/wmfs/supercopy/issues
- npm.io page: https://npm.io/package/@wmfs/supercopy
## Dependencies (5)
- [debug](https://npm.io/package/debug.md) 4.4.1
- [upath](https://npm.io/package/upath.md) 2.0.1
- [lodash](https://npm.io/package/lodash.md) 4.17.21
- [csv-string](https://npm.io/package/csv-string.md) 4.1.1
- [pg-copy-streams](https://npm.io/package/pg-copy-streams.md) 7.0.0
## Alternatives
- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads
## Recent versions
- 1.56.1 (latest) — 2026-08-13
- 1.56.0 — 2025-10-21
- 1.55.0 — 2025-05-28
- 1.54.0 — 2025-05-14
- 1.53.0 — 2024-12-09
- 1.52.0 — 2024-11-04
- 1.51.0 — 2024-11-04
- 1.50.0 — 2022-11-02
- 1.49.0 — 2022-11-02
- 1.48.0 — 2022-11-01
- 1.47.0 — 2022-01-25
- 1.46.0 — 2021-07-09
- 1.45.0 — 2021-05-13
- 1.44.0 — 2021-02-23
- 1.43.0 — 2021-01-12
- … 45 more at https://npm.io/package/@wmfs/supercopy/versions
## README
# supercopy
[](https://tymly.io/)
[](https://www.npmjs.com/package/@wmfs/supercopy)
[](https://circleci.com/gh/wmfs/supercopy)
[](https://codecov.io/gh/wmfs/supercopy)
[](https://www.codefactor.io/repository/github/wmfs/supercopy)
[](https://dependabot.com/)
[](http://commitizen.github.io/cz-cli/)
[](https://standardjs.com)
[](https://github.com/wmfs/tymly/blob/master/packages/pg-concat/LICENSE)
> Takes a specifically-named directory structure of CSV files and conjures bulk insert, update and delete statements and applies them to a PostgreSQL database.
## Install
```bash
$ npm install supercopy --save
```
## Usage
```javascript
const pg = require('pg')
const supercopy = require('supercopy')
// Make a new Postgres client
const client = new pg.Client('postgres://postgres:postgres@localhost:5432/my_test_db')
supercopy(
{
sourceDir: '/dir/that/holds/deletes/inserts/updates/and/upserts/dirs',
headerColumnNamePkPrefix: '.',
topDownTableOrder: ['departments', 'employees'],
client: client,
schemaName: 'my_schema',
truncateTables: true,
debug: true,
multicopy: false,
directoryNames: { ... }
},
function (err) {
// Done!
}
)
```
## supercopy(`options`, `callback`)
### Options
| Property | Type | Notes |
| -------- | ---- | ------ |
| `sourceDir` | `function` | An absolute path pointing to a directory containing action folders. See the [File Structure](#structure) section for more details.
| `headerColumnNamePkPrefix` | `string` | When conjuring an `update` statement, Supercopy will need to know which columns in the CSV file constitute a primary key. It does this by expecting the first line of each file to be a header containing `,` delimited column names. However, column names prefixed with this value should be deemed a primary-key column. Only use in update CSV-file headers.|
| `topDownTableOrder` | `[string]` | An array of strings, where each string is a table name. Table inserts will occur in this order and deletes in reverse - use to avoid integrity-constraint errors. If no schema prefix is supplied to a table name, then it's inferred from `schemaName`.
| `client` | `client` | Either a [pg](https://www.npmjs.com/package/pg) client or pool (something with a `query()` method) that's already connected to a PostgreSQL database.
| `schemaName` | `string` | Identifies a PostgreSQL schema where the tables that are to be affected by this copy be found.
| `truncateTables` | `boolean` | A flag to indicate whether or not to truncate tables before supercopying into them
| `debug` | `boolean` | Show debugging information on the console
| `multicopy` | `boolean` | Enables 'sourceDir' to house many typical Supercopy 'sourceDir' shaped directories. Defaults to false.
| `quote` | `string` | Override the the default quote character, ". It isn't necessary to quote fields but occasionally (especially when importing JSON fields) you need to, and this option will help.
| `directoryNames` | `object` | Overrides the default directory names - see below.
### File structure
The directory identified by the `sourceDir` option should be structured in the following way:
```
/someDir
/inserts
table1.csv
table2.csv
/updates
table1.csv
table2.csv
/upserts
table1.csv
table2.csv
/deletes
table1.csv
OR IF USING MULTICOPY
/manyDirs
/someDir
/inserts
table1.csv
table2.csv
/someDir
/inserts
table1.csv
table2.csv
```
#### Notes
* The sub-directories here refer to the type of action that should be performed using CSV data files contained in it. Supported directory names are `insert`, `update`, `upsert` (try to update, failing that insert) and `delete`.
* Directories are optional. A directory maybe missing or empty.
* The `directoryNames` option can be used to apply actions to directories if the names don't meet the above structure. Eg
`directoryName : { 'inserts': 'new', 'deletes': 'old' }` would insert the contents of the directory named `new` and remove the contents of the `old` directory.
* The filename of each file should refer to a table name in the schema identified by the `schemaName` option.
* The expected format of the .csv files is:
* One line per record
* The first line to be a comma delimited list of column names (i.e. a header record)
* For update and upsert files, ensure columns-names in the header record that are part of the primary key are identified with a `headerColumnNamePkPrefix` character.
* All records to be comma delimited, and any text columns containing a `,` should be quoted with a `"`. The [csv-string](https://www.npmjs.com/package/csv-string#stringifyinput--object-separator--string--string) package might help.
* Note that only primary key values should be provided in a 'delete' file.
## Testing
Before running these tests, you'll need a test PostgreSQL database available and set a `PG_CONNECTION_STRING` environment variable to point to it, for example:
```PG_CONNECTION_STRING=postgres://postgres:postgres@localhost:5432/my_test_db```
```bash
$ npm test
```
## License
[MIT](https://github.com/wmfs/supercopy/blob/master/LICENSE)
---
_Source: https://npm.io/package/@wmfs/supercopy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._