Skip to content
Nhost Documentation
SupportDashboard

Configuring Postgres

Tune PostgreSQL runtime, performance, and operational settings like shared_buffers and work_mem via nhost.toml configuration.

PostgreSQL postgres configuration nhost.toml database settings shared buffers performance tuning wal settings

Configure PostgreSQL in nhost.toml under [postgres.settings]. Use nhost config example to see the full project configuration, including Postgres version and resources.

For settings compatibility, set postgres.version to the latest supported Postgres image for your PostgreSQL major version. Older images may accept settings without applying them.

Settings

Section titled “Settings”
nhost.toml
[postgres.settings]
jit = 'on'
maxConnections = 100
sharedBuffers = '128MB'
effectiveCacheSize = '4GB'
maintenanceWorkMem = '64MB'
checkpointCompletionTarget = 0.9
checkpointTimeout = '5min'
walBuffers = '-1'
walCompression = 'off'
defaultStatisticsTarget = 100
randomPageCost = 4.0
effectiveIOConcurrency = 1
workMem = '4MB'
hugePages = 'try'
minWalSize = '80MB'
maxWalSize = '1GB'
maxWorkerProcesses = 8
maxParallelWorkersPerGather = 2
maxParallelWorkers = 8
maxParallelMaintenanceWorkers = 2
walLevel = 'replica'
maxWalSenders = 10
maxReplicationSlots = 10
maxSlotWalKeepSize = '-1'
archiveTimeout = 300
trackIoTiming = 'off'
logMinDurationStatement = '-1'
logAutovacuumMinDuration = '10min'
logTempFiles = '-1'
sharedPreloadLibraries = [
  'pg_stat_statements',
  'pg_cron',
  'timescaledb',
  'pg_squeeze',
  'pg_search'
]


[postgres.settings.extensions.pgStatStatements]
max = 5000
track = 'top'
trackPlanning = 'off'


[postgres.settings.extensions.cron]
timezone = 'GMT'
maxRunningJobs = 32
logRun = 'on'


[postgres.settings.extensions.pgDurable]
maxUserConnections = 10
retentionDays = 30
logWorkflowSql = 'off'


[postgres.settings.extensions.timescaledb]
maxBackgroundWorkers = 16

Operational notes

Section titled “Operational notes”
  • Restart and downtime: Changing any setting under postgres.settings, including extension settings, restarts PostgreSQL and causes a short period of database downtime. Plan changes accordingly.
  • WAL and replication: A finite maxSlotWalKeepSize can invalidate a lagging replication slot. archiveTimeout is measured in seconds. checkpointTimeout sets the maximum interval between automatic checkpoints; checkpointCompletionTarget controls how much of that interval a checkpoint uses.
  • Logging: Slow-statement logs may contain sensitive SQL. extensions.pgDurable.logWorkflowSql defaults to off because substituted workflow SQL may contain secrets.
  • Background workers: Budget extensions.timescaledb.maxBackgroundWorkers alongside maxWorkerProcesses and other extensions.

See the configuration reference for field types and defaults, and PostgreSQL server configuration for the underlying database settings.