370: Support for connection parameters passed via the DB connection s…

[hubert2dev]

Support Connection URL Parameters for All Database Types

Summary

This PR adds support for parsing connection parameters from URI query strings for PostgreSQL, MongoDB, and MySQL database connections. Users can now specify connection timeout, pool settings, and other connection-specific parameters directly in the connection URI, making configuration more flexible and consistent with standard database connection string practices.

Changes

• Added support for parsing connection parameters from URI query strings
• Parameters can be specified either in the URI query string or as explicit config options
• Explicit config values take precedence over URI query parameters
• Added comprehensive test coverage for URI parsing and parameter validation
• Parameters are validated (must be non-negative numbers) and invalid values are ignored

Supported URL Formats

PostgreSQL

URL Format: postgresql://[username]:[password]@[hostname]:[port]/[database]?[query_params]

Example:

postgresql://user:pass@localhost:5432/mydb?connect_timeout=**300**&keepalives=1&keepalives_idle=60&keepalives_interval=10&keepalives_count=10

MongoDB

URL Format: mongodb://[username]:[password]@[hostname]:[port]/[database]?[query_params]

Example:

mongodb://user:pass@host/powersync_test?connectTimeoutMS=10000&socketTimeoutMS=60000&serverSelectionTimeoutMS=30000&maxPoolSize=10&maxIdleTimeMS=120000

MySQL

URL Format: mysql://[username]:[password]@[hostname]:[port]/[database]?[query_params]

Example:

mysql://user:pass@host/db?connectTimeout=10000&connectionLimit=20&queueLimit=10&timeout=30000

Supported Parameters

PostgreSQL

Parameter	Type	Description	Naming Convention
connect_timeout	number	Connection timeout in seconds	snake_case
keepalives	number	Enable/disable TCP keepalives (0 to disable, 1 to enable)	snake_case
keepalives_idle	number	Seconds before sending first keepalive	snake_case
keepalives_interval	number	Seconds between keepalive probes	snake_case
keepalives_count	number	Number of keepalive probes before connection is considered dead	snake_case

Note: keepalives_interval and keepalives_count are accepted but cannot be directly applied at the Node.js socket level (limitation of the socket API).

MongoDB

Parameter	Type	Description	Naming Convention
connectTimeoutMS	number	Connection timeout in milliseconds	camelCase
socketTimeoutMS	number	Socket timeout in milliseconds	camelCase
serverSelectionTimeoutMS	number	Server selection timeout in milliseconds	camelCase
maxPoolSize	number	Maximum pool size	camelCase
maxIdleTimeMS	number	Maximum idle time in milliseconds	camelCase

MySQL

Parameter	Type	Description	Naming Convention
connectTimeout	number	Connection timeout in milliseconds	camelCase
connectionLimit	number	Maximum number of connections in the pool	camelCase
queueLimit	number	Maximum number of connection requests the pool will queue	camelCase
timeout	number	Query timeout in milliseconds	camelCase

Note: The timeout parameter is accepted in the config but is not a valid PoolOptions property in mysql2. Query timeouts are handled at the query level, not pool level.

Parameter Naming Conventions

Each database type uses a naming convention that matches its underlying driver/library:

• PostgreSQL: Uses snake_case (matches libpq conventions)
• MongoDB: Uses camelCase (matches MongoDB Node.js driver conventions)
• MySQL: Uses camelCase (matches mysql2 driver conventions)

Important: You must use the correct naming convention for each database type. Mixing conventions will not work (e.g., using connectTimeout in a PostgreSQL URI will be ignored).

Usage Examples

PostgreSQL

// Via URI query string
const config = {
  type: 'postgresql',
  uri: 'postgresql://user:pass@host/db?connect_timeout=300&keepalives=1'
};

// Via explicit config (takes precedence)
const config = {
  type: 'postgresql',
  uri: 'postgresql://user:pass@host/db?connect_timeout=300',
  connect_timeout: 600 // This value will be used instead of 300
};

MongoDB

// Via URI query string
const config = {
  type: 'mongodb',
  uri: 'mongodb://user:pass@host/db?connectTimeoutMS=10000&maxPoolSize=10'
};

// Via explicit config (takes precedence)
const config = {
  type: 'mongodb',
  uri: 'mongodb://user:pass@host/db?connectTimeoutMS=10000',
  connectTimeoutMS: 20000 // This value will be used instead of 10000
};

MySQL

// Via URI query string
const config = {
  type: 'mysql',
  uri: 'mysql://user:pass@host/db?connectTimeout=10000&connectionLimit=20'
};

// Via explicit config (takes precedence)
const config = {
  type: 'mysql',
  uri: 'mysql://user:pass@host/db?connectTimeout=10000',
  connectTimeout: 20000 // This value will be used instead of 10000
};

Validation

• All parameters must be valid non-negative numbers
• Invalid values (NaN, negative numbers, non-numeric strings) are silently ignored
• Parameters can be partially specified (you don't need to provide all parameters)
• Explicit config values always take precedence over URI query parameters

Testing

Comprehensive test coverage has been added for:

• URI parsing with query parameters
• Parameter precedence (explicit config over URI params)
• Partial parameter specification
• Invalid parameter value handling
• Error cases (missing database, invalid scheme, etc.)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 33d1c77

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[kobiebotha]

Probably worth mentioning the issue that this addresses