docs: Add YugabyteDB smart driver features to Sequelize documentation (#29496)

krishna-yb · ddhodge · web-flow · commit fe081a75a046 · 2025-12-03T15:00:56.000+05:30
docs: Add YugabyteDB smart driver features to Sequelize documentation

- Added subsection: Using the YugabyteDB Smart Driver
  - Explains how to use smart driver with sequelize-yugabytedb
  - Links to smart-drivers documentation
  - Shows package.json configuration
- Simplified load balance properties section
  - Environment variables examples
  - Connection parameters examples
  - Removed detailed property table for brevity

* docs: Apply review feedback - improve smart driver documentation

* docs: Add environment variables documentation to Node.js smart driver

- Add comprehensive environment variables table to yugabyte-node-driver.md
- Include all standard PG env vars (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD)
- Include YugabyteDB-specific env vars (PGLOADBALANCE, PGTOPOLOGYKEYS, PGYBSERVERSREFRESHINTERVAL)
- Add mapping table showing environment variable to connection parameter correspondence
- Add code examples showing how to set env vars in Node.js and shell
- Update sequelize.md to clarify it shows 'some' not 'all' environment variables
- Add cross-reference from Sequelize docs to complete env vars documentation


- Remove redundant detailed env vars table from yugabyte-node-driver.md
- Keep only the mapping table showing env var to parameter correspondence
- Add all standard PostgreSQL env vars (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD)
- Include YugabyteDB-specific env vars (PGLOADBALANCE, PGTOPOLOGYKEYS, PGYBSERVERSREFRESHINTERVAL)
- Remove note from yugabyte-node-driver.md (cleaner without it)
- Update sequelize.md to link to complete env vars list
- Clarify that load balancing env vars are only for @yugabytedb/pg package


Co-authored-by: Dwight Hodge &lt;ghodge@yugabyte.com&gt;
diff --git a/docs/content/stable/develop/drivers-orms/nodejs/sequelize.md b/docs/content/stable/develop/drivers-orms/nodejs/sequelize.md
@@ -88,6 +88,27 @@ The following code creates an Employees model to store and retrieve employee inf
 - 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.
 - Finally, you can retrieve the information of all employees using `Employee.findAll()`.
 
+#### Using the YugabyteDB node-postgres smart driver
+
+You can also use the [YugabyteDB node-postgres smart driver](/stable/develop/drivers-orms/nodejs/yugabyte-node-driver/) (`@yugabytedb/pg`), which includes connection load balancing features, to distribute connections uniformly across the nodes in the entire cluster or in specific placements (zones or regions).
+
+For more information on the smart driver features, refer to [Using YugabyteDB smart drivers](../../smart-drivers/#using-yugabytedb-smart-drivers).
+
+To use the YugabyteDB node-postgres smart driver instead of the vanilla pg driver, add the following dependencies to your application's `package.json` file, to override the default PostgreSQL driver with the YugabyteDB smart driver:
+
+```json
+{
+  "dependencies": {
+    "sequelize-yugabytedb": "^1.0.5",
+    "pg": "npm:@yugabytedb/pg@8.7.3-yb-10"
+  }
+}
+```
+
+To configure load balancing properties, use either environment variables or connection parameters. See [Specify load balance properties](#specify-load-balance-properties) for examples and more details.
+
+For a complete working example, refer to the [Sequelize ORM example application](https://github.com/YugabyteDB-Samples/orm-examples/tree/master/node/sequelize).
+
 Add the code in the `example.js` file.
 
 ```js
@@ -189,9 +210,74 @@ Employees Details:
 ]
 ```
 
-## Specifying SSL configuration
+#### Specify load balance properties
+
+You can specify load balance properties using environment variables or connection parameters.
+
+For information on all load balance modes, see [Node type-aware load balancing](../../smart-drivers/#node-type-aware-load-balancing).
+
+##### Environment variables
+
+The following table summarizes some environment variables available for configuring the YugabyteDB node-postgres smart driver:
+
+| Environment variable | Description | Default |
+| :--- | :--- | :--- |
+| PGLOADBALANCE | Enables cluster-aware or node type-aware load balancing.<br>Valid values are `any`, `prefer-primary`, `prefer-rr`, `only-primary`, `only-rr`, `true` (alias for `any`), and `false` (disabled). | `false` |
+| PGTOPOLOGYKEYS | Enables topology-aware load balancing by specifying comma-separated geo-locations. Provide locations in the form `cloud.region.zone` (for example, `aws.us-east-1.us-east-1a`). Specify multiple zones by separating values using commas. You can use a wildcard to specify all zones in a region (`cloud.region.*`). Indicate fallback priority using `cloud.region.zone:n`, where `n` is priority number. | Empty (disabled) |
+| PGYBSERVERSREFRESHINTERVAL | The interval (in seconds) to refresh the servers list | `300` (5 minutes) |
+
+These environment variables are only effective when using the YugabyteDB smart driver (`@yugabytedb/pg`). For a complete list of all available environment variables, refer to [Environment variables](../yugabyte-node-driver/#environment-variables).
+
+```js
+const { Sequelize, DataTypes } = require('sequelize-yugabytedb')
+
+// Enable load balancing across nodes in the cluster
+process.env.PGLOADBALANCE = 'any';  // Valid values: any, prefer-primary, prefer-rr, only-primary, only-rr
+// Specify the region(s)/zone(s) to target nodes from (Optional)
+process.env.PGTOPOLOGYKEYS = 'aws.us-east-2.us-east-2a';
+// Set the minimum time interval for refreshing the cluster topology information (Optional)
+process.env.PGYBSERVERSREFRESHINTERVAL = '5';
+
+const sequelize = new Sequelize('yugabyte', 'yugabyte', 'yugabyte', {
+   host: 'localhost',
+   port: '5433',
+   dialect: 'postgres'
+})
+```
+
+You can also set these in your shell or in a `.env` file:
+
+```sh
+export PGLOADBALANCE=any
+export PGTOPOLOGYKEYS=aws.us-east-2.us-east-2a
+export PGYBSERVERSREFRESHINTERVAL=5
+```
+
+##### Connection parameters
+
+Alternatively, you can specify load balancing properties directly in the connection string:
+
+```js
+const connectionString = 
+  'postgres://yugabyte:yugabyte@localhost:5433/yugabyte' +
+  '?loadBalance=any' +
+  '&topologyKeys=aws.us-east-2.us-east-2a' +
+  '&ybServersRefreshInterval=5';
+
+const sequelize = new Sequelize(connectionString, {
+   dialect: 'postgres',
+   pool: {
+      max: 10,
+      min: 2,
+      idle: 10000,
+      acquire: 30000
+   }
+});
+```
+
+## Specify SSL configuration
 
-This configuration can be used while connecting to a YugabyteDB Aeon cluster or a local YB cluster with SSL enabled.
+This configuration can be used while connecting to a YugabyteDB Aeon cluster or a local YugabyteDB cluster with SSL enabled.
 
 1. Install the `fs` package to read the SSL certificate:
 
@@ -224,3 +310,4 @@ This configuration can be used while connecting to a YugabyteDB Aeon cluster or
 ## Learn more
 
 - [YugabyteDB smart drivers for YSQL](../../smart-drivers/)
+- [Sequelize ORM example application](https://github.com/YugabyteDB-Samples/orm-examples/tree/master/node/sequelize)
diff --git a/docs/content/stable/develop/drivers-orms/nodejs/yugabyte-node-driver.md b/docs/content/stable/develop/drivers-orms/nodejs/yugabyte-node-driver.md
@@ -91,6 +91,52 @@ postgresql://yugabyte:yugabyte@128.0.0.1:5433/yugabyte?loadBalance=true? \
 
 After the driver establishes the initial connection, it fetches the list of available servers from the cluster, and load-balances subsequent connection requests across these servers.
 
+#### Environment variables
+
+You can also specify load balance properties using environment variables. The following table shows the mapping between environment variables and their corresponding connection parameters.
+
+| Environment variable | Connection parameter |
+| :--- | :--- |
+| PGHOST | host |
+| PGPORT | port |
+| PGDATABASE | database |
+| PGUSER | user |
+| PGPASSWORD | password |
+| PGLOADBALANCE | loadBalance |
+| PGTOPOLOGYKEYS | topologyKeys |
+| PGYBSERVERSREFRESHINTERVAL | ybServersRefreshInterval |
+
+The following is an example of how you can set up the connection using environment variables.
+
+```js
+const pg = require('@yugabytedb/pg');
+
+// Enable load balancing across nodes in the cluster
+process.env.PGLOADBALANCE = 'any';  // Valid values: any, prefer-primary, prefer-rr, only-primary, only-rr
+// Specify the region(s)/zone(s) to target nodes from (Optional)
+process.env.PGTOPOLOGYKEYS = 'aws.us-east-2.us-east-2a';
+// Set the minimum time interval for refreshing the cluster topology information (Optional)
+process.env.PGYBSERVERSREFRESHINTERVAL = '5';
+
+const client = new pg.Client({
+   host: 'localhost',
+   port: 5433,
+   database: 'yugabyte',
+   user: 'yugabyte',
+   password: 'yugabyte'
+});
+```
+
+You can also set these variables in your shell or in a `.env` file:
+
+```sh
+export PGLOADBALANCE=any
+export PGTOPOLOGYKEYS=aws.us-east-2.us-east-2a
+export PGYBSERVERSREFRESHINTERVAL=5
+```
+
+For information on all load balance modes, see [Node type-aware load balancing](../../smart-drivers/#node-type-aware-load-balancing).
+
 #### Use SSL
 
 The following table describes the connection parameters required to connect using TLS/SSL.
