================
CREATE EXTENSION
================


.. container:: refentry
   :name: SQL-CREATEEXTENSION

   .. container:: titlepage

   .. container:: refnamediv

      .. rubric:: CREATE EXTENSION
         :name: create-extension

      CREATE EXTENSION — 安装一个扩展

   .. container:: refsynopsisdiv

      .. rubric:: 大纲
         :name: 大纲

      .. code:: synopsis

         CREATE EXTENSION [ IF NOT EXISTS ] extension_name
             [ WITH ] [ SCHEMA schema_name ]
                      [ VERSION version ]
                      [ FROM old_version ]
                      [ CASCADE ]

   .. container:: refsect1
      :name: id-1.9.3.64.5

      .. rubric:: 描述
         :name: 描述

      ``CREATE EXTENSION``\ 把一个新的扩展载入到
      当前数据库中。不能有同名扩展已经被载入。

      载入一个扩展本质上是运行该扩展的脚本文件。该脚本通常将创建新的
      SQL对象，例如函数、数据类型、操作符以及索引支持
      方法。\ ``CREATE EXTENSION``\ 会额外地记录
      所有被创建对象的标识，这样发出
      ``DROP EXTENSION``\ 时可以删除它们。

      载入一个扩展要求创建其组件对象所要求的权限。对于大部分扩展这意味
      这需要超级用户或者数据库拥有者的特权。为了以后权限检查的目的，运行
      ``CREATE EXTENSION``\ 的用户会成为该扩展的
      拥有者以及由该扩展的脚本创建的任何对象的拥有者。

   .. container:: refsect1
      :name: id-1.9.3.64.6

      .. rubric:: 参数
         :name: 参数

      .. container:: variablelist

         ``IF NOT EXISTS``
            已有同名扩展存在时不要抛出错误。这种情况下会发出一个提示。
            注意，不保证现有的扩展与将要从当前可用的脚本文件创建的脚本
            有任何相似。

         ``extension_name``
            要安装的扩展的名称。OushuDB 将使用文件
            ``SHAREDIR/extension/``\ ``extension_name``\ ``.control``
            中的指令来创建该扩展。

         ``schema_name``
            假定该扩展允许其内容被重定位，这是要在其中安装该扩展的对象的
            模式名称。被提到的模式必须已经存在。如果没有指定并且该扩展的
            控制文件也没有指定一个模式，将使用当前的默认对象创建模式。

            如果该扩展在其控制文件中指定了一个\ ``schema``\ 参数，
            那么不能用\ ``SCHEMA``\ 子句覆盖该模式。通常，如果
            给出了一个\ ``SCHEMA``\ 子句并且它与扩展的
            ``schema``\ 参数冲突，则会发生错误。不过，如果也给
            出了\ ``CASCADE``\ 子句，则schema冲突时会忽略
            ``schema_name``\ 。 给定的\ ``schema_name``
            将被用来安装任何需要的并且没有在其控制文件中指定
            ``schema``\ 的扩展。

            记住扩展本身被认为不在任何模式中：扩展具有无限定的名称，并且
            要在整个数据库范围内唯一。但是属于扩展的对象可以在模式中。

         ``version``
            要安装的扩展的版本。这可以写成一个标识符或者一个字符串。
            默认版本在该扩展的控制文件中指定。

         ``old_version``
            当且仅当尝试要安装一个扩展来替代一个“老式”
            的模块（它只是一组没有被打包成扩展的对象的集合）时，
            才必须指定 ``FROM`` ``old_version``\ 。
            这个选项导致\ ``CREATE EXTENSION``\ 运行
            另一个安装脚本把现有的对象吸收到该扩展中，而不是创建
            新对象。当心\ ``SCHEMA``\ 指定的是包含已经存在 对象的模式。

            用于\ ``old_version``\ 的值由扩展的作者决定，
            且如果有多于一种版本的老式模块可以被升级到扩展，该值还可能变化。
            对于 9.1 之前的PostgreSQL提供的
            标准附加模块，在升级模块到扩展风格时要为
            ``old_version``\ 使用 ``unpackaged``\ 。

         ``CASCADE``
            自动安装这个扩展所依赖的任何还未安装的扩展。它们的依赖也会同样
            被自动安装。如果给出\ ``SCHEMA``\ 子句，它会应用于这种方式
            下安装的所有扩展。这个语句的其他选项不会被应用于自动安装的扩展。
            特别地，这些自动安装的扩展的默认版本将被选中。

   .. container:: refsect1
      :name: id-1.9.3.64.7

      .. rubric:: 注解
         :name: 注解

      在使用\ ``CREATE EXTENSION``\ 载入扩展到数据库中之前，
      必须先安装好该扩展的支持文件。

      当前可以用于载入的扩展可以在系统视图
      ```pg_available_extensions``
      或者
      ```pg_available_extension_versions``
      中看到。

   .. container:: refsect1
      :name: id-1.9.3.64.8

      .. rubric:: 示例
         :name: 示例

      安装\ `hstore <hstore.html>`__\ 扩展到当前数据库中：

      .. code:: programlisting

         CREATE EXTENSION hstore;

      升级一个 9.1 之前的\ ``hstore``\ 安装成为扩展：

      .. code:: programlisting

         CREATE EXTENSION hstore SCHEMA public FROM unpackaged;

      要小心地指定安装现有\ ``hstore``\ 对象的模式。

   .. container:: refsect1
      :name: id-1.9.3.64.9

      .. rubric:: 兼容性
         :name: 兼容性

      ``CREATE EXTENSION``\ 是一种 OushuDB 扩展。

   .. container:: refsect1
      :name: id-1.9.3.64.10

      .. rubric:: 另见
         :name: 另见

      `ALTER EXTENSION <sql-alterextension.html>`__, `DROP
      EXTENSION <sql-dropextension.html>`__