The GUCS:
A Three-Hour Tour

Josh BerkusPostgreSQL Experts Inc.DrakeCon 2010 - San Francisco

agenda

what are GUCS?

understanding GUCS

simple basic configuration

new GUCS

grand tour

related stuff

pg_hba.conf

recovery.conf

pg_ident.conf

libpq settings

psql \ commands

system functions

X

What are GUCS?

Grand Unified Configuration SettingsA large set of global and session database settings which live in:

src/backend/utils/misc/guc.c

Your main way of configuring and tuning the database.in addition to compile options, system configuration and schema tuning!

Pronounced gucks

208 Switches and Levers

208 Settings?!?

Don't worry!

Setting GUCS

865

Eight types of GUCS

Boolean

Integer

Float

Memory / Disk

Time

Strings

ENUMs

Lists

Eight types of GUCS

Booleantake TRUE | FALSE or ON | OFF

enable_seqscan = on

Integertake whole numbers only

max_connections = 700

Eight types of GUCS

Floattake decimal values

random_page_cost = 3.75

Memory / Disk Sizecan take integers

but can also take computer units: kB, MB, GB

work_mem = 512MB
shared_buffers = 4096

Eight Types of GUCS

Timetake time values (units vary)

units are often omitted

authentication_timeout = 30s

Stringstake unchecked strings

often refers to file locations or program names

log_directory = 'pg_log'

Eight Types of GUCS

ENUMstake a string value from a prescribed list

wal_level = hot_standby

Liststake a list of values, either freeform or ENUM

search_path = 'main, archive, $user'

Six GUCS Contexts

session

superuser

reload

restart

backend

internal

Six GUCS Contexts

session, or usercan be set on per-session basis at runtime

can also be changed by altering the ROLE

superusercan be set at runtime for the whole server, but only by the superuser

Six GUCS Contexts

reload, or sighuprequires a soft restart of the postmaster to change

also called a HUP

restart, or postmastercan only be changed with a hard restart

More on reloading

Three methods for reloading

pg_ctl -D PGDATA reloadkill -HUP SELECT pg_reload_conf();

Six GUCS Contexts

backenddeveloper settings which have to be set before session start

internalcompile-time settings provided for reference. Unalterable.

5 Places of set GUCs

postgresql.conf file

SET

pg_settings

ALTER objects

command-line switches & PGOPTIONS

postgresql.conf

$PGDATA/postgresql.confcan be relocated or symlinked

Primary way to change GUCSfor performance

for logging

for defaults

show postgresql.conf file

point out switching behavior

postgresql.conf

just a big list of settings

defaults are # commented out

if a setting appears multiple times, the last one takes effect

can use include files

SET & SHOW

Access GUCS in a SQL sessionSET changesonly applies to user and superuser contexts

best way to change things for only one session

can be embedded in stored procedures

SET enable_mergejoin = false;

SHOW displaysSHOW ALL lets you see all GUCS

SHOW shared_buffers;

SET & SHOW: set_config

set_config( setting, value, is_local )alternative to SET

better for scripts since it takes a string

SELECT set_config('work_mem','1GB', TRUE);

current_setting ( setting )alternative to SHOW

SELECT current_setting('lc_collate');

pg_settings

Tabular representation of GUCSa system view

can be queried

can be updated, which runs a SET on the relevant parameter

SELECT * FROM pg_settings
WHERE name = 'work_mem';

UPDATE pg_settings SET setting = '12MB'
WHERE name = 'work_mem';

ALTER objects

You can ALTER some objects to change their configuration settingsROLES (users)

DATABASEs

FUNCTIONs

Changes configuration setting when that object is used (unless overridden by a SET)

ALTER ROLE data entry SET search_path = 'entry, public';

New ALTER ROLE for 9.0

ALTER ROLE IN DATABASE accts SET search_path = '$user, webview, contrib, public';

now can set ROLE-based settings just for a specific database

essential for search_path, useful for others

ALTER objects

Good way to discriminate between applications & usersset search_pathsometimes for security

primitive resource managementchange work_mem, etc. for specific ROLES, applications or reports

localizationif different users have different desired displays

ALTER DATABASE sao_paulo SET timezone = 'America/SaoPaulo';

ALTER objects

CREATE FUNCTION check_password(uname TEXT, pass TEXT)RETURNS BOOLEAN AS $$DECLARE passed BOOLEAN;BEGIN SELECT (pwd = $2) INTO passed FROM pwds WHERE username = $1;

RETURN passed;END;$$ LANGUAGE plpgsql SECURITY DEFINER -- Set a secure search_path: trusted -- schema(s), then 'pg_temp'. SET search_path = admin, pg_temp;

command-line and pgoptions

Set options when you start PostgreSQLas command-line switches

using the PGOPTIONS shell variable

Not generally recommendedhard to administrate or document

mainly for running automated testsand for restarting with recovery options

postgres -c 'bgwriter_delay = 50ms'export PGOPTIONS = '-c zero_damaged_pages = ON'

GUCS Reference

The 13 Settings
most users need to adjust

listen_address

max_connections

shared_buffers

work_mem

maintenance_
work_mem

synchronous_commit

checkpoint_segments

wal_buffers

autovacuum

effective_cache_size

GROUP: replication

GROUP: the logging settings

GUCS Reference

What's New, GUCS?

add_missing_from
regex_flavor

X

security & authentication

bonjourlets you turn bonjour support off even if it's compiled

ssl_renegotiation_limitworks around SSL patch from OpenSSL exploit

application_name

settable per session

lets you log which application is running which statementsdifferent ROLEs no longer required

query planner settings

enable_materiallets you turn on and off materialization of subqueries for query plan troubleshooting

geqo_seedmake sure that GEQO plans are determinative for the same inputs

backwards compatibility

bytea_outputsupports old bytea escapes as opposed to new hex format

lo_compat_privilegesdisables new permission checks for large objects

replication settings

wal_level

wal_sender_delay

wal_keep_segments

hot_standby

max_wal_senders

vacuum_defer_cleanup_age

max_standby_archive_delay

max_standby_streaming_delay

trace_recovery

GUCS: the Grand Tour

Categories (mine)

file locations

connection settings

resource management

maintenance

WAL & checkpoints

replication

query tuning

logging

statistics

locks

locale & formatting

other settings & defaults

compatibility

custom GUCS

developer options

presets

custom variable classes

for supporting various PostgreSQL Extensions

custom_variable_classes = 'pg_stat_statements,auto_explain'

pg_stat_statements.max = 10000pg_stat_statements.track = all

auto_explain.log_min_duration = '200ms'auto_explain.log_nested_statements = onauto_explain.log_format = json

Finale

config_file

data_directory

hba_file

ident_file

external_pid_file

listen_addresses

port

max_connections

superuser_reserved_connections

unix_socket_directory

unix_socket_group

unix_socket_permissions

bonjour_name

authentication_timeout

tcp_keepalives_count

tcp_keepalives_idle

tcp_keepalives_interval

db_user_namespace

password_encryption

ssl

krb_caseins_users

krb_realm

krb_server_hostname

krb_server_keyfile

krb_srvname

shared_buffers

work_mem

temp_buffers

max_prepared_transactions

max_files_per_process

max_stack_depth

shared_preload_libraries

maintenance_work_mem

max_fsm_pages

max_fsm_relations

vacuum_cost_delay

vacuum_cost_limit

vacuum_cost_page_dirty

Contact

Josh Berkus: josh@postgresql.orgblog: blogs.ittoolbox.com/database/soup

PostgreSQL: www.postgresql.orgpgexperts: www.pgexperts.com

Upcoming EventspgDay LA at SCALE9x

MySQLCon

This talk is copyright 2010 PostgreSQL Experts Inc., and is licensed under the creative commons attribution license. Images of Gilligan's Island TV show characters are property of CBS or the respective rights holders, and are used here under principles of fair use.

Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelEighth Outline LevelNinth Outline Level