Skip to main content
Home
Browse packagesDocs
ImageSign In with GitHubImageSign In with GitLab

@db/postgres@0.19.5
Built and signed on GitHub Actions

latest
denodrivers/postgres
Works with
This package works with Deno
This package works with Deno
•JSR Score100%•
Downloads822/wk
•
Published11 months ago (0.19.5)

Lightweight PostgreSQL driver for Deno

Classes

c
Client(config?: ClientOptions | ConnectionString)

Clients allow you to communicate with your PostgreSQL database and execute SQL statements asynchronously

c
ConnectionError(message?: string)

A connection error

c
Pool(
connection_params: ClientOptions | ConnectionString | undefined,
size: number,
lazy?: boolean
)

Connection pools are a powerful resource to execute parallel queries and save up time in connection initialization. It is highly recommended that all applications that require concurrent access use a pool to communicate with their PostgreSQL database

  • available(): number

    The number of open connections available for use

  • connect(): Promise<PoolClient>

    This will return a new client from the available connections in the pool

  • end(): Promise<void>

    This will close all open connections and set a terminated status in the pool

  • initialized(): Promise<number>

    This will return the number of initialized clients in the pool

  • size(): number

    The number of total connections open in the pool

c
PoolClient(
config: ClientConfiguration,
releaseCallback: () => void
)

A client used specifically by a connection pool

  • release(): void

    Releases the client back to the pool

c
PostgresError(
fields: Notice,
query?: string
)

A Postgres database error

  • fields: Notice

    The fields of the notice message

  • query: string | undefined

    The query that caused the error

c
QueryArrayResult

This class is used to handle the result of a query that returns an array

  • insertRow(
    row_data: Uint8Array[],
    controls?: ClientControls
    ): void

    Insert a row into the result

  • rows: T[]

    The result rows

c
QueryClient(connection: Connection)

An abstract class used to define common database client properties and methods

  • closeConnection(): Promise<void>

    Close the connection to the database

  • connect(): Promise<void>

    Every client must initialize their connection previously to the execution of any statement

  • connected(): boolean

    Indicates if the client is currently connected to the database

  • createTransaction(
    name: string,
    options?: TransactionOptions
    ): Transaction

    Transactions are a powerful feature that guarantees safe operations by allowing you to control the outcome of a series of statements and undo, reset, and step back said operations to your liking

  • end(): Promise<void>

    Closing your PostgreSQL connection will delete all non-persistent data that may have been created in the course of the session and will require you to reconnect in order to execute further queries

  • queryArray<T extends Array<unknown>>(
    query: string,
    args?: QueryArguments
    ): Promise<QueryArrayResult<T>>

    Execute queries and retrieve the data as array entries. It supports a generic in order to type the entries retrieved by the query

  • queryObject<T>(
    query: string,
    args?: QueryArguments
    ): Promise<QueryObjectResult<T>>

    Executed queries and retrieve the data as object entries. It supports a generic in order to type the entries retrieved by the query

  • resetSessionMetadata(): void

    Resets the transaction session metadata

  • session(): Session

    The current session metadata

c
QueryObjectResult

This class is used to handle the result of a query that returns an object

  • columns: string[]

    The column names will be undefined on the first run of insertRow, since

  • insertRow(
    row_data: Uint8Array[],
    controls?: ClientControls
    ): void

    Insert a row into the result

  • rows: T[]

    The rows of the result

c
QueryResult(query: Query<ResultType>)

This class is used to handle the result of a query

  • command: CommandType

    Type of query executed for this result

  • handleCommandComplete(commandTag: string): void

    Handles the command complete message

  • insertRow(_row: Uint8Array[]): void

    Add a row to the result based on metadata provided by rowDescription This implementation depends on row description not being modified after initialization

  • loadColumnDescriptions(description: RowDescription): void

    This function is required to parse each column of the results

  • rowCount: number

    The amount of rows affected by the query

  • rowDescription(): RowDescription | undefined

    The row description of the result

  • warnings: Notice[]

    The warnings of the result

c
RowDescription(
columnCount: number,
columns: Column[]
)

Class to describe a row

c
Savepoint(
name: string,
update_callback: (name: string) => Promise<void>,
release_callback: (name: string) => Promise<void>
)

A savepoint is a point in a transaction that you can roll back to

  • instances(): number

    This is the count of the current savepoint instances in the transaction

  • release(): Promise<void>

    Releasing a savepoint will remove it's last instance in the transaction

  • update(): Promise<void>

    Updating a savepoint will update its position in the transaction execution

c
Transaction(
name: string,
options: TransactionOptions | undefined,
client: QueryClient,
execute_query_callback: (query: Query<ResultType>) => Promise<QueryResult>,
update_client_lock_callback: (name: string | null) => void
)

A transaction class

  • begin(): Promise<void>

    The begin method will officially begin the transaction, and it must be called before any query or transaction operation is executed in order to lock the session

  • commit(options?: { chain?: boolean; }): Promise<void>

    The commit method will make permanent all changes made to the database in the current transaction and end the current transaction

  • getSavepoint(name: string): Savepoint | undefined

    This method will search for the provided savepoint name and return a reference to the requested savepoint, otherwise it will return undefined

  • getSavepoints(): string[]

    This method will list you all of the active savepoints in this transaction

  • getSnapshot(): Promise<string>

    This method returns the snapshot id of the on going transaction, allowing you to share the snapshot state between two transactions

  • isolation_level(): IsolationLevel

    Get the isolation level of the transaction

  • queryArray<T extends Array<unknown>>(
    query: string,
    args?: QueryArguments
    ): Promise<QueryArrayResult<T>>

    This method allows executed queries to be retrieved as array entries. It supports a generic interface in order to type the entries retrieved by the query

  • queryObject<T>(
    query: string,
    args?: QueryArguments
    ): Promise<QueryObjectResult<T>>

    Executed queries and retrieve the data as object entries. It supports a generic in order to type the entries retrieved by the query

  • rollback(): Promise<void>

    Rollbacks are a mechanism to undo transaction operations without compromising the data that was modified during the transaction.

  • savepoint(name: string): Promise<Savepoint>

    This method will generate a savepoint, which will allow you to reset transaction states to a previous point of time

  • savepoints(): Savepoint[]

    Get all the savepoints of the transaction

c
TransactionError(
transaction_name: string,
cause: PostgresError
)

A transaction error

Enums

E
ResultType

Type of a query result

Interfaces

I
ConnectionOptions

Additional granular database connection options

  • attempts: number

    By default, any client will only attempt to stablish connection with your database once. Setting this parameter will cause the client to attempt reconnection as many times as requested before erroring

  • interval: number | ((previous_interval: number) => number)

    The time to wait before attempting each reconnection (in milliseconds)

I
Notice

The notice interface defining the fields of a notice message

  • code: string

    The notice code

  • column: string

    The column name

  • constraint: string

    The constraint name

  • dataType: string

    The data type name

  • detail: string

    The additional notice detail

  • file: string

    The file name

  • hint: string

    The notice hint descrip=bing possible ways to fix this notice

  • internalPosition: string

    The internal position of code that triggered the notice

  • internalQuery: string

    The internal query that triggered the notice

  • line: string

    The line number

  • message: string

    The notice message

  • position: string

    The position of code that triggered the notice

  • routine: string

    The routine name

  • schema: string

    The database schema

  • severity: string

    The notice severity level

  • table: string

    The table name

  • where: string

    The where metadata

I
QueryObjectOptions

Options to control the behavior of a Query instance

  • camelCase: boolean

    Enabling camel case will transform any snake case field names coming from the database into camel case ones

  • fields: string[]

    This parameter supersedes query column names coming from the databases in the order they were provided. Fields must be unique and be in the range of (a-zA-Z0-9_), otherwise the query will throw before execution. A field can not start with a number, just like JavaScript variables

I
QueryOptions

Types of options

  • args: QueryArguments

    The arguments to be passed to the query

  • encoder: (arg: unknown) => EncodedArg

    A custom function to override the encoding logic of the arguments passed to the query

  • name: string

    The name of the query statement

  • text: string

    The query statement to be executed

I
Session

The Session representing the current state of the connection

  • current_transaction: string | null

    This is the code for the transaction currently locking the connection. If there is no transaction ongoing, the transaction code will be null

  • pid: number | undefined

    This is the process id of the current session as assigned by the database on connection. This id will undefined when there is no connection stablished

  • tls: boolean | undefined

    Indicates if the connection is being carried over TLS. It will be undefined when there is no connection stablished

  • transport: "tcp" | "socket" | undefined

    This indicates the protocol used to connect to the database

I
TLSOptions

The Transport Layer Security (TLS) protocol options to be used by the database connection

  • caCertificates: string[]

    A list of root certificates that will be used in addition to the default root certificates to verify the server's certificate.

  • enabled: boolean

    If TLS support is enabled or not. If the server requires TLS, the connection will fail.

  • enforce: boolean

    Forces the connection to run over TLS If the server doesn't support TLS, the connection will fail

Type Aliases

T
ClientOptions = { applicationName?: string; connection?: Partial<ConnectionOptions>; controls?: ClientControls; database?: string; hostname?: string; host_type?: "tcp" | "socket"; options?: string | Record<string, string>; password?: string; port?: string | number; tls?: Partial<TLSOptions>; user?: string; }

The Client database connection options

T
CommandType =
"INSERT"
| "DELETE"
| "UPDATE"
| "SELECT"
| "MOVE"
| "FETCH"
| "COPY"
| "CREATE"

Type of query to be executed

T
ConnectionString = string

The connection string must match the following URI structure. All parameters but database and user are optional

T
Decoders = [key in number | OidType]?: DecoderFunction

A dictionary of functions used to decode (parse) column field values from string to a custom type. These functions will take precedence over the DecodeStrategy. Each key in the dictionary is the column OID type number or Oid type name, and the value is the decoder function.

T
DecodeStrategy = "string" | "auto"

The strategy to use when decoding results data

T
IsolationLevel = "read_committed" | "repeatable_read" | "serializable"

The isolation level of a transaction to control how we determine the data integrity between transactions

T
OidType = keyof Oid

A Postgres Object identifiers (OIDs) type name.

T
OidValue = (Oid)[OidType]

A Postgres Object identifiers (OIDs) numeric value.

T
QueryArguments = unknown[] | Record<string, unknown>

Types of arguments passed to a query

T
TransactionOptions = { isolation_level?: IsolationLevel; read_only?: boolean; snapshot?: string; }

Type of the transaction options

Variables

v
Oid: { bool: number; bytea: number; char: number; name: number; int8: number; int2: number; _int2vector_0: number; int4: number; regproc: number; text: number; oid: number; tid: number; xid: number; _cid_0: number; _oidvector_0: number; _pg_ddl_command: number; _pg_type: number; _pg_attribute: number; _pg_proc: number; _pg_class: number; json: number; _xml_0: number; _xml_1: number; _pg_node_tree: number; json_array: number; _smgr: number; _index_am_handler: number; point: number; lseg: number; path: number; box: number; polygon: number; line: number; line_array: number; cidr: number; cidr_array: number; float4: number; float8: number; _abstime_0: number; _reltime_0: number; _tinterval_0: number; _unknown: number; circle: number; circle_array: number; _money_0: number; _money_1: number; macaddr: number; inet: number; bool_array: number; byte_array: number; char_array: number; name_array: number; int2_array: number; _int2vector_1: number; int4_array: number; regproc_array: number; text_array: number; tid_array: number; xid_array: number; _cid_1: number; _oidvector_1: number; bpchar_array: number; varchar_array: number; int8_array: number; point_array: number; lseg_array: number; path_array: number; box_array: number; float4_array: number; float8_array: number; _abstime_1: number; _reltime_1: number; _tinterval_1: number; polygon_array: number; oid_array: number; _aclitem_0: number; _aclitem_1: number; macaddr_array: number; inet_array: number; bpchar: number; varchar: number; date: number; time: number; timestamp: number; timestamp_array: number; date_array: number; time_array: number; timestamptz: number; timestamptz_array: number; _interval_0: number; _interval_1: number; numeric_array: number; _pg_database: number; _cstring_0: number; timetz: number; timetz_array: number; _bit_0: number; _bit_1: number; _varbit_0: number; _varbit_1: number; numeric: number; _refcursor_0: number; _refcursor_1: number; regprocedure: number; regoper: number; regoperator: number; regclass: number; regtype: number; regprocedure_array: number; regoper_array: number; regoperator_array: number; regclass_array: number; regtype_array: number; _record_0: number; _cstring_1: number; _any: number; _anyarray: number; void: number; _trigger: number; _language_handler: number; _internal: number; _opaque: number; _anyelement: number; _record_1: number; _anynonarray: number; _pg_authid: number; _pg_auth_members: number; _txid_snapshot_0: number; uuid: number; uuid_array: number; _txid_snapshot_1: number; _fdw_handler: number; _pg_lsn_0: number; _pg_lsn_1: number; _tsm_handler: number; _anyenum: number; _tsvector_0: number; _tsquery_0: number; _gtsvector_0: number; _tsvector_1: number; _gtsvector_1: number; _tsquery_1: number; regconfig: number; regconfig_array: number; regdictionary: number; regdictionary_array: number; jsonb: number; jsonb_array: number; _anyrange: number; _event_trigger: number; _int4range_0: number; _int4range_1: number; _numrange_0: number; _numrange_1: number; _tsrange_0: number; _tsrange_1: number; _tstzrange_0: number; _tstzrange_1: number; _daterange_0: number; _daterange_1: number; _int8range_0: number; _int8range_1: number; _pg_shseclabel: number; regnamespace: number; regnamespace_array: number; regrole: number; regrole_array: number; }

A map of OidType to OidValue.

v
OidTypes: [key in OidValue]: OidType

A map of OidValue to OidType. Used to decode values and avoid search iteration.

Report package

Please provide a reason for reporting this package. We will review your report and take appropriate action.

Please review the JSR usage policy before submitting a report.

Add Package

deno add jsr:@db/postgres

Import symbol

import * as mod from "@db/postgres";
or

Import directly with a jsr specifier

import * as mod from "jsr:@db/postgres";