PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

CREATE DATABASE

CREATE DATABASE — 创建一个新数据库

Synopsis

CREATE DATABASE name
    [ WITH ] [ OWNER [=] user_name ]
           [ TEMPLATE [=] template ]
           [ ENCODING [=] encoding ]
           [ STRATEGY [=] strategy ]
           [ LOCALE [=] locale ]
           [ LC_COLLATE [=] lc_collate ]
           [ LC_CTYPE [=] lc_ctype ]
           [ BUILTIN_LOCALE [=] builtin_locale ]
           [ ICU_LOCALE [=] icu_locale ]
           [ ICU_RULES [=] icu_rules ]
           [ LOCALE_PROVIDER [=] locale_provider ]
           [ COLLATION_VERSION = collation_version ]
           [ TABLESPACE [=] tablespace_name ]
           [ ALLOW_CONNECTIONS [=] allowconn ]
           [ CONNECTION LIMIT [=] connlimit ]
           [ IS_TEMPLATE [=] istemplate ]
           [ OID [=] oid ]

描述

CREATE DATABASE 创建一个新的 PostgreSQL 数据库。

要创建数据库,你必须是超级用户或者拥有特殊的 CREATEDB 特权。参见 CREATE ROLE。

默认情况下,新数据库将通过克隆标准系统数据库 template1 来创建。可以通过书写 TEMPLATE name 来指定一个不同的模板。特别地,通过书写 TEMPLATE template0,你可以创建一个原始的数据库(其中不存在任何用户定义的对象,且系统对象未被修改过),它只包含你的 PostgreSQL 版本所预定义的标准对象。如果你希望避免复制可能已经被加入到 template1 中的任何本地安装对象,这会很有用。

参数

name #

要创建的数据库的名字。

user_name #

将拥有新数据库的用户的角色名,或者用 DEFAULT 表示使用默认值(即执行该命令的用户)。要创建一个由其他角色拥有的数据库,你必须能够 SET ROLE 到该角色。

template #

用于创建新数据库的模板的名字,或者用 DEFAULT 表示使用默认模板(template1)。

encoding #

新数据库中要使用的字符集编码。可以指定一个字符串常量(例如 'SQL_ASCII')、一个整数编码编号,或者用 DEFAULT 表示使用默认编码(即模板数据库的编码)。PostgreSQL 服务器支持的字符集在 Section 23.3.1 中描述。其他限制见下文。

strategy #

创建新数据库时要采用的策略。如果使用 WAL_LOG 策略,数据库将被逐块复制,并且每个块都会被单独写入预写式日志。在模板数据库较小的情况下,这是效率最高的策略,因此它也是默认值。较旧的 FILE_COPY 策略也可用。该策略会为目标数据库使用的每个表空间向预写式日志写入一条小记录。每条这样的记录代表在文件系统层级把一个完整的目录复制到新位置。虽然这样做会大幅减少预写式日志的写入量(尤其是当模板数据库很大时),但它也会迫使系统在新数据库创建之前和之后各执行一次检查点。在某些情况下,这可能会对整体系统性能产生明显的负面影响。FILE_COPY 策略会受到 file_copy_method 设置的影响。

locale #

设置新数据库中的默认排序规则和字符分类。排序规则影响应用于字符串的排序顺序(例如在带有 ORDER BY 的查询中),以及文本列索引中使用的顺序。字符分类影响字符的归类,例如小写、大写和数字。它还会设置操作系统环境中相关的方面,即 LC_COLLATE 和 LC_CTYPE。默认值为与模板数据库相同的设置。详情参见 Section 23.2.2.3.1 和 Section 23.2.2.3.2。

可以通过单独设置 lc_collate、lc_ctype、builtin_locale 或 icu_locale 来覆盖它。

如果 locale_provider 为 builtin,则必须指定 locale 或 builtin_locale,并将其设置为 C、C.UTF-8 或 PG_UNICODE_FAST 之一。

Tip

其他排序规则设置 lc_messages、lc_monetary、lc_numeric 和 lc_time 不是每个数据库固定的,也不会被此命令设置。如果你想让它们成为某个特定数据库的默认值,可以使用 ALTER DATABASE ... SET。

lc_collate #

在数据库服务器的操作系统环境中设置 LC_COLLATE。默认值为 locale 的设置(如果指定了的话),否则与模板数据库的设置相同。其他限制见下文。

如果 locale_provider 为 libc,还会设置新数据库中使用的默认排序规则,从而覆盖 locale 的设置。

lc_ctype #

在数据库服务器的操作系统环境中设置 LC_CTYPE。默认值为 locale 的设置(如果指定了的话),否则与模板数据库的设置相同。其他限制见下文。

如果 locale_provider 为 libc,还会设置新数据库中使用的默认字符分类,从而覆盖 locale 的设置。

builtin_locale #

指定用于数据库默认排序规则和字符分类的 builtin 提供者排序规则,从而覆盖 locale 的设置。排序规则提供者必须是 builtin。默认值为 locale 的设置(如果指定了的话);否则与模板数据库的设置相同。

builtin 提供者可用的排序规则为 C、C.UTF-8 和 PG_UNICODE_FAST。

icu_locale #

指定用于数据库默认排序规则和字符分类的 ICU 排序规则(参见 Section 23.2.2.3.2),从而覆盖 locale 的设置。排序规则提供者必须是 ICU。默认值为 locale 的设置(如果指定了的话);否则与模板数据库的设置相同。

icu_rules #

指定额外的排序规则来自定义该数据库默认排序行为。仅 ICU 支持此选项。详情参见 Section 23.2.3.4。

locale_provider #

指定该数据库默认排序规则使用的提供者。可能的值为 builtin、icu(如果服务器在编译时启用了 ICU 支持)或 libc。默认情况下,提供者与 template 的相同。详情参见 Section 23.1.4。

collation_version #

指定要随数据库一起存储的排序规则版本字符串。通常应省略此选项,这样版本将根据操作系统所提供的数据库排序规则的实际版本计算得出。此选项旨在供 pg_upgrade 用来从现有安装中复制版本。

有关如何处理数据库排序规则版本不匹配的信息,另请参见 ALTER DATABASE。

tablespace_name #

将与新数据库关联的表空间的名字,或者用 DEFAULT 表示使用模板数据库的表空间。该表空间将成为在此数据库中创建的对象所使用的默认表空间。更多信息参见 CREATE TABLESPACE。

allowconn #

如果为 false,则任何人都无法连接到该数据库。默认值为 true,即允许连接(除非受到其他机制的限制,例如 GRANT/REVOKE CONNECT)。

connlimit #

可以建立到该数据库的并发连接数。默认值 -1 表示不设限制。

istemplate #

如果为 true,则任何拥有 CREATEDB 特权的用户都可以克隆该数据库;如果为 false(默认值),则只有超级用户或数据库所有者才能克隆它。

oid #

用于新数据库的对象标识符。如果不指定此参数,PostgreSQL 会自动选择一个合适的 OID。此参数主要供 pg_upgrade 内部使用,并且只有 pg_upgrade 能指定小于 16384 的值。

可选参数可以按任意顺序书写,而不限于上面演示的顺序。

注记

CREATE DATABASE 不能在事务块内执行。

诸如“无法初始化数据库目录”之类的错误最有可能与数据目录权限不足、磁盘已满或其他文件系统问题有关。

使用 DROP DATABASE 来删除数据库。

程序 createdb 是此命令的一个包装程序,为方便起见而提供。

数据库级别的配置参数(通过 ALTER DATABASE 设置)和数据库级别的权限(通过 GRANT 设置)不会从模板数据库复制。

虽然可以通过把名字指定为模板来复制 template1 之外的数据库,但这(还)不是一种通用的“COPY DATABASE”工具。主要限制是,在被复制期间不能有其他会话连接到模板数据库。如果启动时存在任何其他连接,CREATE DATABASE 将失败;否则,在 CREATE DATABASE 完成之前,到模板数据库的新连接会被阻止。更多信息参见 Section 22.3。

为新数据库指定的字符集编码必须与所选的排序规则设置(LC_COLLATE 和 LC_CTYPE)兼容。如果排序规则为 C(或等效的 POSIX),则允许所有编码;但对于其他排序规则设置,只有一种编码能正常工作。(不过在 Windows 上,UTF-8 编码可以与任何排序规则一起使用。)CREATE DATABASE 允许超级用户无视排序规则设置而指定 SQL_ASCII 编码,但不推荐这样做,因为如果将与该排序规则的编码不兼容的数据存储在数据库中,可能会导致字符串函数行为异常。

编码和排序规则设置必须与模板数据库的设置相匹配,除非使用 template0 作为模板。这是因为其他数据库可能包含与指定编码不匹配的数据,或者包含其排序顺序受 LC_COLLATE 和 LC_CTYPE 影响的索引。复制这样的数据会按照新设置产生一个损坏的数据库。然而,template0 被认为不包含任何会受影响的数据或索引。

目前没有选项可以使用带非确定性比较的数据库排序规则(解释参见 CREATE COLLATION)。如果需要这种功能,则必须改用列级排序规则。

CONNECTION LIMIT 选项的强制执行只是近似的;当该数据库只剩下一个连接“槽”时,如果两个新会话几乎同时启动,则有可能两个都会失败。另外,此限制不会对超级用户或后台工作进程强制执行。

示例

创建一个新数据库:

CREATE DATABASE lusiadas;

创建一个数据库 sales,由用户 salesapp 拥有,默认表空间为 salesspace:

CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;

创建一个使用不同排序规则的数据库 music:

CREATE DATABASE music
    LOCALE 'sv_SE.utf8'
    TEMPLATE template0;

在此示例中,如果指定的排序规则与 template1 中的不同,则 TEMPLATE template0 子句是必需的。(如果不是,则显式指定排序规则是多余的。)

创建一个使用不同排序规则和不同字符集编码的数据库 music2:

CREATE DATABASE music2
    LOCALE 'sv_SE.iso885915'
    ENCODING LATIN9
    TEMPLATE template0;

指定的排序规则和编码设置必须匹配,否则将报告错误。

请注意,排序规则的名称与特定操作系统相关,因此上述命令在不同系统上的表现可能不一致。

兼容性

SQL 标准中没有 CREATE DATABASE 语句。数据库等同于目录(catalog),目录的创建方式由具体实现定义。

另请参阅

ALTER DATABASE, DROP DATABASE