# postgres-interval

> Parse Postgres interval columns

Latest version **4.1.0** (published 2026-06-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install postgres-interval
pnpm add postgres-interval
yarn add postgres-interval
bun add postgres-interval
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 4.1.0 |
| Published | 2026-06-30 |
| First published | 2015-06-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 0 |
| Unpacked size | 14 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 38 |
| Author | Ben Drucker |
| Maintainers | bendrucker |
| Keywords | postgres, interval, parser |

## Links

- npm: https://www.npmjs.com/package/postgres-interval
- Repository: https://github.com/bendrucker/postgres-interval
- Homepage: https://github.com/bendrucker/postgres-interval#readme
- Issues: https://github.com/bendrucker/postgres-interval/issues
- npm.io page: https://npm.io/package/postgres-interval

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 4.1.0 (latest) — 2026-06-30
- 4.0.2 — 2024-01-29
- 4.0.1 — 2023-06-29
- 4.0.0 — 2021-09-14
- 3.0.0 — 2020-10-30
- 2.1.0 — 2020-08-05
- 2.0.0 — 2020-06-19
- 1.2.0 — 2019-02-23
- 1.1.2 — 2018-07-11
- 1.1.1 — 2017-07-21
- 1.1.0 — 2017-03-10
- 1.0.2 — 2016-04-12
- 1.0.1 — 2015-12-03
- 0.0.1 — 2015-10-26
- 1.0.0 — 2015-06-14

## README

# postgres-interval [![tests](https://github.com/bendrucker/postgres-interval/workflows/tests/badge.svg)](https://github.com/bendrucker/postgres-interval/actions?query=workflow%3Atests)

> Parse Postgres interval columns


## Install

```sh
npm install --save postgres-interval
```


## Usage

```js
var parse = require('postgres-interval')
var interval = parse('01:02:03')
// => { hours: 1, minutes: 2, seconds: 3 }
interval.toPostgres()
// 1 hour 2 minutes 3 seconds
interval.toISOString()
// P0Y0M0DT1H2M3S
interval.toISOStringShort()
// PT1H2M3S
```

This package parses the default Postgres interval style. If you have changed [`intervalstyle`](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-INTERVALSTYLE), you will need to set it back to the default:

```sql
set intervalstyle to default;
```

## API

#### `parse(pgInterval)` -> `interval`

##### pgInterval

*Required*  
Type: `string`

A Postgres interval string.

This package is focused on parsing Postgres outputs. It optimizes for performance by assuming that inputs follow the default interval format. It does not perform any validation on the input. If any interval field is not found, its value will be set to `0` in the returned `interval`.

#### `interval.toPostgres()` -> `string`

Returns an interval string. This allows the interval object to be passed into prepared statements.

#### `interval.toISOString()` -> `string`

Returns an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) compliant string, for example `P0Y0M0DT0H9M0S`.

Also available as `interval.toISO()` for backwards compatibility.

#### `interval.toISOStringShort()` -> `string`

Returns an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) compliant string shortened to minimum length, for example `PT9M`.

#### `interval.toTemporalDuration()` -> `Temporal.Duration`

Returns a [`Temporal.Duration`](https://tc39.es/proposal-temporal/docs/duration.html) representing the interval.

Requires `globalThis.Temporal`. It ships unflagged in Node 26+. On older runtimes, install a polyfill such as [`@js-temporal/polyfill`](https://www.npmjs.com/package/@js-temporal/polyfill) and assign it to `globalThis.Temporal`. The method throws if `Temporal` is unavailable.

Postgres mixed-sign intervals (e.g. `1 mon -1 days`) throw a `RangeError`. `Temporal.Duration` requires all fields to share a single sign, which these intervals violate.

The `Temporal` types are not yet in the default TypeScript lib. To resolve the return type, your project needs Temporal lib types: the TypeScript lib once available, or the `@js-temporal/polyfill` types. This package adds no type dependency.

## License

MIT © [Ben Drucker](http://bendrucker.me)

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