Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gajus/slonik-utilities
Utilities for manipulating data in PostgreSQL database using Slonik.
https://github.com/gajus/slonik-utilities
postgresql slonik upsert
Last synced: 7 days ago
JSON representation
Utilities for manipulating data in PostgreSQL database using Slonik.
- Host: GitHub
- URL: https://github.com/gajus/slonik-utilities
- Owner: gajus
- License: other
- Created: 2019-04-18T13:25:19.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-06-17T19:42:20.000Z (over 1 year ago)
- Last Synced: 2024-10-19T00:18:15.034Z (20 days ago)
- Topics: postgresql, slonik, upsert
- Language: TypeScript
- Size: 359 KB
- Stars: 32
- Watchers: 3
- Forks: 8
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://coveralls.io/github/gajus/slonik-utilities)
[](https://www.npmjs.org/package/slonik-utilities)
[](https://github.com/gajus/canonical)
[](https://twitter.com/kuizinas)
Utilities for manipulating data in PostgreSQL database using [Slonik](https://github.com/gajus/slonik).
* [Slonik Utilities](#user-content-slonik-utilities)
* [Contents](#user-content-slonik-utilities-contents)
* [Usage](#user-content-slonik-utilities-usage)
* [`update`](#user-content-slonik-utilities-usage-update)
* [`updateDistinct`](#user-content-slonik-utilities-usage-updatedistinct)
* [`upsert`](#user-content-slonik-utilities-usage-upsert)
```js
import {
update
} from 'slonik-utilities';
/**
* @param connection Instance of Slonik connection.
* @param {string} tableName Target table name.
* @param {Object.} namedValueBindings Object describing the desired column values.
* @param {Object.} [booleanExpressionValues] Object describing the boolean expression used to construct WHERE condition.
* @returns {UpdateResultType}
*/
update;
```
Constructs and executes `UPDATE` query.
Operation:
```js
update(
connection,
'user',
{
givenName: 'foo'
}
);
```
Is equivalent to:
```sql
UPDATE "user"
SET
"given_name" = $1;
```
#### Example: Update rows matching a boolean WHERE condition
Operation:
```js
update(
connection,
'user',
{
givenName: 'foo'
},
{
lastName: 'bar'
}
);
```
Is equivalent to:
```sql
UPDATE "user"
SET
"given_name" = $1
WHERE
"last_name" = $2;
```
```js
import {
updateDistinct
} from 'slonik-utilities';
/**
* @param connection Instance of Slonik connection.
* @param {string} tableName Target table name.
* @param {Object.} namedValueBindings Object describing the desired column values.
* @param {Object.} [booleanExpressionValues] Object describing the boolean expression used to construct WHERE condition.
* @returns {UpdateDistinctResultType}
*/
updateDistinct;
```
Constructs and executes `UPDATE` query matching only rows with distinct values.
Operation:
```js
update(
connection,
'user',
{
givenName: 'foo'
}
);
```
Is equivalent to:
```sql
UPDATE "user"
SET
"given_name" = $1
WHERE
"given_name" IS DISTINCT FROM $1;
```
#### Example: Update rows matching a boolean WHERE condition
Operation:
```js
update(
connection,
'user',
{
givenName: 'foo'
},
{
lastName: 'bar'
}
);
```
Is equivalent to:
```sql
UPDATE "user"
SET
"given_name" = $1
WHERE
"last_name" = $2 AND
"given_name" IS DISTINCT FROM $1;
```
```js
import {
upsert
} from 'slonik-utilities';
/**
* @typedef Configuration~Upsert
* @property identifierName column name. Default: "id".
*/
/**
* @param connection Instance of Slonik connection.
* @param {string} tableName Target table name.
* @param {Object.} namedValueBindings Object describing the desired column values.
* @param {string[]} [uniqueConstraintColumnNames] Names of columns that describe a unique constraint on the table. Defaults to property names of `namedValueBindings`.
* @param {Configuration~Upsert} [configuration]
*/
upsert;
```
Inserts a new record to the database. If there is a conflicting unique constraint, updates the existing row.
#### Example: Named value bindings equal to the unique constraint column names
Table schema:
```sql
CREATE TABLE user (
id SERIAL PRIMARY KEY,
email_address text NOT NULL
);
CREATE UNIQUE INDEX user_email_idx ON user(email_address text_ops);
```
Operation:
```js
upsert(
connection,
'user',
{
emailAddress: '[email protected]'
}
);
```
Behaviour:
If `user` table already contains a record describing the input email, then the following query will be evaluted:
```sql
SELECT "id"
FROM "user"
WHERE (
"email_address" = $1
);
```
If `user` table does not contain a record describing the input email, then the following queries will be evaluated:
```sql
SELECT "id"
FROM "user"
WHERE (
"email_address" = $1
);
INSERT INTO "user" ("email_address")
VALUES ($1)
ON CONFLICT ("email_address")
DO NOTHING
RETURNING "id";
-- This query will not be evaluted if the preceeding query returns result.
SELECT "id"
FROM "user"
WHERE (
"email_address" = $1
);
```
#### Example: Named value bindings different than the unique constraint column names
Table schema:
```sql
CREATE TABLE user (
id SERIAL PRIMARY KEY,
email_address text NOT NULL,
password text NOT NULL,
given_name text NOT NULL,
family_name text NOT NULL
);
CREATE UNIQUE INDEX user_email_idx ON user(email_address text_ops);
```
Operation:
```js
upsert(
connection,
'user',
{
emailAddress: '[email protected]',
familyName: 'Kuizinas',
givenName: 'Gajus'
},
[
'email_address'
]
);
```
Behaviour:
If `user` table already contains a record describing the input email, then the following query will be evaluted:
```sql
SELECT "id"
FROM "user"
WHERE (
"email_address" = $1 AND
"family_name" = $2 AND
"given_name" = $3
);
```
If `user` table does not contain a record describing the input email, then the following queries will be evaluated:
```sql
SELECT "id"
FROM "user"
WHERE (
"email_address" = $1 AND
"family_name" = $2 AND
"given_name" = $3
);
INSERT INTO "user" ("email_address", "family_name", "given_name")
VALUES ($1, $2, $3)
ON CONFLICT ("email_address")
DO UPDATE SET
"family_name" = "excluded"."family_name",
"given_name" = "excluded"."given_name"
RETURNING "id"
```
#### Example: SQL tags as values
Named value binding values can be SQL tokens, e.g.
```js
upsert(
connection,
'user',
{
emailAddress: '[email protected]',
createdAt: sql.raw('to_timestamp($1)', [1555595070])
}
);
```
Given the above example, queries equivalent to the following will be evaluated:
```sql
SELECT "id"
FROM "user"
WHERE (
"email_address" = $1 AND
"created_at" = to_timestamp($2)
);
-- ...
```