Class: JDBCURI
@divine/uri-jdbc-protocol.JDBCURI
Hierarchy
DatabaseURI↳
JDBCURI
Constructors
constructor
• new JDBCURI(url?, params?)
Constructs a new URI subclass. The URI constructor is a bit unusual, as it will always return an URI subclass and never a plain URI object.
If the URI contains user information (credentials), it will be added as an AuthSelector and removed from the URI.
Parameters
| Name | Type | Description |
|---|---|---|
url? | string | URL | Url | The URL to construct. If relative, it will be resolved as a file: URL relative to the current working directory. If url is a string and params is provided, the string may contain {prop} placeholders, which will then be resolved and percent-encoded against properties in params. |
params? | Params | An optional record with parameters, used in case url is a string. |
Inherited from
DatabaseURI.constructor
Defined in
uri/build/src/uri.d.ts:182
• new JDBCURI(url?, base?, params?)
Constructs a new URI subclass. The URI constructor is a bit unusual, as it will always return an URI subclass and never a plain URI object.
If the URI contains user information (credentials), it will be added as an AuthSelector and removed from the URI.
NOTE: If base is an URI, all its selectors will be inherited by the newly constructed URI.
Parameters
| Name | Type | Description |
|---|---|---|
url? | string | URL | Url | The URL to construct. If relative, it will be resolved against base. If url is a string and params are provided, the string may contain {prop} placeholders, which will then be resolved and percent-encoded against properties in params. |
base? | string | URL | Url | A base URL that url will be resolved relative to, in case url is relative. If base itself is relative, base will first be resolved as a file: URL relative to the current working directory. Just like url, if base is a string and params is provided, {prop} placeholders may be present in the string. |
params? | Params | An optional record with parameters, used in case url and/or base is a string. |
Inherited from
DatabaseURI.constructor
Defined in
uri/build/src/uri.d.ts:201
Properties
href
• Readonly href: string
This URI's string representation. Unlike in URL, this property may not be changed/updated.
Inherited from
DatabaseURI.href
Defined in
uri/build/src/uri.d.ts:164
origin
• Readonly origin: string
This URI's origin. Unlike in URL, this property may not be changed/updated.
Inherited from
DatabaseURI.origin
Defined in
uri/build/src/uri.d.ts:166
protocol
• Readonly protocol: string
This URI's protocol. Unlike in URL, this property may not be changed/updated.
Inherited from
DatabaseURI.protocol
Defined in
uri/build/src/uri.d.ts:168
selectors
• selectors: Object
All selectors that may apply to this URI. Use addSelector to modify this property.
Type declaration
| Name | Type | Description |
|---|---|---|
auth? | AuthSelector[] | Authentication/Credentials selectors. See AuthSelector. |
headers? | HeadersSelector[] | Headers selectors. See HeadersSelector. |
params? | ParamsSelector[] | Parameter selectos. See ParamsSelector. |
session? | SessionSelector[] | Session selectors. Only used internally. |
Inherited from
DatabaseURI.selectors
Defined in
uri/build/src/uri.d.ts:153
FIELDS
▪ Static Readonly FIELDS: symbol
An alias for FIELDS.
Inherited from
DatabaseURI.FIELDS
Defined in
uri/build/src/uri.d.ts:118
FINALIZE
▪ Static Readonly FINALIZE: symbol
An alias for FIELDS.
Inherited from
DatabaseURI.FINALIZE
Defined in
uri/build/src/uri.d.ts:120
HEADERS
▪ Static Readonly HEADERS: symbol
An alias for HEADERS.
Inherited from
DatabaseURI.HEADERS
Defined in
uri/build/src/uri.d.ts:122
NULL
▪ Static Readonly NULL: symbol
An alias for NULL.
Inherited from
DatabaseURI.NULL
Defined in
uri/build/src/uri.d.ts:116
STATUS
▪ Static Readonly STATUS: symbol
An alias for STATUS.
Inherited from
DatabaseURI.STATUS
Defined in
uri/build/src/uri.d.ts:124
STATUS_TEXT
▪ Static Readonly STATUS_TEXT: symbol
An alias for STATUS_TEXT.
Inherited from
DatabaseURI.STATUS_TEXT
Defined in
uri/build/src/uri.d.ts:126
VOID
▪ Static Readonly VOID: symbol
An alias for VOID.
Inherited from
DatabaseURI.VOID
Defined in
uri/build/src/uri.d.ts:114
Methods
$
▸ $(strings, ...values): DatabaseURI
Constructs a new DatabaseURI, relative to this URI, from a template string, percent-encoding all arguments.
Example:
const base = new URI('sqlite:/tmp/demo.db');
const info = await base.$`#item_info?(eq,id,${item})`.load();
Throws
TypeError If the resulting URI is not actually a DatabaseURI.
Parameters
| Name | Type | Description |
|---|---|---|
strings | TemplateStringsArray | The template string array. |
...values | unknown[] | The values to be encoded. |
Returns
DatabaseURI
A new DatabaseURI subclass instance.
Inherited from
DatabaseURI.$
Defined in
uri/build/src/protocols/database.d.ts:524
[asyncIterator]
▸ [asyncIterator](): AsyncIterator<Buffer, any, undefined> & Metadata
All URIs are AsyncIterable<Buffer>. This method implements that interface by calling
load(stream).
Returns
AsyncIterator<Buffer, any, undefined> & Metadata
An AsyncIterator<Buffer> stream.
Inherited from
DatabaseURI.[asyncIterator]
Defined in
uri/build/src/uri.d.ts:393
_createDBConnectionPool
▸ Protected _createDBConnectionPool(params): Promise<DBConnectionPool>
Parameters
| Name | Type |
|---|---|
params | DBParamsSelector |
Returns
Promise<DBConnectionPool>
Overrides
DatabaseURI._createDBConnectionPool
Defined in
uri-jdbc-protocol/src/jdbc-protocol.ts:7
_getAuthorization
▸ Protected _getAuthorization(req, payload?, challenges?): Promise<undefined | Authorization>
Parameters
| Name | Type |
|---|---|
req | AuthSchemeRequest |
payload? | Buffer | AsyncIterable<Buffer> |
challenges? | WWWAuthenticate[] |
Returns
Promise<undefined | Authorization>
Inherited from
DatabaseURI._getAuthorization
Defined in
uri/build/src/uri.d.ts:394
_getBestSelector
▸ Protected _getBestSelector<T>(sels, challenge?): null | T
Type parameters
| Name | Type |
|---|---|
T | extends SelectorBase |
Parameters
| Name | Type |
|---|---|
sels | undefined | T[] |
challenge? | WWWAuthenticate |
Returns
null | T
Inherited from
DatabaseURI._getBestSelector
Defined in
uri/build/src/uri.d.ts:397
_guessContentType
▸ Protected _guessContentType(knownContentType?): undefined | ContentType
Parameters
| Name | Type |
|---|---|
knownContentType? | string | ContentType |
Returns
undefined | ContentType
Inherited from
DatabaseURI._guessContentType
Defined in
uri/build/src/uri.d.ts:395
_makeIOError
▸ Protected _makeIOError(err): IOError
Parameters
| Name | Type |
|---|---|
err | unknown |
Returns
IOError
Inherited from
DatabaseURI._makeIOError
Defined in
uri/build/src/uri.d.ts:396
addSelector
▸ addSelector<T>(selector): JDBCURI
Adds a new selector to this URI.
Selectors is a way to specify in what situations some kind of parameters or configuration is valid. When some kind of configuration is required (such as authentication of connection parameters), all registered selectors are evaluated and based on the matching score, the best selector is chosen. The more specific a selector is, the higher the score it will receive if it matches.
Based on this, it's possible to limit the scope of credentials or to configure certain HTTP headers to be sent to a specific set of servers.
It's also perfectly valid not to specify a selector for some kind of parameters. As long as there is only one kind of this configuration, it will apply unconditionally.
Throws
TypeError If the selector to add is invalid.
Type parameters
| Name | Type |
|---|---|
T | extends AuthSelector | HeadersSelector | ParamsSelector | SessionSelector |
Parameters
| Name | Type | Description |
|---|---|---|
selector | T | The selector to add. |
Returns
This URI.
Inherited from
DatabaseURI.addSelector
Defined in
uri/build/src/uri.d.ts:235
append
▸ append<T, D>(data, _sendCT?, _recvCT?): Promise<T & DBMetadata>
Uses the DB reference in this URI's fragment to add one or multiple rows in a table using INSERT.
Throws
IOError On I/O errors or if this URI does not have a valid DB reference fragment.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | The actual type returned. |
D | unknown | The type of data to store. |
Parameters
| Name | Type | Description |
|---|---|---|
data | D | The data to add to the table. |
_sendCT? | string | ContentType | Must not be used. |
_recvCT? | string | ContentType | Must not be used. |
Returns
Promise<T & DBMetadata>
A row or array of rows (if the database supports it), with DBMetadata.
Inherited from
DatabaseURI.append
Defined in
uri/build/src/protocols/database.d.ts:562
close
▸ close(): Promise<void>
Shuts down the database connection pool.
Throws
IOError On I/O errors.
Returns
Promise<void>
Inherited from
DatabaseURI.close
Defined in
uri/build/src/protocols/database.d.ts:757
info
▸ info<T>(): Promise<T & Metadata>
This method will return information about the resource this URI references, if the subclass supports it.
The actual operation depends on what kind of URI this is. See FileURI.info or HTTPURI.info for two common examples.
Throws
IOError On I/O errors or if the subclass does not support this method.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends DirectoryEntry | The actual type of information record returned. Must extend DirectoryEntry. |
Returns
Promise<T & Metadata>
An information record describing the resources.
Inherited from
DatabaseURI.info
Defined in
uri/build/src/uri.d.ts:246
list
▸ list<T>(): Promise<T[] & Metadata>
This method will return information about this URI's children/subresources, if the subclass supports it.
The actual operation depends on what kind of URI this is. See FileURI.info for a common example.
Throws
IOError On I/O errors or if the subclass does not support this method.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends DirectoryEntry | The actual type of information record returned. Must extend DirectoryEntry. |
Returns
Promise<T[] & Metadata>
An array of information record describing the subresources.
Inherited from
DatabaseURI.list
Defined in
uri/build/src/uri.d.ts:256
load
▸ load<T>(_recvCT?): Promise<T & DBMetadata>
Uses the DB reference in this URI's fragment to retrieve one or multiple rows or a single cell from a table
with SELECT.
Throws
IOError On I/O errors or if this URI does not have a valid DB reference fragment.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | The actual type returned. |
Parameters
| Name | Type | Description |
|---|---|---|
_recvCT? | string | ContentType | Must not be used. |
Returns
Promise<T & DBMetadata>
A cell, row or array of rows, with DBMetadata.
Inherited from
DatabaseURI.load
Defined in
uri/build/src/protocols/database.d.ts:535
modify
▸ modify<T, D>(data, _sendCT?, _recvCT?): Promise<T & DBMetadata>
Uses the DB reference in this URI's fragment to modify one or multiple rows in a table using UPDATE.
Throws
IOError On I/O errors or if this URI does not have a valid DB reference fragment.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | Object. |
D | unknown | The type of the update data. |
Parameters
| Name | Type | Description |
|---|---|---|
data | D | The data to update in the table. |
_sendCT? | string | ContentType | Must not be used. |
_recvCT? | string | ContentType | Must not be used. |
Returns
Promise<T & DBMetadata>
Object(VOID), with DBMetadata.
Inherited from
DatabaseURI.modify
Defined in
uri/build/src/protocols/database.d.ts:575
query
▸ query<T>(...queries): Promise<T & DBMetadata>
Executes one or more queries in the same session.
Throws
TypeError If the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object = object[] | The actual type returned. Always an array. |
Parameters
| Name | Type | Description |
|---|---|---|
...queries | DBQuery[] | The queries to execute. |
Returns
Promise<T & DBMetadata>
An array of rows from the last query. All result sets are available as a DBResult array via FIELDS (from the DBMetadata).
Inherited from
DatabaseURI.query
Defined in
uri/build/src/protocols/database.d.ts:597
▸ query<T>(query, ...params): Promise<T & DBMetadata>
Executes a query in the form of a template literal.
All values/parameters will either be quoted and encoded or sent separately to the database server for processing, depending on the actual database driver. Example:
const users = dbURI.query<User>[]>`select * from users where first_name = ${firstName}`;
See also q, q.quote, q.raw, q.join, q.list, q.values and q.assign for handy utility functions.
Throws
TypeError If one of the parameters is undefined or if the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object = object[] | The actual type returned. Always an array. |
Parameters
| Name | Type | Description |
|---|---|---|
query | TemplateStringsArray | The query as a template string array. |
...params | BasicTypes[] | The query parameters. Values may be DBQuery instances or of any type supported by the database. |
Returns
Promise<T & DBMetadata>
An array of rows. The raw set is available as a DBResult array — of length 1 — via FIELDS (from the DBMetadata).
Inherited from
DatabaseURI.query
Defined in
uri/build/src/protocols/database.d.ts:621
▸ query<T>(query, params): Promise<T & DBMetadata>
Executes a query in the form of a query string. The string may contain {prop} placeholders, which will then be
resolved against properties in params.
All values/parameters will either be quoted and encoded or sent separately to the database server for processing, depending on the actual database driver. Example:
const users = dbURI.query<User>[]>('select * from users where first_name = {name}', { name: firstName });
See also q, q.quote, q.raw, q.join, q.list, q.values and q.assign for handy utility functions.
Throws
TypeError If one of the parameters is undefined or if the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object = object[] | The actual type returned. Always an array. |
Parameters
| Name | Type | Description |
|---|---|---|
query | string | The query, with {prop} placeholders for parameters. |
params | Params | An record with parameters, used to look up placeholders from the query. Parameters may be DBQuery instances themselves, or of any type supported by the database. |
Returns
Promise<T & DBMetadata>
An array of rows. The raw set is available as a DBResult array — of length 1 — via FIELDS (from the DBMetadata).
Inherited from
DatabaseURI.query
Defined in
uri/build/src/protocols/database.d.ts:646
▸ query<T>(params, cb): Promise<T>
Begins a transaction and evaluates the provided callback.
If the callback returns successfully, the transaction is committed and this method returns the callback's return value; if the callback throws, the transaction is rolled back and the exception is propagated.
Transaction deadlocks are handled automatically by default. When the driver detects that a transaction was
aborted because of a deadlock, it waits a little based on the DBTransactionParams.backoff function, and
then invokes the callback again (the retryCount argument will be 1 on the first retry and so on), up to a
maximum of DBTransactionParams.retries times. Only then will the deadlock exception be propagated. To
this behaviour, set retry to 0.
If this method is called recursively, savepoints will be created (and rolled back) instead of transactions, and
params will be silently ignored. The retryCount argument is set to null in this case.
Throws
TypeError if the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Throws
unknown Any exception thrown by cb is propagated.
Type parameters
| Name | Description |
|---|---|
T | The return type of the callback. |
Parameters
| Name | Type | Description |
|---|---|---|
params | DBTransactionParams | Transaction options, specifying the number of retries on deadlocks, the backoff strategey or transaction isolation level. |
cb | DBCallback<T> | The function to evaluate inside the transaction/savepoint. |
Returns
Promise<T>
Whatever cb returns.
Inherited from
DatabaseURI.query
Defined in
uri/build/src/protocols/database.d.ts:672
▸ query<T>(cb): Promise<T>
Begins a transaction and evaluates the provided callback.
If the callback returns successfully, the transaction is committed and this method returns the callback's return value; if the callback throws, the transaction is rolled back and the exception is propagated.
Transaction deadlocks are handled automatically. When the driver detects that a transaction was aborted because
of a deadlock, it waits a few hundred milliseconds, and then invokes the callback again (the retryCount
argument will be 1 on the first retry and so on), up to a maximum of 8 times. Only then will the deadlock
exception be propagated. The wait time is approximately doubled on each retry, up to around 12 seconds.
If this method is called recursively, savepoints will be created (and rolled back) instead of transactions. The
retryCount argument is set to null in this case.
Throws
TypeError if the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Throws
unknown Any exception thrown by cb is propagated.
Type parameters
| Name | Description |
|---|---|
T | The return type of the callback. |
Parameters
| Name | Type | Description |
|---|---|---|
cb | DBCallback<T> | The function to evaluate inside the transaction/savepoint. |
Returns
Promise<T>
Whatever cb returns.
Inherited from
DatabaseURI.query
Defined in
uri/build/src/protocols/database.d.ts:695
remove
▸ remove<T>(_recvCT?): Promise<T & DBMetadata>
Uses the DB reference in this URI's fragment to remove one or multiple rows from a table using DELETE.
Throws
IOError On I/O errors or if this URI does not have a valid DB reference fragment.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | Object. |
Parameters
| Name | Type | Description |
|---|---|---|
_recvCT? | string | ContentType | Must not be used. |
Returns
Promise<T & DBMetadata>
Object(VOID), with DBMetadata.
Inherited from
DatabaseURI.remove
Defined in
uri/build/src/protocols/database.d.ts:585
save
▸ save<T, D>(data, _sendCT?, _recvCT?): Promise<T & DBMetadata>
Uses the DB reference in this URI's fragment to store one or multiple rows in a table using upsert semantics
(using INSERT ... ON CONFLICT UPDATE ... or UPSERT, for instance, but this depends on the database).
Throws
IOError On I/O errors or if this URI does not have a valid DB reference fragment.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | The actual type returned. |
D | unknown | The type of data to store. |
Parameters
| Name | Type | Description |
|---|---|---|
data | D | The data to store in a row (or an array of rows to store). |
_sendCT? | string | ContentType | Must not be used. |
_recvCT? | string | ContentType | Must not be used. |
Returns
Promise<T & DBMetadata>
A row or array of rows (if the database supports it), with DBMetadata.
Inherited from
DatabaseURI.save
Defined in
uri/build/src/protocols/database.d.ts:549
watch
▸ watch<T>(query): AsyncIterable<T & DBMetadata>
Opens a change data capture channel to the database and returns a stream of change events.
Example:
for await (const ev of dbURI.watch(q`listen foo`)) {
console.log('New PostgreSQL notification', ev);
}
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | The type of events that will be emitted. |
Parameters
| Name | Type | Description |
|---|---|---|
query | DBQuery | The query that opens the change event stream. |
Returns
AsyncIterable<T & DBMetadata>
A stream of change events.
Inherited from
DatabaseURI.watch
Defined in
uri/build/src/protocols/database.d.ts:713
▸ watch<T>(query, ...params): AsyncIterable<T & DBMetadata>
Opens a change data capture channel to the database and returns a stream of change events.
for await (const ev of dbURI.watch`experimental changefeed FOR orders`) {
console.log('New order from CockroachDB', ev);
}
Throws
TypeError If one of the parameters is undefined or if the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | The type of events that will be emitted. |
Parameters
| Name | Type | Description |
|---|---|---|
query | TemplateStringsArray | The query that opens the change event stream. |
...params | unknown[] | The query parameters. Values may be DBQuery instances or of any type supported by the database. |
Returns
AsyncIterable<T & DBMetadata>
A stream of change events.
Inherited from
DatabaseURI.watch
Defined in
uri/build/src/protocols/database.d.ts:732
▸ watch<T>(query, params): AsyncIterable<T & DBMetadata>
Opens a change data capture channel to the database and returns a stream of change events.
for await (const ev of dbURI.watch('experimental changefeed FOR orders', {})) {
console.log('New order from CockroachDB', ev);
}
Throws
TypeError If one of the parameters is undefined or if the arguments are invalid.
Throws
IOError On I/O errors.
Throws
DBError On database/query errors.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends object | The type of events that will be emitted. |
Parameters
| Name | Type | Description |
|---|---|---|
query | string | The query that opens the change event stream, with {prop} placeholders for parameters. |
params | Params | An record with parameters, used to look up placeholders from the query. Parameters may be DBQuery instances themselves, or of any type supported by the database. |
Returns
AsyncIterable<T & DBMetadata>
A stream of change events.
Inherited from
DatabaseURI.watch
Defined in
uri/build/src/protocols/database.d.ts:751
$
▸ Static $(strings, ...values): URI
Creates a new URI from a template string, percent-encoding all arguments.
Example:
const href = URI.$`http://${host}/blobs/${blob}?as=${ct}
Parameters
| Name | Type | Description |
|---|---|---|
strings | TemplateStringsArray | The template string array. |
...values | unknown[] | The values to be encoded. |
Returns
URI
A new URI subclass instance.
Inherited from
DatabaseURI.$
Defined in
uri/build/src/uri.d.ts:148
register
▸ Static register(protocol, uri): typeof URI
Registers a new URI protocol. All subclasses must register their URL protocol support with this method.
Parameters
| Name | Type | Description |
|---|---|---|
protocol | string | The URL protocol to register. Must include the trailing colon. |
uri | typeof URI | The URI subclass. |
Returns
typeof URI
The URI baseclass (for chaining).
Inherited from
DatabaseURI.register
Defined in
uri/build/src/uri.d.ts:134