Vai al contenuto principale

Postgres / CockroachDB

Traduzione Beta Non Ufficiale

Questa pagina è stata tradotta da PageTurner AI (beta). Non ufficialmente approvata dal progetto. Hai trovato un errore? Segnala problema →

PostgreSQL, CockroachDB e Amazon Aurora Postgres sono supportati come driver di TypeORM.

I database compatibili con PostgreSQL possono essere utilizzati con TypeORM tramite il tipo di data source postgres.

Per utilizzare YugabyteDB, consultare la loro documentazione ORM per iniziare. Nota che poiché alcune funzionalità Postgres non sono supportate da YugabyteDB, alcune funzionalità di TypeORM potrebbero essere limitate.

Installazione​

npm install pg

Per il supporto allo streaming:

npm install pg-query-stream

Opzioni Data Source​

Consulta Opzioni del Data Source per le opzioni comuni del data source. Puoi utilizzare il tipo di data source postgres, cockroachdb o aurora-postgres per connetterti ai rispettivi database.

  • url - URL di connessione dove viene stabilita la connessione. Si noti che altre opzioni del data source sovrascriveranno i parametri impostati tramite l'URL.

  • host - Host del database.

  • port - Porta dell'host del database. La porta predefinita di Postgres è 5432.

  • username - Nome utente del database.

  • password - Password del database.

  • database - Nome del database.

  • schema - Nome dello schema. Il valore predefinito è "public".

  • connectTimeoutMS - Millisecondi prima che si verifichi un timeout durante la connessione iniziale al server Postgres. Se undefined o impostato a 0, non c'è timeout. Predefinito: undefined.

  • ssl - Oggetto con parametri SSL. Vedi TLS/SSL.

  • uuidExtension - Estensione Postgres da utilizzare per generare UUID. Predefinita: uuid-ossp. Può essere cambiata in pgcrypto se l'estensione uuid-ossp non è disponibile.

  • poolErrorHandler - Funzione chiamata quando il pool sottostante emette un evento 'error'. Accetta un singolo parametro (istanza dell'errore) e per default registra con livello warn.

  • maxTransactionRetries - Numero massimo di tentativi di transazione in caso di errore 40001. Predefinito: 5.

  • logNotifications - Booleano per determinare se i messaggi di notice e gli eventi di notifica del server Postgres devono essere inclusi nei log del client con livello info (default: false).

  • installExtensions - Booleano per controllare se installare automaticamente le estensioni Postgres necessarie (default: true).

  • extensions - Elenco di estensioni Postgres aggiuntive da installare nel database (default: undefined).

  • applicationName - Stringa visibile in statistiche e log per associare un'applicazione a una connessione (default: undefined).

  • parseInt8 - Booleano per abilitare l'analisi di interi a 64 bit (int8) come numeri JavaScript. Di default, i valori int8 (bigint) vengono restituiti come stringhe per evitare overflow. I numeri JavaScript sono IEEE-754 e perdono precisione oltre il massimo intero sicuro (Number.MAX_SAFE_INTEGER = +2^53). Se serve l'intera gamma a 64 bit, considera di lavorare con le stringhe restituite o convertirle in bigint nativo invece di usare questa opzione.

Opzioni aggiuntive possono essere aggiunte all'oggetto extra e verranno passate direttamente alla libreria client. Vedi la documentazione di pg per Pool e Client.

Tipi di Colonna​

Tipi di colonna per 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

Tipi di colonna per 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 restituisce tutti i tipi di dati numerici come string. Tuttavia, se ometti il tipo di colonna e definisci la tua proprietà come number, l'ORM convertirà la stringa in numero tramite parseInt.

Colonne vettoriali​

Le colonne vettoriali possono essere utilizzate per ricerche di similarità usando gli operatori vettoriali di 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`

Colonne spaziali​

Il supporto di PostgreSQL e CockroachDB in TypeORM utilizza GeoJSON come formato di interscambio, quindi le colonne di geometria dovrebbero essere tipizzate come object o Geometry (o sottoclassi, ad esempio Point) dopo aver importato i tipi geojson o utilizzato i tipi GeoJSON integrati in 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 cerca di comportarsi correttamente, ma non è sempre possibile determinare quando un valore inserito o il risultato di una funzione PostGIS debba essere trattato come una geometria. Di conseguenza, potresti trovarti a scrivere codice simile al seguente, dove i valori vengono convertiti in geometry PostGIS da GeoJSON e in GeoJSON come 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()