PostgreSQL Source Code  git master
option.c
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * option.c
4  * FDW and GUC option handling for postgres_fdw
5  *
6  * Portions Copyright (c) 2012-2023, PostgreSQL Global Development Group
7  *
8  * IDENTIFICATION
9  * contrib/postgres_fdw/option.c
10  *
11  *-------------------------------------------------------------------------
12  */
13 #include "postgres.h"
14 
15 #include "access/reloptions.h"
19 #include "commands/defrem.h"
20 #include "commands/extension.h"
21 #include "libpq/libpq-be.h"
22 #include "postgres_fdw.h"
23 #include "utils/builtins.h"
24 #include "utils/guc.h"
25 #include "utils/varlena.h"
26 
27 /*
28  * Describes the valid options for objects that this wrapper uses.
29  */
30 typedef struct PgFdwOption
31 {
32  const char *keyword;
33  Oid optcontext; /* OID of catalog in which option may appear */
34  bool is_libpq_opt; /* true if it's used in libpq */
36 
37 /*
38  * Valid options for postgres_fdw.
39  * Allocated and filled in InitPgFdwOptions.
40  */
42 
43 /*
44  * Valid options for libpq.
45  * Allocated and filled in InitPgFdwOptions.
46  */
48 
49 /*
50  * GUC parameters
51  */
53 
54 /*
55  * Helper functions
56  */
57 static void InitPgFdwOptions(void);
58 static bool is_valid_option(const char *keyword, Oid context);
59 static bool is_libpq_option(const char *keyword);
60 
61 #include "miscadmin.h"
62 
63 /*
64  * Validate the generic options given to a FOREIGN DATA WRAPPER, SERVER,
65  * USER MAPPING or FOREIGN TABLE that uses postgres_fdw.
66  *
67  * Raise an ERROR if the option or its value is considered invalid.
68  */
70 
71 Datum
73 {
74  List *options_list = untransformRelOptions(PG_GETARG_DATUM(0));
75  Oid catalog = PG_GETARG_OID(1);
76  ListCell *cell;
77 
78  /* Build our options lists if we didn't yet. */
80 
81  /*
82  * Check that only options supported by postgres_fdw, and allowed for the
83  * current object type, are given.
84  */
85  foreach(cell, options_list)
86  {
87  DefElem *def = (DefElem *) lfirst(cell);
88 
89  if (!is_valid_option(def->defname, catalog))
90  {
91  /*
92  * Unknown option specified, complain about it. Provide a hint
93  * with a valid option that looks similar, if there is one.
94  */
95  PgFdwOption *opt;
96  const char *closest_match;
98  bool has_valid_options = false;
99 
101  for (opt = postgres_fdw_options; opt->keyword; opt++)
102  {
103  if (catalog == opt->optcontext)
104  {
105  has_valid_options = true;
107  }
108  }
109 
110  closest_match = getClosestMatch(&match_state);
111  ereport(ERROR,
112  (errcode(ERRCODE_FDW_INVALID_OPTION_NAME),
113  errmsg("invalid option \"%s\"", def->defname),
114  has_valid_options ? closest_match ?
115  errhint("Perhaps you meant the option \"%s\".",
116  closest_match) : 0 :
117  errhint("There are no valid options in this context.")));
118  }
119 
120  /*
121  * Validate option value, when we can do so without any context.
122  */
123  if (strcmp(def->defname, "use_remote_estimate") == 0 ||
124  strcmp(def->defname, "updatable") == 0 ||
125  strcmp(def->defname, "truncatable") == 0 ||
126  strcmp(def->defname, "async_capable") == 0 ||
127  strcmp(def->defname, "parallel_commit") == 0 ||
128  strcmp(def->defname, "keep_connections") == 0)
129  {
130  /* these accept only boolean values */
131  (void) defGetBoolean(def);
132  }
133  else if (strcmp(def->defname, "fdw_startup_cost") == 0 ||
134  strcmp(def->defname, "fdw_tuple_cost") == 0)
135  {
136  /*
137  * These must have a floating point value greater than or equal to
138  * zero.
139  */
140  char *value;
141  double real_val;
142  bool is_parsed;
143 
144  value = defGetString(def);
145  is_parsed = parse_real(value, &real_val, 0, NULL);
146 
147  if (!is_parsed)
148  ereport(ERROR,
149  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
150  errmsg("invalid value for floating point option \"%s\": %s",
151  def->defname, value)));
152 
153  if (real_val < 0)
154  ereport(ERROR,
155  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
156  errmsg("\"%s\" must be a floating point value greater than or equal to zero",
157  def->defname)));
158  }
159  else if (strcmp(def->defname, "extensions") == 0)
160  {
161  /* check list syntax, warn about uninstalled extensions */
162  (void) ExtractExtensionList(defGetString(def), true);
163  }
164  else if (strcmp(def->defname, "fetch_size") == 0 ||
165  strcmp(def->defname, "batch_size") == 0)
166  {
167  char *value;
168  int int_val;
169  bool is_parsed;
170 
171  value = defGetString(def);
172  is_parsed = parse_int(value, &int_val, 0, NULL);
173 
174  if (!is_parsed)
175  ereport(ERROR,
176  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
177  errmsg("invalid value for integer option \"%s\": %s",
178  def->defname, value)));
179 
180  if (int_val <= 0)
181  ereport(ERROR,
182  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
183  errmsg("\"%s\" must be an integer value greater than zero",
184  def->defname)));
185  }
186  else if (strcmp(def->defname, "password_required") == 0)
187  {
188  bool pw_required = defGetBoolean(def);
189 
190  /*
191  * Only the superuser may set this option on a user mapping, or
192  * alter a user mapping on which this option is set. We allow a
193  * user to clear this option if it's set - in fact, we don't have
194  * a choice since we can't see the old mapping when validating an
195  * alter.
196  */
197  if (!superuser() && !pw_required)
198  ereport(ERROR,
199  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
200  errmsg("password_required=false is superuser-only"),
201  errhint("User mappings with the password_required option set to false may only be created or modified by the superuser.")));
202  }
203  else if (strcmp(def->defname, "sslcert") == 0 ||
204  strcmp(def->defname, "sslkey") == 0)
205  {
206  /* similarly for sslcert / sslkey on user mapping */
207  if (catalog == UserMappingRelationId && !superuser())
208  ereport(ERROR,
209  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
210  errmsg("sslcert and sslkey are superuser-only"),
211  errhint("User mappings with the sslcert or sslkey options set may only be created or modified by the superuser.")));
212  }
213  else if (strcmp(def->defname, "analyze_sampling") == 0)
214  {
215  char *value;
216 
217  value = defGetString(def);
218 
219  /* we recognize off/auto/random/system/bernoulli */
220  if (strcmp(value, "off") != 0 &&
221  strcmp(value, "auto") != 0 &&
222  strcmp(value, "random") != 0 &&
223  strcmp(value, "system") != 0 &&
224  strcmp(value, "bernoulli") != 0)
225  ereport(ERROR,
226  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
227  errmsg("invalid value for string option \"%s\": %s",
228  def->defname, value)));
229  }
230  }
231 
232  PG_RETURN_VOID();
233 }
234 
235 /*
236  * Initialize option lists.
237  */
238 static void
240 {
241  int num_libpq_opts;
242  PQconninfoOption *lopt;
243  PgFdwOption *popt;
244 
245  /* non-libpq FDW-specific FDW options */
246  static const PgFdwOption non_libpq_options[] = {
247  {"schema_name", ForeignTableRelationId, false},
248  {"table_name", ForeignTableRelationId, false},
249  {"column_name", AttributeRelationId, false},
250  /* use_remote_estimate is available on both server and table */
251  {"use_remote_estimate", ForeignServerRelationId, false},
252  {"use_remote_estimate", ForeignTableRelationId, false},
253  /* cost factors */
254  {"fdw_startup_cost", ForeignServerRelationId, false},
255  {"fdw_tuple_cost", ForeignServerRelationId, false},
256  /* shippable extensions */
257  {"extensions", ForeignServerRelationId, false},
258  /* updatable is available on both server and table */
259  {"updatable", ForeignServerRelationId, false},
260  {"updatable", ForeignTableRelationId, false},
261  /* truncatable is available on both server and table */
262  {"truncatable", ForeignServerRelationId, false},
263  {"truncatable", ForeignTableRelationId, false},
264  /* fetch_size is available on both server and table */
265  {"fetch_size", ForeignServerRelationId, false},
266  {"fetch_size", ForeignTableRelationId, false},
267  /* batch_size is available on both server and table */
268  {"batch_size", ForeignServerRelationId, false},
269  {"batch_size", ForeignTableRelationId, false},
270  /* async_capable is available on both server and table */
271  {"async_capable", ForeignServerRelationId, false},
272  {"async_capable", ForeignTableRelationId, false},
273  {"parallel_commit", ForeignServerRelationId, false},
274  {"keep_connections", ForeignServerRelationId, false},
275  {"password_required", UserMappingRelationId, false},
276 
277  /* sampling is available on both server and table */
278  {"analyze_sampling", ForeignServerRelationId, false},
279  {"analyze_sampling", ForeignTableRelationId, false},
280 
281  /*
282  * sslcert and sslkey are in fact libpq options, but we repeat them
283  * here to allow them to appear in both foreign server context (when
284  * we generate libpq options) and user mapping context (from here).
285  */
286  {"sslcert", UserMappingRelationId, true},
287  {"sslkey", UserMappingRelationId, true},
288 
289  {NULL, InvalidOid, false}
290  };
291 
292  /* Prevent redundant initialization. */
294  return;
295 
296  /*
297  * Get list of valid libpq options.
298  *
299  * To avoid unnecessary work, we get the list once and use it throughout
300  * the lifetime of this backend process. We don't need to care about
301  * memory context issues, because PQconndefaults allocates with malloc.
302  */
304  if (!libpq_options) /* assume reason for failure is OOM */
305  ereport(ERROR,
306  (errcode(ERRCODE_FDW_OUT_OF_MEMORY),
307  errmsg("out of memory"),
308  errdetail("Could not get libpq's default connection options.")));
309 
310  /* Count how many libpq options are available. */
311  num_libpq_opts = 0;
312  for (lopt = libpq_options; lopt->keyword; lopt++)
313  num_libpq_opts++;
314 
315  /*
316  * Construct an array which consists of all valid options for
317  * postgres_fdw, by appending FDW-specific options to libpq options.
318  *
319  * We use plain malloc here to allocate postgres_fdw_options because it
320  * lives as long as the backend process does. Besides, keeping
321  * libpq_options in memory allows us to avoid copying every keyword
322  * string.
323  */
325  malloc(sizeof(PgFdwOption) * num_libpq_opts +
326  sizeof(non_libpq_options));
327  if (postgres_fdw_options == NULL)
328  ereport(ERROR,
329  (errcode(ERRCODE_FDW_OUT_OF_MEMORY),
330  errmsg("out of memory")));
331 
332  popt = postgres_fdw_options;
333  for (lopt = libpq_options; lopt->keyword; lopt++)
334  {
335  /* Hide debug options, as well as settings we override internally. */
336  if (strchr(lopt->dispchar, 'D') ||
337  strcmp(lopt->keyword, "fallback_application_name") == 0 ||
338  strcmp(lopt->keyword, "client_encoding") == 0)
339  continue;
340 
341  /* We don't have to copy keyword string, as described above. */
342  popt->keyword = lopt->keyword;
343 
344  /*
345  * "user" and any secret options are allowed only on user mappings.
346  * Everything else is a server option.
347  */
348  if (strcmp(lopt->keyword, "user") == 0 || strchr(lopt->dispchar, '*'))
349  popt->optcontext = UserMappingRelationId;
350  else
351  popt->optcontext = ForeignServerRelationId;
352  popt->is_libpq_opt = true;
353 
354  popt++;
355  }
356 
357  /* Append FDW-specific options and dummy terminator. */
358  memcpy(popt, non_libpq_options, sizeof(non_libpq_options));
359 }
360 
361 /*
362  * Check whether the given option is one of the valid postgres_fdw options.
363  * context is the Oid of the catalog holding the object the option is for.
364  */
365 static bool
366 is_valid_option(const char *keyword, Oid context)
367 {
368  PgFdwOption *opt;
369 
370  Assert(postgres_fdw_options); /* must be initialized already */
371 
372  for (opt = postgres_fdw_options; opt->keyword; opt++)
373  {
374  if (context == opt->optcontext && strcmp(opt->keyword, keyword) == 0)
375  return true;
376  }
377 
378  return false;
379 }
380 
381 /*
382  * Check whether the given option is one of the valid libpq options.
383  */
384 static bool
385 is_libpq_option(const char *keyword)
386 {
387  PgFdwOption *opt;
388 
389  Assert(postgres_fdw_options); /* must be initialized already */
390 
391  for (opt = postgres_fdw_options; opt->keyword; opt++)
392  {
393  if (opt->is_libpq_opt && strcmp(opt->keyword, keyword) == 0)
394  return true;
395  }
396 
397  return false;
398 }
399 
400 /*
401  * Generate key-value arrays which include only libpq options from the
402  * given list (which can contain any kind of options). Caller must have
403  * allocated large-enough arrays. Returns number of options found.
404  */
405 int
406 ExtractConnectionOptions(List *defelems, const char **keywords,
407  const char **values)
408 {
409  ListCell *lc;
410  int i;
411 
412  /* Build our options lists if we didn't yet. */
414 
415  i = 0;
416  foreach(lc, defelems)
417  {
418  DefElem *d = (DefElem *) lfirst(lc);
419 
420  if (is_libpq_option(d->defname))
421  {
422  keywords[i] = d->defname;
423  values[i] = defGetString(d);
424  i++;
425  }
426  }
427  return i;
428 }
429 
430 /*
431  * Parse a comma-separated string and return a List of the OIDs of the
432  * extensions named in the string. If any names in the list cannot be
433  * found, report a warning if warnOnMissing is true, else just silently
434  * ignore them.
435  */
436 List *
437 ExtractExtensionList(const char *extensionsString, bool warnOnMissing)
438 {
439  List *extensionOids = NIL;
440  List *extlist;
441  ListCell *lc;
442 
443  /* SplitIdentifierString scribbles on its input, so pstrdup first */
444  if (!SplitIdentifierString(pstrdup(extensionsString), ',', &extlist))
445  {
446  /* syntax error in name list */
447  ereport(ERROR,
448  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
449  errmsg("parameter \"%s\" must be a list of extension names",
450  "extensions")));
451  }
452 
453  foreach(lc, extlist)
454  {
455  const char *extension_name = (const char *) lfirst(lc);
456  Oid extension_oid = get_extension_oid(extension_name, true);
457 
458  if (OidIsValid(extension_oid))
459  {
460  extensionOids = lappend_oid(extensionOids, extension_oid);
461  }
462  else if (warnOnMissing)
463  {
465  (errcode(ERRCODE_UNDEFINED_OBJECT),
466  errmsg("extension \"%s\" is not installed",
467  extension_name)));
468  }
469  }
470 
471  list_free(extlist);
472  return extensionOids;
473 }
474 
475 /*
476  * Replace escape sequences beginning with % character in the given
477  * application_name with status information, and return it.
478  *
479  * This function always returns a palloc'd string, so the caller is
480  * responsible for pfreeing it.
481  */
482 char *
483 process_pgfdw_appname(const char *appname)
484 {
485  const char *p;
487 
489 
490  for (p = appname; *p != '\0'; p++)
491  {
492  if (*p != '%')
493  {
494  /* literal char, just copy */
496  continue;
497  }
498 
499  /* must be a '%', so skip to the next char */
500  p++;
501  if (*p == '\0')
502  break; /* format error - ignore it */
503  else if (*p == '%')
504  {
505  /* string contains %% */
506  appendStringInfoChar(&buf, '%');
507  continue;
508  }
509 
510  /* process the option */
511  switch (*p)
512  {
513  case 'a':
515  break;
516  case 'c':
517  appendStringInfo(&buf, "%lx.%x", (long) (MyStartTime), MyProcPid);
518  break;
519  case 'C':
521  break;
522  case 'd':
523  if (MyProcPort)
524  {
525  const char *dbname = MyProcPort->database_name;
526 
527  if (dbname)
529  else
530  appendStringInfoString(&buf, "[unknown]");
531  }
532  break;
533  case 'p':
534  appendStringInfo(&buf, "%d", MyProcPid);
535  break;
536  case 'u':
537  if (MyProcPort)
538  {
539  const char *username = MyProcPort->user_name;
540 
541  if (username)
543  else
544  appendStringInfoString(&buf, "[unknown]");
545  }
546  break;
547  default:
548  /* format error - ignore it */
549  break;
550  }
551  }
552 
553  return buf.data;
554 }
555 
556 /*
557  * Module load callback
558  */
559 void
560 _PG_init(void)
561 {
562  /*
563  * Unlike application_name GUC, don't set GUC_IS_NAME flag nor check_hook
564  * to allow postgres_fdw.application_name to be any string more than
565  * NAMEDATALEN characters and to include non-ASCII characters. Instead,
566  * remote server truncates application_name of remote connection to less
567  * than NAMEDATALEN and replaces any non-ASCII characters in it with a '?'
568  * character.
569  */
570  DefineCustomStringVariable("postgres_fdw.application_name",
571  "Sets the application name to be used on the remote server.",
572  NULL,
574  NULL,
575  PGC_USERSET,
576  0,
577  NULL,
578  NULL,
579  NULL);
580 
581  MarkGUCPrefixReserved("postgres_fdw");
582 }
static Datum values[MAXATTR]
Definition: bootstrap.c:156
#define OidIsValid(objectId)
Definition: c.h:759
void _PG_init(void)
Definition: option.c:560
char * process_pgfdw_appname(const char *appname)
Definition: option.c:483
static bool is_valid_option(const char *keyword, Oid context)
Definition: option.c:366
static PQconninfoOption * libpq_options
Definition: option.c:47
int ExtractConnectionOptions(List *defelems, const char **keywords, const char **values)
Definition: option.c:406
static bool is_libpq_option(const char *keyword)
Definition: option.c:385
List * ExtractExtensionList(const char *extensionsString, bool warnOnMissing)
Definition: option.c:437
Datum postgres_fdw_validator(PG_FUNCTION_ARGS)
Definition: option.c:72
static PgFdwOption * postgres_fdw_options
Definition: option.c:41
struct PgFdwOption PgFdwOption
PG_FUNCTION_INFO_V1(postgres_fdw_validator)
char * pgfdw_application_name
Definition: option.c:52
static void InitPgFdwOptions(void)
Definition: option.c:239
bool defGetBoolean(DefElem *def)
Definition: define.c:108
char * defGetString(DefElem *def)
Definition: define.c:49
int errdetail(const char *fmt,...)
Definition: elog.c:1202
int errhint(const char *fmt,...)
Definition: elog.c:1316
int errcode(int sqlerrcode)
Definition: elog.c:858
int errmsg(const char *fmt,...)
Definition: elog.c:1069
#define WARNING
Definition: elog.h:36
#define ERROR
Definition: elog.h:39
#define ereport(elevel,...)
Definition: elog.h:149
Oid get_extension_oid(const char *extname, bool missing_ok)
Definition: extension.c:144
PQconninfoOption * PQconndefaults(void)
Definition: fe-connect.c:1665
#define PG_RETURN_VOID()
Definition: fmgr.h:349
#define PG_GETARG_OID(n)
Definition: fmgr.h:275
#define PG_GETARG_DATUM(n)
Definition: fmgr.h:268
#define PG_FUNCTION_ARGS
Definition: fmgr.h:193
int MyProcPid
Definition: globals.c:44
struct Port * MyProcPort
Definition: globals.c:47
pg_time_t MyStartTime
Definition: globals.c:45
bool parse_int(const char *value, int *result, int flags, const char **hintmsg)
Definition: guc.c:2824
void DefineCustomStringVariable(const char *name, const char *short_desc, const char *long_desc, char **valueAddr, const char *bootValue, GucContext context, int flags, GucStringCheckHook check_hook, GucStringAssignHook assign_hook, GucShowHook show_hook)
Definition: guc.c:5044
bool parse_real(const char *value, double *result, int flags, const char **hintmsg)
Definition: guc.c:2914
void MarkGUCPrefixReserved(const char *className)
Definition: guc.c:5105
@ PGC_USERSET
Definition: guc.h:75
char * cluster_name
Definition: guc_tables.c:527
char * application_name
Definition: guc_tables.c:535
#define malloc(a)
Definition: header.h:50
struct parser_state match_state[5]
static struct @145 value
int i
Definition: isn.c:73
Assert(fmt[strlen(fmt) - 1] !='\n')
List * lappend_oid(List *list, Oid datum)
Definition: list.c:374
void list_free(List *list)
Definition: list.c:1545
char * pstrdup(const char *in)
Definition: mcxt.c:1624
#define lfirst(lc)
Definition: pg_list.h:172
#define NIL
Definition: pg_list.h:68
static char * buf
Definition: pg_test_fsync.c:67
const char * username
Definition: pgbench.c:306
uintptr_t Datum
Definition: postgres.h:64
#define InvalidOid
Definition: postgres_ext.h:36
unsigned int Oid
Definition: postgres_ext.h:31
List * untransformRelOptions(Datum options)
Definition: reloptions.c:1333
char * dbname
Definition: streamutil.c:51
void appendStringInfo(StringInfo str, const char *fmt,...)
Definition: stringinfo.c:91
void appendStringInfoString(StringInfo str, const char *s)
Definition: stringinfo.c:176
void appendStringInfoChar(StringInfo str, char ch)
Definition: stringinfo.c:188
void initStringInfo(StringInfo str)
Definition: stringinfo.c:59
char * defname
Definition: parsenodes.h:810
Definition: pg_list.h:54
Oid optcontext
Definition: option.c:33
const char * keyword
Definition: option.c:32
bool is_libpq_opt
Definition: option.c:34
char * user_name
Definition: libpq-be.h:166
char * database_name
Definition: libpq-be.h:165
bool superuser(void)
Definition: superuser.c:46
const char * getClosestMatch(ClosestMatchState *state)
Definition: varlena.c:6169
bool SplitIdentifierString(char *rawstring, char separator, List **namelist)
Definition: varlena.c:3455
void initClosestMatch(ClosestMatchState *state, const char *source, int max_d)
Definition: varlena.c:6114
void updateClosestMatch(ClosestMatchState *state, const char *candidate)
Definition: varlena.c:6134