# @cumulus/db

> Utilities for working with the Cumulus DB

Latest version **22.4.0** (published 2026-09-02) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @cumulus/db
pnpm add @cumulus/db
yarn add @cumulus/db
bun add @cumulus/db
```

## 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 | 22.4.0 |
| Published | 2026-09-02 |
| First published | 2020-08-18 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | cumuluspublisher, nsidc_kovarik, jennyhliu, npauzenga, ppilone84, etcart |

## Links

- npm: https://www.npmjs.com/package/@cumulus/db
- npm.io page: https://npm.io/package/@cumulus/db

## Recent versions

- 22.4.0 (latest) — 2026-09-02
- 21.3.5 (release-v21.3.5) — 2026-06-03
- 20.3.3 (release-v20.3.3) — 2026-04-16
- 21.2.1 (release-v21.2.1) — 2026-03-18
- 21.3.2-testlerna.0 (release-v21.3.2-testlerna.0) — 2026-03-02
- 21.3.1-alpha.0 (release-v21.3.1-alpha.0) — 2026-01-28
- 20.3.2 (release-v20.3.2) — 2025-12-04
- 20.2.3 (release-v20.2.3) — 2025-12-03
- 21.0.0-echo10 (release-v21.0.0-echo10) — 2025-11-21
- 20.3.1 (release-v20.3.1) — 2025-10-14
- 20.2.2 (release-v20.2.2) — 2025-10-08
- 20.1.3-alpha.2 (release-v20.1.3-alpha.2) — 2025-05-15
- 20.1.3-alpha.1 (release-v20.1.3-alpha.1) — 2025-05-15
- 20.1.3-alpha.0 (release-v20.1.3-alpha.0) — 2025-05-14
- 18.5.6 (release-v18.5.6) — 2025-04-11
- … 139 more at https://npm.io/package/@cumulus/db/versions

## README

# @cumulus/db

Utilities for working with the Cumulus database.

## Versioning

Cumulus uses a modified semantic versioning scheme and minor releases likely
include breaking changes.

Before upgrade, please read the Cumulus
[release notes](https://github.com/nasa/cumulus/releases) before upgraded.

It is strongly recommended you do not use `^` in your `package.json` to
automatically update to new minor versions. Instead, pin the version or use `~`
to automatically update to new patch versions.

## Installation

```bash
  npm install @cumulus/db
```

## Contents

### Types

TypeScript interfaces describing the data types stored in the Cumulus database are found in the `/types` directory.

Typically, there are two TypeScript interfaces describing each Cumulus data type. For example:

- `PostgresProvider`: Describes the data structure ready for insertion into the Cumulus Postgres database
- `PostgresProviderRecord`: Describes the data structure after retrieval from the Cumulus database. This data type usually includes extra required properties (such as the auto-incremented primary key field), since those properties will exist once a record has been created.

### BigInt cumulus_id columns

For the BigInt columns, knex returns postgres as "string" type. In order to use cumulus_id as a number, knex hook
postProcessResponse is configured to convert the return string from columns ending with "cumulus_id" to number.

### Database Migration

We have scripts to initialize or update the database schema. The system can choose between a "clean slate"
setup and an "incremental patch" approach depending on the state of the database and the configuration.

- Standard Migrations (migrations/):
These are the default operational files. They follow an incremental patch-based model, applying specific,
versioned changes (e.g., adding a column, creating a new index) to an existing database. This is used
for standard updates where data must be preserved and the schema evolved over time.
- Bootstrap Mode (migrations-bootstrap/):
This directory contains the full declarations required to build a clean database from scratch. Instead
of a long history of patches, the bootstrap process uses optimized scripts to define the entire schema
(tables, constraints, and initial partitions) in one pass. This is for fresh deployments and ensures
a consistent, modern baseline.

**Note**: A database created using the Bootstrap process is fully compatible with the migration history;
it can be updated with Standard Migrations later as new patches are released.

#### Creating a new migration

```sh
  npx knex migrate:make migration_name
```

This will create a new migration file under `migrations`. Please do not modify the existing files in
migrations directory.

**Important: Schema Synchronization**
Because `Standard Migrations` uses patches and the `Bootstrap Mode` uses a "clean slate" model,
you must keep them in sync:
- Update Both: Any schema change added to a migration patch must be manually added to the bootstrap
  declarations to keep fresh deployments current.
- Matching Filenames: Every file in migrations-bootstrap/ must also exist in migrations/ to prevent
  Knex "corrupt directory" errors.
- Content: The bootstrap version contains the full logic, while the version in the standard folder
  can be a no-op script (e.g., xxx_seed_migration_history.ts) to satisfy Knex validation.


## About Cumulus

Cumulus is a cloud-based data ingest, archive, distribution and management
prototype for NASA's future Earth science data streams.

[Cumulus Documentation](https://nasa.github.io/cumulus)

## Contributing

To make a contribution, please
[see our contributing guidelines](https://github.com/nasa/cumulus/blob/master/CONTRIBUTING.md).

---
_Source: https://npm.io/package/@cumulus/db · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._