Перейти к основному содержанию

Postgres / CockroachDB

Неофициальный Бета-перевод

Эта страница переведена PageTurner AI (бета). Не одобрена официально проектом. Нашли ошибку? Сообщить о проблеме →

TypeORM поддерживает драйверы для PostgreSQL, CockroachDB и Amazon Aurora Postgres.

Базы данных, совместимые с PostgreSQL, также могут использоваться в TypeORM через тип источника данных postgres.

Для работы с YugabyteDB обратитесь к их документации по ORM. Учтите, что поскольку YugabyteDB не поддерживает некоторые функции Postgres, часть возможностей TypeORM может быть ограничена.

Установка​

npm install pg

Поддержка потоковой передачи:

npm install pg-query-stream

Параметры источника данных​

Общие параметры источников данных см. в разделе Параметры источника данных. Для подключения к соответствующим базам данных используйте тип источника данных postgres, cockroachdb или aurora-postgres.

  • url - URL подключения. Обратите внимание: другие параметры источника данных имеют приоритет над параметрами, заданными в URL.

  • host - Хост базы данных.

  • port - Порт хоста базы данных. Стандартный порт Postgres — 5432.

  • username - Имя пользователя базы данных.

  • password - Пароль базы данных.

  • database - Имя базы данных.

  • schema - Название схемы. По умолчанию — "public".

  • connectTimeoutMS - Время ожидания подключения (в миллисекундах). Если undefined или 0 — таймаут отсутствует. По умолчанию: undefined.

  • ssl - Объект с параметрами SSL. См. TLS/SSL.

  • uuidExtension - Расширение Postgres для генерации UUID. По умолчанию: uuid-ossp. Можно заменить на pgcrypto, если uuid-ossp недоступно.

  • poolErrorHandler - Функция-обработчик событий 'error' из пула соединений. Принимает экземпляр ошибки. По умолчанию: логирование с уровнем warn.

  • maxTransactionRetries - Максимальное количество повторных попыток транзакции при ошибке 40001. По умолчанию: 5.

  • logNotifications - Логировать уведомления сервера Postgres и события NOTIFY с уровнем info (по умолчанию: false).

  • installExtensions - Автоматически устанавливать необходимые расширения Postgres (по умолчанию: true).

  • extensions - Список дополнительных расширений Postgres для установки (по умолчанию: undefined).

  • applicationName - Идентификатор приложения для статистики и логов (по умолчанию: undefined).

  • parseInt8 - Парсить 64-битные целые числа (int8) как числа JavaScript. По умолчанию int8 возвращаются как строки для предотвращения переполнения. Числа JavaScript (IEEE-754) теряют точность за пределами Number.MAX_SAFE_INTEGER = +2^53. Для полной поддержки 64-битного диапазона используйте строки или нативный bigint.

Дополнительные параметры можно добавить в объект extra — они будут переданы напрямую клиентской библиотеке. Подробнее см. в документации pg: Pool и Client.

Типы столбцов​

Типы столбцов для postgres​

int, int2, int4, int8, smallint, integer, bigint, decimal, numeric, real, float, float4, float8, double precision, money, character varying, varchar, character, char, text, citext, hstore, bytea, bit, varbit, bit varying, timetz, timestamptz, timestamp, timestamp without time zone, timestamp with time zone, date, time, time without time zone, time with time zone, interval, bool, boolean, enum, point, line, lseg, box, path, polygon, circle, cidr, inet, macaddr, macaddr8, tsvector, tsquery, uuid, xml, json, jsonb, jsonpath, int4range, int8range, numrange, tsrange, tstzrange, daterange, int4multirange, int8multirange, nummultirange, tsmultirange, tstzmultirange, multidaterange, geometry, geography, cube, ltree, vector, halfvec.

Типы столбцов для cockroachdb​

array, bool, boolean, bytes, bytea, blob, date, numeric, decimal, dec, float, float4, float8, double precision, real, inet, int, integer, int2, int8, int64, smallint, bigint, interval, string, character varying, character, char, char varying, varchar, text, time, time without time zone, timestamp, timestamptz, timestamp without time zone, timestamp with time zone, json, jsonb, uuid

Примечание: CockroachDB возвращает все числовые типы данных как string. Однако если вы опустите тип столбца и определите свойство как number, ORM преобразует строку в число с помощью parseInt.

Векторные колонки​

Векторные колонки позволяют выполнять поиск по сходству с помощью векторных операторов PostgreSQL:

// L2 distance (Euclidean) - <->
const results = await dataSource.sql`
    SELECT id, embedding
    FROM post
    ORDER BY embedding <-> ${"[1,2,3]"}
    LIMIT 5`

// Cosine distance - <=>
const results = await dataSource.sql`
    SELECT id, embedding
    FROM post
    ORDER BY embedding <=> ${"[1,2,3]"}
    LIMIT 5`

// Inner product - <#>
const results = await dataSource.sql`
    SELECT id, embedding
    FROM post
    ORDER BY embedding <#> ${"[1,2,3]"}
    LIMIT 5`

Пространственные столбцы​

Поддержка PostgreSQL и CockroachDB в TypeORM использует GeoJSON как формат обмена, поэтому столбцы геометрии должны быть помечены как object или Geometry (или подклассы, например Point) после импорта типов geojson или использования встроенных в TypeORM типов GeoJSON:

import {
    Entity,
    PrimaryColumn,
    Column,
    Point,
    LineString,
    MultiPoint
} from "typeorm"

@Entity()
export class Thing {
    @PrimaryColumn()
    id: number

    @Column("geometry")
    point: Point

    @Column("geometry")
    linestring: LineString

    @Column("geometry", {
        spatialFeatureType: "MultiPoint",
        srid: 4326,
    })
    multiPointWithSRID: MultiPoint
}

...

const thing = new Thing()
thing.point = {
    type: "Point",
    coordinates: [116.443987, 39.920843],
}
thing.linestring = {
    type: "LineString",
    coordinates: [
        [-87.623177, 41.881832],
        [-90.199402, 38.627003],
        [-82.446732, 38.413651],
        [-87.623177, 41.881832],
    ],
}
thing.multiPointWithSRID = {
    type: "MultiPoint",
    coordinates: [
        [100.0, 0.0],
        [101.0, 1.0],
    ],
}

TypeORM пытается корректно обрабатывать данные, но не всегда возможно определить, когда значение при вставке или результат функции PostGIS должно рассматриваться как геометрия. В результате вы можете столкнуться с кодом, аналогичным приведённому ниже, где значения преобразуются в геометрические объекты PostGIS geometry из GeoJSON и в GeoJSON как json:

import { Point } from "typeorm"

const origin: Point = {
    type: "Point",
    coordinates: [0, 0],
}

await dataSource.manager
    .createQueryBuilder(Thing, "thing")
    // convert stringified GeoJSON into a geometry with an SRID that matches the
    // table specification
    .where(
        "ST_Distance(geom, ST_SetSRID(ST_GeomFromGeoJSON(:origin), ST_SRID(geom))) > 0",
    )
    .orderBy(
        "ST_Distance(geom, ST_SetSRID(ST_GeomFromGeoJSON(:origin), ST_SRID(geom)))",
        "ASC",
    )
    .setParameters({
        // stringify GeoJSON
        origin: JSON.stringify(origin),
    })
    .getMany()

await dataSource.manager
    .createQueryBuilder(Thing, "thing")
    // convert geometry result into GeoJSON, treated as JSON (so that TypeORM
    // will know to deserialize it)
    .select("ST_AsGeoJSON(ST_Buffer(geom, 0.1))::json geom")
    .from("thing")
    .getMany()