From 2a0c81a12c7e6c5ac1557b0f1f4a581f23fd4ca7 Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Mon, 24 Sep 2012 17:55:53 +0300 Subject: Add support for include_dir in config file. This allows easily splitting configuration into many files, deployed in a directory. Magnus Hagander, Greg Smith, Selena Deckelmann, reviewed by Noah Misch. --- doc/src/sgml/config.sgml | 150 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 117 insertions(+), 33 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index cfdc803056f..4bd06ed7601 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -79,38 +79,6 @@ shared_buffers = 128MB value, write either two quotes (preferred) or backslash-quote. - - - include - in configuration file - - In addition to parameter settings, the postgresql.conf - file can contain include directives, which specify - another file to read and process as if it were inserted into the - configuration file at this point. This feature allows a configuration - file to be divided into physically separate parts. - Include directives simply look like: - -include 'filename' - - If the file name is not an absolute path, it is taken as relative to - the directory containing the referencing configuration file. - Inclusions can be nested. - - - - - include_if_exists - in configuration file - - There is also an include_if_exists directive, which acts - the same as the include directive, except for the behavior - when the referenced file does not exist or cannot be read. A regular - include will consider this an error condition, but - include_if_exists merely logs a message and continues - processing the referencing configuration file. - - SIGHUP @@ -213,7 +181,123 @@ SET ENABLE_SEQSCAN TO OFF; - + + + Configuration File Includes + + + + include + in configuration file + + In addition to parameter settings, the postgresql.conf + file can contain include directives, which specify + another file to read and process as if it were inserted into the + configuration file at this point. This feature allows a configuration + file to be divided into physically separate parts. + Include directives simply look like: + +include 'filename' + + If the file name is not an absolute path, it is taken as relative to + the directory containing the referencing configuration file. + Inclusions can be nested. + + + + + include_if_exists + in configuration file + + There is also an include_if_exists directive, which acts + the same as the include directive, except for the behavior + when the referenced file does not exist or cannot be read. A regular + include will consider this an error condition, but + include_if_exists merely logs a message and continues + processing the referencing configuration file. + + + + + include_dir + in configuration file + + The postgresql.conf file can also contain + include_dir directives, which specify an entire directory + of configuration files to include. It is used similarly: + + include_dir 'directory' + + Non-absolute directory names follow the same rules as single file include + directives: they are relative to the directory containing the referencing + configuration file. Within that directory, only non-directory files whose + names end with the suffix .conf will be included. File + names that start with the . character are also excluded, + to prevent mistakes as they are hidden on some platforms. Multiple files + within an include directory are processed in filename order. The filenames + are ordered by C locale rules, ie. numbers before letters, and uppercase + letters before lowercase ones. + + + + Include files or directories can be used to logically separate portions + of the database configuration, rather than having a single large + postgresql.conf file. Consider a company that has two + database servers, each with a different amount of memory. There are likely + elements of the configuration both will share, for things such as logging. + But memory-related parameters on the server will vary between the two. And + there might be server specific customizations, too. One way to manage this + situation is to break the custom configuration changes for your site into + three files. You could add this to the end of your + postgresql.conf file to include them: + + include 'shared.conf' + include 'memory.conf' + include 'server.conf' + + All systems would have the same shared.conf. Each server + with a particular amount of memory could share the same + memory.conf; you might have one for all servers with 8GB of RAM, + another for those having 16GB. And finally server.conf could + have truly server-specific configuration information in it. + + + + Another possibility is to create a configuration file directory and + put this information into files there. For example, a conf.d + directory could be referenced at the end ofpostgresql.conf: + + include_dir 'conf.d' + + Then you could name the files in the conf.d directory like this: + + 00shared.conf + 01memory.conf + 02server.conf + + This shows a clear order in which these files will be loaded. This is + important because only the last setting encountered when the server is + reading its configuration will be used. Something set in + conf.d/02server.conf in this example would override a value + set in conf.d/01memory.conf. + + + + You might instead use this configuration directory approach while naming + these files more descriptively: + + 00shared.conf + 01memory-8GB.conf + 02server-foo.conf + + This sort of arrangement gives a unique name for each configuration file + variation. This can help eliminate ambiguity when several servers have + their configurations all stored in one place, such as in a version + control repository. (Storing database configuration files under version + control is another good practice to consider). + + + File Locations -- cgit v1.2.3