UNPKG

@clickup/ent-framework

Version:

A PostgreSQL graph-database-alike library with microsharding and row-level security

178 lines (113 loc) 5.82 kB
[**@clickup/ent-framework**](../README.md) *** [@clickup/ent-framework](../globals.md) / Island # Class: Island\<TClient\> Defined in: [src/abstract/Island.ts:94](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L94) Island is a moderately short-lived collection of DB connections (represented as Clients) that contains a single master Client and any number of replicas. - In normal situations, you don't likely need to work with Islands directly, you can rely on higher level abstractions which support automatic rediscovery and retries: Ent (or lower level Shard and Schema). - Islands are helpful mostly when working with cross-Shards logic. - Island is somewhat temporary: if the Cluster is reconfigured in real-time, then its Island objects may be recycled and re-created, and the corresponding Clients may be ended. This also applies to any given Client instance. Don't retain and reuse those objects for too long. The reliable abstractions (resilient to disconnects, shards migration, failover etc.) start from Shard level. - There is no guarantee that the data returned by shards(), master() or replica() will be up to date. Shards may be just migrated to another Island. Master may become a replica, or vice versa. ## Type Parameters | Type Parameter | | ------ | | `TClient` *extends* [`Client`](Client.md) | ## Constructors ### new Island() > **new Island**\<`TClient`\>(`options`): [`Island`](Island.md)\<`TClient`\> Defined in: [src/abstract/Island.ts:121](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L121) Initializes the Island by copying the Client references into it. #### Parameters | Parameter | Type | | ------ | ------ | | `options` | [`IslandOptions`](../interfaces/IslandOptions.md)\<`TClient`\> | #### Returns [`Island`](Island.md)\<`TClient`\> ## Properties | Property | Type | Description | | ------ | ------ | ------ | | <a id="default_options"></a> `DEFAULT_OPTIONS` | `Required`\<`PickPartial`\<[`IslandOptions`](../interfaces/IslandOptions.md)\<[`Client`](Client.md)\>\>\> | Default values for the constructor options. | | <a id="options-1"></a> `options` | `Required`\<[`IslandOptions`](../interfaces/IslandOptions.md)\<`TClient`\>\> | Island configuration options. | ## Accessors ### no #### Get Signature > **get** **no**(): `number` Defined in: [src/abstract/Island.ts:133](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L133) Island number. ##### Returns `number` *** ### clients #### Get Signature > **get** **clients**(): readonly `TClient`[] Defined in: [src/abstract/Island.ts:140](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L140) The list of Clients in this Island. No assumptions about the order. ##### Returns readonly `TClient`[] ## Methods ### rediscover() > **rediscover**(): `Promise`\<[`SwallowedErrorLoggerProps`](../interfaces/SwallowedErrorLoggerProps.md)[]\> Defined in: [src/abstract/Island.ts:157](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L157) Queries for Shards on the best available Client (preferably master, then replicas) and stores the result internally, available for the further shards() call. - If some Clients are unavailable, tries its best to infer the data from other Clients. - The method queries ALL clients in parallel, because the caller logic anyways needs to know, who's master and who's replica, as a side effect of the very 1st query after the Client creation. We infer that as a piggy back after calling Client#shardNos(). - In case we could not discover shards, returns the list of errors happened during the discovery. #### Returns `Promise`\<[`SwallowedErrorLoggerProps`](../interfaces/SwallowedErrorLoggerProps.md)[]\> *** ### shards() > **shards**(): [`Shard`](Shard.md)\<`TClient`\>[] Defined in: [src/abstract/Island.ts:224](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L224) Returns the currently best-known Shards on this Island. This method is needed only when working with cross-Shards logic; in normal situations, it is not called much. #### Returns [`Shard`](Shard.md)\<`TClient`\>[] *** ### master() > **master**(): `TClient` Defined in: [src/abstract/Island.ts:252](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L252) Returns the currently best-known master Client among the Clients of this Island. - If all masters are unhealthy, we still return one of them and prefer not to fall back on a replica, because otherwise, we'll see non-obvious errors in logs ("can't write in a read-only Client" or so) and suspect that there is a bug in logic, although there is really no bug, it's just the master node went down. It's way better to throw a straightforward error like "Client is down". - If we can't find a master, but there is a list of Clients with unknown roles, prefer returning one of them vs. any known replica, since there is a chance that among those unknown Clients, there will be a master. - In case all Clients are read-only (replicas), still returns the 1st of them, assuming that it's better to throw at the caller side on a failed write (at worst) rather than here. It is not common to have an Island without a master Client, that happens only temporarily during failover/switchover, so the caller will likely rediscover and find a new master on a next retry. #### Returns `TClient` *** ### replica() > **replica**(): `TClient` Defined in: [src/abstract/Island.ts:279](https://github.com/clickup/ent-framework/blob/master/src/abstract/Island.ts#L279) Returns a currently best-known random replica Client. In case there are no replicas, returns the master Client. #### Returns `TClient`