nsdb(n)

ns/server/$server/db

The ns/server/$server/db section selects the database pools available to a virtual server. The pools themselves are defined globally under ns/db/pools and ns/db/pool/$dbpool and may be shared by multiple servers.

The default pool is used when application code requests a database handle without explicitly naming a pool.

 ns_section ns/server/$server/db {
     ns_param pools       pool1,pool2,pool3
     ns_param defaultpool pool1
 }

Parameter name: defaultpool

Default database pool used by this server when no explicit pool name is requested

• Type: string

Parameter name: pools

List of database pool names available to this server; the names must refer to pools defined in ns/db/pools

• Type: list

ns/db/drivers

The ns/db/drivers section defines database driver instances available to NaviServer's nsdb interface. Each parameter name is a configuration-defined driver name, and each value is the database driver module implementation to load.

Database drivers are external NaviServer modules. They are maintained separately from the core server, usually in separate source repositories, and must be compiled and installed before they can be loaded. Common drivers include nsdbpg for PostgreSQL and nsoracle for Oracle; additional drivers are available for other database systems.

 ns_section ns/db/drivers {
     ns_param postgres nsdbpg
     ns_param nsoracle nsoracle
 }

Available external database drivers include nsdbpg, nsoracle, nsdbmysql, nsdbsqlite, nsdbtds, nsodbc, and nsdbbdb.

Parameter name: database driver name

Configuration-defined database driver name whose value names the installed database driver module implementation; the driver name is used in ns/db/pool/$dbpool via the driver parameter

• Value type: module

• Role of parameter name: configuration-defined identifier

• Cardinality: multiple entries with different parameter names are expected

ns/db/driver/$dbdriver

The ns/db/driver/$dbdriver section contains optional settings for a database driver instance. The final path component is the configuration-defined driver name from ns/db/drivers, not necessarily the implementation name.

For example, a configuration may map the driver name postgres to the nsdbpg implementation and then configure driver-specific settings below ns/db/driver/postgres.

 ns_section ns/db/drivers {
     ns_param postgres nsdbpg
 }
 
 ns_section ns/db/driver/postgres {
     ns_param pgbin /usr/lib/postgresql/18/bin/
 }

ns/db/pools

The ns/db/pools section defines global database pool names. Each parameter name is a configuration-defined pool name, and each value is a human-readable description of the pool.

Database pools are process-wide definitions and can be made available to one or more virtual servers through the server-specific ns/server/$server/db section.

 ns_section ns/db/pools {
     ns_param pool1 "Main database pool"
     ns_param pool2 "Secondary database pool"
     ns_param pool3 "Optional third database pool"
 }

Parameter name: database pool name

Configuration-defined database pool name whose value is a human-readable pool description; the pool name is used in ns/db/pool/$dbpool sections and in per-server database configuration

• Value type: string

• Role of parameter name: configuration-defined identifier

• Cardinality: multiple entries with different parameter names are expected

ns/db/pool/$dbpool

The ns/db/pool/$dbpool section configures a global database connection pool. A pool defines how NaviServer connects to a database, how many handles are maintained, and how idle or stale handles are checked and closed.

Database pools are global and may be used by multiple virtual servers. A server selects the pools it uses in ns/server/$server/db.

 ns_section ns/db/pool/pool1 {
     ns_param driver         postgres
     ns_param datasource     localhost::dbname
     ns_param user           dbuser
     ns_param password       secret
     ns_param connections    15
     ns_param logminduration 10ms
 }

Parameter name: checkinterval

Interval at which the pool checks for stale database handles

• Type: time

• Default: 5m

Parameter name: connections

Number of database connections maintained by this pool

• Type: integer

• Default: 2

Parameter name: datasource

Driver-specific datasource string identifying the database connection target

• Type: string

Parameter name: driver

Database driver used by this pool

• Type: string

Parameter name: logminduration

When SQL logging is enabled, log only statements whose execution time is at least this duration

• Type: time

• Default: 0ms

Parameter name: logsqlerrors

Log SQL errors reported by this pool

• Type: boolean

• Default: false

Parameter name: maxidle

Close database handles that have been idle for at least this interval

• Type: time

• Default: 5m

Parameter name: maxopen

Close database handles that have been open longer than this interval

• Type: time

• Default: 60m

Parameter name: password

Database password used when opening connections for this pool

• Type: string

Parameter name: user

Database user name used when opening connections for this pool

• Type: string