PostgreSQL数据库扩展包——原理CreateExtension扩展控制文件解析

createExtension函数

首先看createExtension函数，该函数首先调用check_valid_extension_name函数在任何访问文件系统之前检测extension的名字的合法性；调用get_extension_oid检测数据库是否已经安装该扩展（参加PostgreSQL数据库TableAM——systable操作）；使用全局变量creating_extension确保同一时刻只能创建一个扩展；通过遍历CreateExtensionStmt结构体，初始化d_schema、d_new_version、d_old_version、d_cascade等变量；最后调用CreateExtensionInternal(stmt->extname, schemaName, versionName, oldVersionName, cascade, NIL, true)函数。

ObjectAddress CreateExtension(ParseState *pstate, CreateExtensionStmt *stmt) {
  DefElem    *d_schema = NULL;
  DefElem    *d_new_version = NULL;
  DefElem    *d_old_version = NULL;
  DefElem    *d_cascade = NULL;
  char     *schemaName = NULL;
  char     *versionName = NULL;
  char     *oldVersionName = NULL;
  bool    cascade = false;
  ListCell   *lc;
  check_valid_extension_name(stmt->extname);
  if (get_extension_oid(stmt->extname, true) != InvalidOid){
    if (stmt->if_not_exists){ ereport(NOTICE,(errcode(ERRCODE_DUPLICATE_OBJECT),errmsg("extension \"%s\" already exists, skipping",stmt->extname)));return InvalidObjectAddress;
    }else
      ereport(ERROR,(errcode(ERRCODE_DUPLICATE_OBJECT),errmsg("extension \"%s\" already exists",stmt->extname))); }
  /* We use global variables to track the extension being created, so we can create only one extension at the same time. */
  if (creating_extension)
    ereport(ERROR, (errcode(ERRCODE_FEATURE_NOT_SUPPORTED), errmsg("nested CREATE EXTENSION is not supported")));
  /* Deconstruct the statement option list */
  foreach(lc, stmt->options){
    DefElem    *defel = (DefElem *) lfirst(lc);
    if (strcmp(defel->defname, "schema") == 0) {
      if (d_schema) ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("conflicting or redundant options"), parser_errposition(pstate, defel->location)));
      d_schema = defel;
      schemaName = defGetString(d_schema);
    } else if (strcmp(defel->defname, "new_version") == 0) {
      if (d_new_version) ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("conflicting or redundant options"), parser_errposition(pstate, defel->location)));
      d_new_version = defel;
      versionName = defGetString(d_new_version);
    } else if (strcmp(defel->defname, "old_version") == 0) {
      if (d_old_version) ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("conflicting or redundant options"), parser_errposition(pstate, defel->location)));
      d_old_version = defel;
      oldVersionName = defGetString(d_old_version);
    } else if (strcmp(defel->defname, "cascade") == 0) {
      if (d_cascade)
        ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("conflicting or redundant options"), parser_errposition(pstate, defel->location)));
      d_cascade = defel;
      cascade = defGetBoolean(d_cascade);
    } else
      elog(ERROR, "unrecognized option: %s", defel->defname);
  }
  /* Call CreateExtensionInternal to do the real work. */
  return CreateExtensionInternal(stmt->extname, schemaName, versionName, oldVersionName, cascade, NIL, true);
}

CreateExtensionInternal函数

​​static ObjectAddress CreateExtensionInternal(char *extensionName, char *schemaName, const char *versionName, const char *oldVersionName, bool cascade, List *parents, bool is_create)​​当指定cascade，如果依赖的扩展需要被安装，则会递归调用CreateExtensionInternal函数。parent列表参数包含已经安装的扩展。

static ObjectAddress CreateExtensionInternal(char *extensionName, char *schemaName, const char *versionName, const char *oldVersionName, bool cascade, List *parents, bool is_create) {
  char     *origSchemaName = schemaName;
  Oid      schemaOid = InvalidOid;
  Oid      extowner = GetUserId();
  ExtensionControlFile *pcontrol;
  ExtensionControlFile *control;
  List     *updateVersions;
  List     *requiredExtensions;
  List     *requiredSchemas;
  Oid      extensionOid;
  ObjectAddress address;
  ListCell   *lc;
  /* Read the primary control file.  Note we assume that it does not contain any non-ASCII data, so there is no need to worry about encoding at this point. */
  pcontrol = read_extension_control_file(extensionName);

read_extension_control_file读取primary control file，主要调用parse_extension_control_file函数。parse_extension_control_file函数解析控制文件，取出调用具体版本，文件名等信息。如果version为NULL，则进行primary file的处理；否则进行optional auxiliary文件的处理。get_extension_control_filename(control->name)函数获取文件全路径sharepath/extension/extname.control。将文件内容读取并将键值内容转换ConfigVariable列表，并将其值赋给ExtensionControlFile结构体相应的成员。

static ExtensionControlFile *read_extension_control_file(const char *extname) {
  ExtensionControlFile *control;
  /* Set up default values.  Pointer fields are initially null. */
  control = (ExtensionControlFile *) palloc0(sizeof(ExtensionControlFile));
  control->name = pstrdup(extname);
  control->relocatable = false;
  control->superuser = true;
  control->encoding = -1;
  /* Parse the primary control file. */
  parse_extension_control_file(control, NULL);
  return control;
}

static void parse_extension_control_file(ExtensionControlFile *control, const char *version){
  char     *filename;
  FILE     *file;
  ConfigVariable *item, *head = NULL, *tail = NULL;
  /* Locate the file to read.  Auxiliary files are optional. */
  if (version)
    filename = get_extension_aux_control_filename(control, version);
  else
    filename = get_extension_control_filename(control->name);
  if ((file = AllocateFile(filename, "r")) == NULL) {
    if (version && errno == ENOENT) { /* no auxiliary file for this version */    
      pfree(filename); return;
    }
    ereport(ERROR, (errcode_for_file_access(), errmsg("could not open extension control file \"%s\": %m", filename)));
  }

  /* Parse the file content, using GUC's file parsing code.  We need not check the return value since any errors will be thrown at ERROR level. */
  (void) ParseConfigFp(file, filename, 0, ERROR, &head, &tail);
  FreeFile(file);
  /* Convert the ConfigVariable list into ExtensionControlFile entries. */
  for (item = head; item != NULL; item = item->next){
    if (strcmp(item->name, "directory") == 0){
      if (version) ereport(ERROR,(errcode(ERRCODE_SYNTAX_ERROR), errmsg("parameter \"%s\" cannot be set in a secondary extension control file", item->name)));
      control->directory = pstrdup(item->value);
    } else if (strcmp(item->name, "default_version") == 0) {
      if (version) ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("parameter \"%s\" cannot be set in a secondary extension control file", item->name)));
      control->default_version = pstrdup(item->value);
    } else if (strcmp(item->name, "module_pathname") == 0) {
      control->module_pathname = pstrdup(item->value);
    } else if (strcmp(item->name, "comment") == 0) {
      control->comment = pstrdup(item->value);
    } else if (strcmp(item->name, "schema") == 0) {
      control->schema = pstrdup(item->value);
    } else if (strcmp(item->name, "relocatable") == 0) {
      if (!parse_bool(item->value, &control->relocatable)) ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE), errmsg("parameter \"%s\" requires a Boolean value", item->name)));
    } else if (strcmp(item->name, "superuser") == 0) {
      if (!parse_bool(item->value, &control->superuser)) ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE), errmsg("parameter \"%s\" requires a Boolean value", item->name)));
    } else if (strcmp(item->name, "encoding") == 0) {
      control->encoding = pg_valid_server_encoding(item->value);
      if (control->encoding < 0) ereport(ERROR, (errcode(ERRCODE_UNDEFINED_OBJECT), errmsg("\"%s\" is not a valid encoding name", item->value)));
    } else if (strcmp(item->name, "requires") == 0){
      /* Need a modifiable copy of string */
      char     *rawnames = pstrdup(item->value);
      /* Parse string into list of identifiers */
      if (!SplitIdentifierString(rawnames, ',', &control->requires)) {
        /* syntax error in name list */
        ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE), errmsg("parameter \"%s\" must be a list of extension names", item->name)));
      }
    } else
      ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("unrecognized parameter \"%s\" in file \"%s\"", item->name, filename)));
  }
  FreeConfigVariables(head);
  if (control->relocatable && control->schema != NULL)
    ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), errmsg("parameter \"schema\" cannot be specified when \"relocatable\" is true")));
  pfree(filename);
}

CreateExtensionInternal函数如果没有获得versionName，则需要取pcontrol->default_version作为versionName。

/* Determine the version to install */
  if (versionName == NULL){
    if (pcontrol->default_version)
      versionName = pcontrol->default_version;
    else
      ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE), errmsg("version to install must be specified")));
  }
  check_valid_version_name(versionName);

CreateExtensionInternal函数下面的逻辑是寻找指定版本扩展的脚本，如果没有该版本的脚本，则寻找更新版本的脚本（identify_update_path）。

if (oldVersionName) {
    /* "FROM old_version" was specified, indicating that we're trying to update from some unpackaged version of the extension.  Locate a series of update scripts that will do it. */
    check_valid_version_name(oldVersionName);
    if (strcmp(oldVersionName, versionName) == 0)
      ereport(ERROR,(errcode(ERRCODE_INVALID_PARAMETER_VALUE),errmsg("FROM version must be different from installation target version \"%s\"",versionName)));
    updateVersions = identify_update_path(pcontrol, oldVersionName, versionName);
    if (list_length(updateVersions) == 1) {
      /* Simple case where there's just one update script to run. We will not need any follow-on update steps. */
      Assert(strcmp((char *) linitial(updateVersions), versionName) == 0);
      updateVersions = NIL;
    }else{
      /* Multi-step sequence.  We treat this as installing the version that is the target of the first script, followed by successive updates to the later versions. */
      versionName = (char *) linitial(updateVersions);
      updateVersions = list_delete_first(updateVersions);
    }
  }else{
    /* No FROM, so we're installing from scratch.  If there is an install script for the desired version, we only need to run that one. */
    char     *filename;
    struct stat fst;
    oldVersionName = NULL;
    filename = get_extension_script_filename(pcontrol, NULL, versionName);
    if (stat(filename, &fst) == 0) {
      /* Easy, no extra scripts */
      updateVersions = NIL;
    } else {
      /* Look for best way to install this version */
      List     *evi_list;
      ExtensionVersionInfo *evi_start;
      ExtensionVersionInfo *evi_target;
      /* Extract the version update graph from the script directory */
      evi_list = get_ext_ver_list(pcontrol);
      /* Identify the target version */
      evi_target = get_ext_ver_info(versionName, &evi_list);
      /* Identify best path to reach target */
      evi_start = find_install_path(evi_list, evi_target, &updateVersions);
      /* Fail if no path ... */
      if (evi_start == NULL) ereport(ERROR,(errcode(ERRCODE_INVALID_PARAMETER_VALUE),errmsg("extension \"%s\" has no installation script nor update path for version \"%s\"",pcontrol->name, versionName)));
      /* Otherwise, install best starting point and then upgrade */
      versionName = evi_start->name;
    }
  }

get_extension_script_filename​函数调用如下：
get_ext_ver_list()：遍历所有.sql文件获取所有版本节点。
find_install_path()：根据目标节点选择最短路径以及相对应的起始节点。
find_update_path()：最短路径算法Dijkstra的实现。
get_extension_script_filename获取sql文件名，规则如下：
版本命名的规则:扩展名 +“–”+“版本号”+ .sql (eg:cube–1.2.sql)
版本与版本之间的升级采用“–”连接。(eg:cube–1.2–1.3.sql)
Target 版本由控制文件中的default_version确定。
根据目标版本选择最短路径。

为需要按照的目标版本获取control参数，read_extension_aux_control_file获取aux控制文件ExtensionControlFile结构体。

/* Fetch control parameters for installation target version */
  control = read_extension_aux_control_file(pcontrol, versionName);

先通过schemaName获取schemaOid，如果control->schema不为NULL，使用control->schema作为schemaName，再通过该schemaName获取schemaOid，如果不存在相关schemaOid，则通过CreateSchemaCommand创建Schema。
如果control->schema为NULL，判别先通过schemaName获取的schemaOid是否为合法，不合法则从默认creation namespace获取该schemaOid所代表的scchemaName。

/* Determine the target schema to install the extension into */
  if (schemaName){ /* If the user is giving us the schema name, it must exist already. */
    schemaOid = get_namespace_oid(schemaName, false); }
  if (control->schema != NULL) {
    /* The extension is not relocatable and the author gave us a schema for it. Unless CASCADE parameter was given, it's an error to give a schema different from control->schema if control->schema is specified. */
    if (schemaName && strcmp(control->schema, schemaName) != 0 && !cascade)
      ereport(ERROR, (errcode(ERRCODE_FEATURE_NOT_SUPPORTED), errmsg("extension \"%s\" must be installed in schema \"%s\"", control->name, control->schema)));
    /* Always use the schema from control file for current extension. */
    schemaName = control->schema;
    /* Find or create the schema in case it does not exist. */
    schemaOid = get_namespace_oid(schemaName, true);
    if (!OidIsValid(schemaOid)){
      CreateSchemaStmt *csstmt = makeNode(CreateSchemaStmt);
      csstmt->schemaname = schemaName;
      csstmt->authrole = NULL;  /* will be created by current user */
      csstmt->schemaElts = NIL;
      csstmt->if_not_exists = false;
      CreateSchemaCommand(csstmt, "(generated CREATE SCHEMA command)", -1, -1);
      /* CreateSchemaCommand includes CommandCounterIncrement, so new schema is now visible. */
      schemaOid = get_namespace_oid(schemaName, false);
    }
  } else if (!OidIsValid(schemaOid)) {
    /* Neither user nor author of the extension specified schema; use the current default creation namespace, which is the first explicit entry in the search_path. */
    List     *search_path = fetch_search_path(false);
    if (search_path == NIL) /* nothing valid in search_path? */
      ereport(ERROR, (errcode(ERRCODE_UNDEFINED_SCHEMA), errmsg("no schema has been selected to create in")));
    schemaOid = linitial_oid(search_path);
    schemaName = get_namespace_name(schemaOid);
    if (schemaName == NULL) /* recently-deleted namespace? */
      ereport(ERROR, (errcode(ERRCODE_UNDEFINED_SCHEMA), errmsg("no schema has been selected to create in")));
    list_free(search_path);
  }

/* Make note if a temporary namespace has been accessed in this transaction. */
  if (isTempNamespace(schemaOid))
    MyXactFlags |= XACT_FLAGS_ACCESSEDTEMPNAMESPACE;
  /*
   * We don't check creation rights on the target namespace here.  If the
   * extension script actually creates any objects there, it will fail if
   * the user doesn't have such permissions.  But there are cases such as
   * procedural languages where it's convenient to set schema = pg_catalog
   * yet we don't want to restrict the command to users with ACL_CREATE for
   * pg_catalog.
   */

查找该扩展依赖的其他扩展，并安装它们，并将get_required_extension和get_extension_schema函数放入get_extension_schema和requiredSchemas列表。

/* Look up the prerequisite extensions, install them if necessary, and build lists of their OIDs and the OIDs of their target schemas. */
  requiredExtensions = NIL;
  requiredSchemas = NIL;
  foreach(lc, control->requires){
    char     *curreq = (char *) lfirst(lc);
    Oid      reqext;
    Oid      reqschema;
    reqext = get_required_extension(curreq,extensionName,origSchemaName,cascade,parents,is_create);
    reqschema = get_extension_schema(reqext);
    requiredExtensions = lappend_oid(requiredExtensions, reqext);
    requiredSchemas = lappend_oid(requiredSchemas, reqschema);
  }

InsertExtensionTuple():把控制文件的信息保存到Tuple中。

/* Insert new tuple into pg_extension, and create dependency entries. */
  address = InsertExtensionTuple(control->name, extowner, schemaOid, control->relocatable, versionName, PointerGetDatum(NULL), PointerGetDatum(NULL), requiredExtensions);
  extensionOid = address.objectId;
  /* Apply any control-file comment on extension */
  if (control->comment != NULL)
    CreateComments(extensionOid, ExtensionRelationId, 0, control->comment);

execute_sql_string():解析sql文件。先调用pg_parse_query将sql转换成parsetree_list。

/* Execute the installation script file */
  execute_extension_script(extensionOid, control, oldVersionName, versionName, requiredSchemas, schemaName, schemaOid);

  /* If additional update scripts have to be executed, apply the updates as though a series of ALTER EXTENSION UPDATE commands were given */
  ApplyExtensionUpdates(extensionOid, pcontrol, versionName, updateVersions, origSchemaName, cascade, is_create);
  return address;
}

然后执行pg_analyze_and_rewrite(),pg_plan_queries()，ExecutorRun()对每一个parse tree重写执行。