Postgres / CockroachDB

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

PostgreSQL, CockroachDB y Amazon Aurora Postgres son compatibles como drivers de TypeORM.

Las bases de datos compatibles con PostgreSQL también pueden usarse con TypeORM mediante el tipo de fuente de datos postgres.

Para usar YugabyteDB, consulta su documentación de ORM para comenzar. Ten en cuenta que debido a que algunas características de Postgres no son compatibles con YugabyteDB, cierta funcionalidad de TypeORM puede estar limitada.

Instalación

npm install pg

Para soporte de streaming:

npm install pg-query-stream

Opciones de Data Source

Consulta Opciones de Fuente de Datos para las opciones comunes. Puedes usar los tipos de fuente de datos postgres, cockroachdb o aurora-postgres para conectarte a las respectivas bases de datos.

• url - URL de conexión donde se realiza la conexión. Ten en cuenta que otras opciones del data source sobreescribirán parámetros establecidos en la URL.

• host - Host de la base de datos.

• port - Puerto del host de la base de datos. El puerto predeterminado de Postgres es 5432.

• username - Nombre de usuario de la base de datos.

• password - Contraseña de la base de datos.

• database - Nombre de la base de datos.

• schema - Nombre del esquema. Por defecto es "public".

• connectTimeoutMS - Milisegundos antes de que ocurra un tiempo de espera durante la conexión inicial al servidor de Postgres. Si es undefined o se establece en 0, no hay tiempo de espera. Por defecto es undefined.

• ssl - Objeto con parámetros SSL. Ver TLS/SSL.

• uuidExtension - Extensión de Postgres para usar al generar UUID. Por defecto es uuid-ossp. Puede cambiarse a pgcrypto si la extensión uuid-ossp no está disponible.

• poolErrorHandler - Función que se llama cuando el pool subyacente emite el evento 'error'. Toma un único parámetro (instancia de error) y por defecto registra con nivel warn.

• maxTransactionRetries - Número máximo de reintentos de transacción en caso de error 40001. Por defecto es 5.

• logNotifications - Booleano para determinar si los mensajes de notificación del servidor Postgres y los eventos de notificación deben incluirse en los registros del cliente con nivel info (predeterminado: false).

• installExtensions - Booleano para controlar si se instalan automáticamente las extensiones necesarias de Postgres o no (predeterminado: true).

• extensions - Lista de extensiones adicionales de Postgres para instalar en la base de datos (predeterminado: undefined).

• applicationName - Cadena visible en estadísticas y registros para ayudar a referenciar una aplicación con una conexión (predeterminado: undefined).

• parseInt8 - Booleano para habilitar el análisis de enteros de 64 bits (int8) como números JavaScript. Por defecto, los valores int8 (bigint) se devuelven como cadenas para evitar desbordamientos. Los números JavaScript son IEEE-754 y pierden precisión por encima del entero seguro máximo (Number.MAX_SAFE_INTEGER = +2^53). Si necesitas el rango completo de 64 bits, considera trabajar con las cadenas devueltas o convertirlas al tipo nativo bigint en lugar de usar esta opción.

Opciones adicionales pueden agregarse al objeto extra y se pasarán directamente a la biblioteca cliente. Ver más en la documentación de pg para Pool y Client.

Tipos de Columna

Tipos de columna para 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.

Tipos de columna para 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

Nota: CockroachDB devuelve todos los tipos de datos numéricos como string. Sin embargo, si omites el tipo de columna y defines tu propiedad como number, el ORM convertirá la cadena en número mediante parseInt.

Columnas vectoriales

Las columnas vectoriales pueden usarse para búsquedas de similitud usando operadores vectoriales de 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`

Columnas espaciales

El soporte de PostgreSQL y CockroachDB en TypeORM utiliza GeoJSON como formato de intercambio, por lo que las columnas de geometría deben etiquetarse como object o Geometry (o subclases, por ejemplo, Point) después de importar los tipos geojson o utilizando los tipos GeoJSON incorporados de TypeORM:

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 intenta hacer lo correcto, pero no siempre es posible determinar cuándo un valor que se está insertando o el resultado de una función de PostGIS debe tratarse como una geometría. Como resultado, puedes encontrarte escribiendo código similar al siguiente, donde los valores se convierten en geometrías geometry de PostGIS a partir de GeoJSON y en GeoJSON como 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()