excel-to-postgres

library1.6.0jsnpmunverified

A utility library (v1.6.0, stable) that exports Excel workbooks (.xlsx) directly into a PostgreSQL database with options for automatic database/table creation, table dropping, and primary key generation. It simplifies ETL workflows by handling schema inference and data insertion in one call. Unlike manual CSV imports or custom scripts, this package offers a zero-config approach with TypeScript support and minimal dependencies. Release cadence is low; updates are driven by bug fixes rather than feature additions.

database productivity

npm install excel-to-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXCEL-TO-POSTGRES

excel-to-postgres

databasejavascriptv1.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

excelToPostgresDb

✓ import { excelToPostgresDb } from 'excel-to-postgres'

✗ const excelToPostgresDb = require('excel-to-postgres')

ESM-only; CommonJS require will fail. Named export, not default.

excelToPostgresDb (default import attempt)

✓ import { excelToPostgresDb } from 'excel-to-postgres'

✗ import excelToPostgresDb from 'excel-to-postgres'

The package does not have a default export; only a named export.

excelToPostgresDb (TypeScript type import)

✓ import { excelToPostgresDb } from 'excel-to-postgres'

✗ import type { excelToPostgresDb } from 'excel-to-postgres'

The main function is the only export; types are automatically included in the import.

Shows basic usage: connect to PostgreSQL, create DB and tables, generate primary key, and export Excel data.

import { excelToPostgresDb } from 'excel-to-postgres'; async function main() { await excelToPostgresDb( { host: 'localhost', user: 'postgres', password: process.env.PGPASSWORD ?? '', port: 5432, database: 'my_pg_db', }, '/path/to/file.xlsx', { createDatabase: true, createTables: true, dropTables: false, generatePrimaryKey: true, } ); console.log('Excel data exported to PostgreSQL'); } main().catch(console.error);

Debug

Known issues

gotchaThe function expects a full file path (string), not a file buffer or stream. Passing a buffer will fail silently or throw a confusing error.

fix

Always provide an absolute or relative path to the .xlsx file. Use path.resolve if needed.

affects: >=1.0.0

gotchaIf createDatabase is false but the database does not exist, the function will throw an error. It does not auto-create the database by default.

fix

Set createDatabase: true in options, or ensure the target database exists beforehand.

affects: >=1.0.0

deprecatedOptions generatePrimaryKey and useExistingPrimaryKeys are mutually exclusive; using both will cause unexpected behavior. No error is thrown.

fix

Choose only one primary key option. Do not set both to true.

affects: >=1.0.0

gotchaThe package does not support .xls (old Excel format) files. It only works with .xlsx (Office Open XML) format.

fix

Convert .xls files to .xlsx first, or use a different library.

affects: >=1.0.0

gotchaColumn names with special characters (e.g., spaces, dots) are not sanitized; they may cause SQL syntax errors when creating tables.

fix

Rename columns in Excel to use only alphanumeric characters and underscores before exporting.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Must use import to load ES Module: /path/to/excel-to-postgres/index.js

Trying to use CommonJS require() in a Node.js project with ES module package.

fix

Use import { excelToPostgresDb } from 'excel-to-postgres' instead of require()

TypeError: Cannot destructure property 'SheetNames' of (intermediate value) as it is undefined.

Passing a file buffer or invalid file path instead of a string path to an .xlsx file.

fix

Ensure you pass a valid file path string (e.g., './data.xlsx') to the function.

error: database "my_pg_db" does not exist

The target database does not exist and createDatabase option is false or not set.

fix

Set createDatabase: true in options, or create the database manually before calling the function.

Upgrade

Version history

1.6.0latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client for Node.js

xlsxrequiredParse Excel (.xlsx) files

Agent activity

29 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/Jmurp11/excel-to-postgres ↗

packageexcel-to-postgres ↗

homepagehttps://github.com/Jmurp11/excel-to-postgres#readme ↗