Configuration

Options go on .option("name", "value") in Scala/Python or inside OPTIONS (...) in SQL. Names are matched case-insensitively. Any option not listed below is forwarded to the PostgreSQL JDBC driver, which is how you pass through standard JDBC parameters like loginTimeout or socketTimeout.

Required connection options

Every write sets these four. Any missing option throws IllegalArgumentException before Spark starts a task.

Option	Default	Tier	Notes
url	—	Community	PostgreSQL JDBC URL
dbtable	—	Community	Target table name
user	—	Community	Database user
password	—	Community	Database password
driver	org.postgresql.Driver	Community	Override only for a shaded driver class

Write

Option	Default	Tier	Notes
writeMode	append	append / overwrite Community; upsert Community with one key, Pro with composite keys	Invalid values throw IllegalArgumentException
mergeKeys	—	Pro when more than one key	Required for upsert; comma-separated, whitespace trimmed
batchSize	1000	Community	Rows per write batch

Schema and validation

Option	Default	Tier	Notes
schemaEvolution	strict	strict Community; see notes for non-default modes	strict, addColumns, alignToTarget, warn
schemaEvolutionAllowTableRewrite	false	Pro	Required for widenings that rewrite the whole table
columnCaseSensitive	false	Community	When false, identifiers fold to lowercase
validationMode	skip	skip Community; other modes paid	skip, strict, warnAndFilter

Note

Invalid values for schemaEvolution and validationMode fall back silently — schemaEvolution to strict, validationMode to skip. writeMode is the exception: an invalid value throws.

Retry

Option	Default	Tier	Notes
maxRetries	3	Community	Total attempts including the first
retryBackoffMs	1000	Community	Initial backoff in milliseconds
retryBackoffMultiplier	2.0	Community	Exponential factor between attempts

Connection pool

Option	Default	Tier	Notes
maxPoolSize	spark.executor.cores (fallback: 2)	Community	Maximum concurrent connections per active Spark process
minIdle	0	Community	Minimum idle connections
connectionTimeout	30000	Community	ms to wait for a connection
idleTimeout	30000	Community	ms before idle connections close
maxLifetime	1800000	Community	ms before a connection is retired

See Tuning and Metrics for connection-budget math and tuning guidance.

Security

Option	Default	Tier	Notes
ssl	false	Pro when true	Enables TLS
sslMode	require	Pro	disable, allow, prefer, require, verify-ca, verify-full
sslCert	—	Enterprise	Client certificate path
sslKey	—	Enterprise	Client private key path (PKCS#8 DER)
sslRootCert	—	Enterprise	Root CA certificate path

See SSL and Security for file placement and key-format requirements.

Streaming

Option	Default	Tier	Notes
streamingExactlyOnce	false	Enterprise with streaming	Enables replay protection for committed microbatches
commitLogTable	—	Enterprise with streaming	Override the bookkeeping table used by exactly-once mode
commitLogRetentionEpochs	—	Enterprise with streaming	Positive integer; prunes old tracking rows after commit

checkpointLocation is still a Spark Structured Streaming option, not a PGStyx option. Use Streaming for delivery and checkpointing guidance.

Metrics and licensing

Option	Default	Tier	Notes
metricsEnabled	true	Community	Tracks built-in counters for Metrics.getReport()
licenseKey	—	Community	Required for any Pro or Enterprise capability

Plan gating in one place

If any of the following is set, the job requires a matching licenseKey:

• More than one mergeKeys value — Pro.
• schemaEvolution=addColumns or schemaEvolution=alignToTarget — paid-plan schema-evolution modes.
• schemaEvolutionAllowTableRewrite=true — Pro.
• validationMode set to anything other than skip — Pro.
• ssl=true — Pro.
• Any of sslCert, sslKey, sslRootCert with ssl=true — Enterprise.
• .writeStream.format("pgstyx") — Enterprise.
• streamingExactlyOnce=true — Enterprise.

Missing or invalid license throws LicenseException at write-build time, naming the gated feature.