1. The GUCS:
A Three-Hour Tour
Josh Berkus
PostgreSQL Experts Inc.
DrakeCon 2010 - San Francisco

2. agenda
# what are GUCS?
# understanding GUCS
# simple basic configuration
# new GUCS
# grand tour

3. related stuff
X
# pg_hba.conf
# recovery.conf
# pg_ident.conf
# libpq settings
# psql commands
# system functions

4. What are GUCS?
# “Grand Unified Configuration Settings”
– A 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”

5. 208 Switches and Levers

6. 208 Settings?!?

7. Don't worry!

8. Setting GUCS
8
6
5

9. Eight types of GUCS
# Boolean # Time
# Integer # Strings
# Float # ENUMs
# Memory / Disk # Lists

10. Eight types of GUCS
# Boolean
– take TRUE | FALSE or ON | OFF
enable_seqscan = on
# Integer
– take whole numbers only
max_connections = 700

11. Eight types of GUCS
# Float
– take decimal values
random_page_cost = 3.75
# Memory / Disk Size
– can take integers
– but can also take “computer units”: kB, MB, GB
work_mem = 512MB
shared_buffers = 4096

12. Eight Types of GUCS
# Time
– take time values (units vary)
– units are often omitted
authentication_timeout = 30s
# Strings
– take unchecked strings
– often refers to file locations or program names
log_directory = 'pg_log'

13. Eight Types of GUCS
# ENUMs
– take a string value from a prescribed list
wal_level = hot_standby
# Lists
– take a list of values, either freeform or ENUM
search_path = 'main, archive, “$user”'

14. Six GUCS Contexts
# session
# superuser
# reload
# restart
# backend
# internal

15. Six GUCS Contexts
# session, or “user”
– can be set on per-session basis at runtime
– can also be changed by altering the ROLE
# superuser
– can be set at runtime for the whole server, but only
by the superuser

16. Six GUCS Contexts
# reload, or “sighup”
– requires a soft restart of the postmaster to change
– also called a “HUP”
# restart, or “postmaster”
– can only be changed with a hard restart

17. More on reloading
# Three methods for reloading
pg_ctl -D PGDATA reload
kill -HUP <postmaster.pid>
SELECT pg_reload_conf();

18. Six GUCS Contexts
# backend
– developer settings which have to be set before
session start
# internal
– compile-time settings provided for reference.
Unalterable.

19. 5 Places of set GUCs
1.postgresql.conf file
2.SET
3.pg_settings
4.ALTER objects
5.command-line switches & PGOPTIONS

20. postgresql.conf
# $PGDATA/postgresql.conf
– can be relocated or symlinked
# Primary way to change GUCS
– for performance
– for logging
– for defaults

21. 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

22. SET & SHOW
# Access GUCS in a SQL session
– SET changes
● only 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 displays
● SHOW ALL lets you see all GUCS
SHOW shared_buffers;

23. 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');

24. pg_settings
# Tabular representation of GUCS
– a “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';

25. ALTER objects
# You can ALTER some objects to change their
configuration settings
– ROLES (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';

26. 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

27. ALTER objects
# Good way to discriminate between applications
& users
– set search_path
● sometimes for security
– primitive resource management
● change work_mem, etc. for specific ROLES, applications
or reports
– localization
● if different users have different desired displays
ALTER DATABASE sao_paulo SET timezone =
'America/SaoPaulo';

28. 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;

29. command-line and pgoptions
# Set options when you start PostgreSQL
– as command-line switches
– using the PGOPTIONS shell variable
# Not generally recommended
– hard to administrate or document
– mainly for running automated tests
● and for restarting with recovery options
postgres -c 'bgwriter_delay = 50ms'
export PGOPTIONS = '-c zero_damaged_pages = ON'

30. GUCS Reference

31. The 13 Settings
most users need to adjust
(1) listen_address (8) checkpoint_segments
(2) max_connections (9) wal_buffers
(3) shared_buffers (10) autovacuum
(4) work_mem (11) effective_cache_size
(5) maintenance_
(12) GROUP: replication
work_mem
(13) GROUP: the logging settings
(6) synchronous_commit

32. GUCS Reference

33. What's New, GUCS?

34. X
add_missing_from
regex_flavor

35. security & authentication
# bonjour
– lets you turn bonjour support off even if it's
compiled
# ssl_renegotiation_limit
– works around SSL patch from OpenSSL exploit

36. application_name
# settable per session
# lets you log which application is running which
statements
– different ROLEs no longer required

37. query planner settings
# enable_material
– lets you turn on and off materialization of
subqueries for query plan troubleshooting
# geqo_seed
– make sure that GEQO plans are determinative
for the same inputs

38. backwards compatibility
# bytea_output
– supports old bytea escapes as opposed to new
hex format
# lo_compat_privileges
– disables new permission checks for large
objects

39. 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

40. GUCS: the Grand Tour

41. Categories (mine)
# file locations # statistics
# connection settings # locks
# resource # locale & formatting
management # other settings &
# maintenance defaults
# WAL & checkpoints # compatibility
# replication # custom GUCS
# query tuning # developer options
# logging # presets

42. custom variable classes
# for supporting various PostgreSQL Extensions
custom_variable_classes =
'pg_stat_statements,auto_explain'
pg_stat_statements.max = 10000
pg_stat_statements.track = all
auto_explain.log_min_duration = '200ms'
auto_explain.log_nested_statements = on
auto_explain.log_format = json

43. Finale
1) config_file 20) ssl
2) data_directory 21) krb_caseins_users
3) hba_file 22) krb_realm
4) ident_file 23) krb_server_hostname
5) external_pid_file 24) krb_server_keyfile
6) listen_addresses 25) krb_srvname
7) port 26) shared_buffers
8) max_connections 27) work_mem
9) superuser_reserved_connections 28) temp_buffers
10) unix_socket_directory 29) max_prepared_transactions
11) unix_socket_group 30) max_files_per_process
12) unix_socket_permissions 31) max_stack_depth
13) bonjour_name 32) shared_preload_libraries
14) authentication_timeout 33) maintenance_work_mem
15) tcp_keepalives_count 34) max_fsm_pages
16) tcp_keepalives_idle 35) max_fsm_relations
17) tcp_keepalives_interval 36) vacuum_cost_delay
18) db_user_namespace 37) vacuum_cost_limit
19) password_encryption 38) vacuum_cost_page_dirty

44. Contact
# Josh Berkus: josh@postgresql.org
– blog: blogs.ittoolbox.com/database/soup
# PostgreSQL: www.postgresql.org
– pgexperts: www.pgexperts.com
# Upcoming Events
– pgDay 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.