Skip to content

Commit 16458e6

Browse files
committed
docs: Add YugabyteDB smart driver features to Sequelize documentation
- Added note about smart driver features in Step 2 - New section: Using YugabyteDB Smart Driver features - Load balancing configuration and modes - Topology awareness for multi-region deployments - Connection string examples with smart driver parameters - Environment variables reference table - Examples showing how to enable load balancing with process.env - Documentation for all PGLOADBALANCE modes - Examples for topology-aware routing - Complete environment variables reference This update helps developers leverage YugabyteDB's smart driver capabilities for better performance, high availability, and geo-distributed applications.
1 parent f529c35 commit 16458e6

File tree

1 file changed

+104
-0
lines changed

1 file changed

+104
-0
lines changed

docs/content/stable/develop/drivers-orms/nodejs/sequelize.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,16 @@ The following code creates an Employees model to store and retrieve employee inf
8888
- The actual table is created by calling the `Employee.sync()` API in the `createTableAndInsert()` function. This also inserts the data for three employees into the table using the `Employee.create()` API.
8989
- Finally, you can retrieve the information of all employees using `Employee.findAll()`.
9090
91+
{{< note title="YugabyteDB Smart Driver Features" >}}
92+
The `sequelize-yugabytedb` package uses the YugabyteDB smart driver (`@yugabytedb/pg`) which provides advanced features like:
93+
94+
- **Load Balancing**: Automatically distribute queries across cluster nodes
95+
- **Topology Awareness**: Route queries based on node location and availability
96+
- **Connection Management**: Automatic failover and node discovery
97+
98+
These features are configured via environment variables or connection parameters. See the examples below for configuration options.
99+
{{< /note >}}
100+
91101
Add the code in the `example.js` file.
92102
93103
```js
@@ -189,6 +199,100 @@ Employees Details:
189199
]
190200
```
191201
202+
## Using YugabyteDB Smart Driver features
203+
204+
The `sequelize-yugabytedb` package includes the YugabyteDB smart driver which provides cluster-aware connection management. You can enable these features using environment variables or configuration parameters.
205+
206+
### Load balancing
207+
208+
Configure load balancing to distribute queries across all nodes in your YugabyteDB cluster:
209+
210+
```js
211+
const { Sequelize, DataTypes } = require('sequelize-yugabytedb')
212+
213+
// Set load balancing before creating connection
214+
process.env.PGLOADBALANCE = 'any'; // Options: any, prefer-primary, prefer-rr, only-primary, only-rr
215+
process.env.PGYBSERVERSREFRESHINTERVAL = '5'; // Refresh cluster topology every 5 seconds
216+
217+
const sequelize = new Sequelize('yugabyte', 'yugabyte', 'yugabyte', {
218+
host: 'localhost',
219+
port: '5433',
220+
dialect: 'postgres'
221+
})
222+
```
223+
224+
**Load balance modes:**
225+
226+
- `any`: Distribute queries across all nodes (recommended for best performance)
227+
- `prefer-primary`: Prefer primary nodes, fall back to read replicas
228+
- `prefer-rr`: Prefer read replicas, fall back to primary nodes
229+
- `only-primary`: Use only primary nodes
230+
- `only-rr`: Use only read replica nodes
231+
232+
### Topology awareness
233+
234+
For multi-region deployments, use topology awareness to route queries to nodes in specific regions or zones:
235+
236+
```js
237+
// Route queries to nodes in specific cloud region/zone
238+
process.env.PGTOPOLOGYKEYS = 'aws.us-east-2.us-east-2a';
239+
process.env.PGFALLBACKTOTOPOLOGYKEYSONLY = 'false'; // Allow fallback to other zones
240+
241+
const sequelize = new Sequelize('yugabyte', 'yugabyte', 'yugabyte', {
242+
host: 'localhost',
243+
port: '5433',
244+
dialect: 'postgres'
245+
})
246+
```
247+
248+
### Connection string with smart driver parameters
249+
250+
Alternatively, you can specify load balancing parameters directly in the connection string:
251+
252+
```js
253+
const connectionString =
254+
'postgres://yugabyte:yugabyte@localhost:5433/yugabyte' +
255+
'?loadBalance=any' +
256+
'&topologyKeys=aws.us-east-2.us-east-2a' +
257+
'&ybServersRefreshInterval=5' +
258+
'&failedHostReconnectDelaySecs=5';
259+
260+
const sequelize = new Sequelize(connectionString, {
261+
dialect: 'postgres',
262+
pool: {
263+
max: 10,
264+
min: 2,
265+
idle: 10000,
266+
acquire: 30000
267+
}
268+
});
269+
```
270+
271+
### Environment variables
272+
273+
The YugabyteDB smart driver recognizes these PostgreSQL-compatible environment variables:
274+
275+
| Variable | Description | Default |
276+
| :--- | :--- | :--- |
277+
| `PGHOST` | Database host | `localhost` |
278+
| `PGPORT` | Database port | `5433` |
279+
| `PGUSER` | Database user | `yugabyte` |
280+
| `PGPASSWORD` | Database password | `yugabyte` |
281+
| `PGDATABASE` | Database name | `yugabyte` |
282+
| `PGLOADBALANCE` | Load balancing mode | `false` |
283+
| `PGTOPOLOGYKEYS` | Topology-aware routing keys | - |
284+
| `PGYBSERVERSREFRESHINTERVAL` | Cluster topology refresh interval (seconds) | `5` |
285+
| `PGFAILEDHOSTRECONNECTDELAYSECS` | Failed host reconnect delay (seconds) | `5` |
286+
287+
You can set these in your shell or in a `.env` file:
288+
289+
```sh
290+
export PGHOST=localhost
291+
export PGPORT=5433
292+
export PGLOADBALANCE=any
293+
export PGYBSERVERSREFRESHINTERVAL=5
294+
```
295+
192296
## Specifying SSL configuration
193297
194298
This configuration can be used while connecting to a YugabyteDB Aeon cluster or a local YB cluster with SSL enabled.

0 commit comments

Comments
 (0)