https://github.com/bendrucker/postgres-bytea
Postgres bytea parser
https://github.com/bendrucker/postgres-bytea
Last synced: over 1 year ago
JSON representation
Postgres bytea parser
- Host: GitHub
- URL: https://github.com/bendrucker/postgres-bytea
- Owner: bendrucker
- License: mit
- Created: 2015-06-14T04:29:14.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2022-04-21T17:51:22.000Z (over 4 years ago)
- Last Synced: 2025-04-10T08:14:05.080Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 24.4 KB
- Stars: 13
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# postgres-bytea [](https://github.com/bendrucker/postgres-bytea/actions?query=workflow%3Atests)
> Decode/encode Postgres bytea strings to Buffers
## Install
```sh
npm install postgres-bytea
```
## Usage
### Decoding
To decode a bytea string into a buffer:
```js
const bytea = require('postgres-bytea')
// bytea hex format
bytea.decode('\\x1234') //
// bytea escape format
bytea.decode('\\000\\100\\200') //
```
The `decode` function supports both the hex format used in Postgres 9+ and the escape format used in Postgres 8 and earlier. It automatically detects the format from the incoming data.
For backward compatibility, `decode` is also the default export from the package.
### Decoding (Stream)
To decode a bytea hex stream into binary:
```js
const bytea = require('postgres-bytea')
readable.pipe(new bytea.Decoder())
```
`Decoder` expects a double-escaped `\\x` prefix to allow reading from a `COPY TO` statement.
### Encoding (Stream)
```js
const bytea = require('postgres-bytea')
readable.pipe(new bytea.Encoder())
```
`Encoder` adds a double-escaped `\\x` prefix to allow writing to a `COPY FROM` statement.
## API
#### `bytea.decode(input)` -> `buffer`
##### input
*Required*
Type: `string`
A Postgres bytea binary string.
#### `new bytea.Decoder()` -> `stream.Transform`
Creates a bytea decoder stream that emits buffer chunks.
#### `new bytea.Encoder()` -> `stream.Transform`
Creates a bytea encoder stream that receives buffer chunks and emits them as bytea strings.
## Prefix Escaping
> The “hex” format encodes binary data as 2 hexadecimal digits per byte, most significant nibble first. The entire string is preceded by the sequence \x (to distinguish it from the escape format). In some contexts, the initial backslash may need to be escaped by doubling it (see Section 4.1.2.1).
>
> https://www.postgresql.org/docs/12/datatype-binary.html#id-1.5.7.12.9
A `SELECT` statement returns bytea values using the single-escaped `\x` prefix. The `COPY TO` and `COPY FROM` commands expect and return bytea values with the double-escaped `\\x` prefix.
`bytea.decode` expects the single-escaped prefix. The `Decoder` and `Encoder` streams expect the double-escaped prefix, since they are most useful in `COPY FROM` and `COPY TO` statements.
## License
MIT © [Ben Drucker](http://bendrucker.me)