↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

文档 / SQL 命令 / 数据库、模式与表空间

SQL COMMAND · 数据库、模式与表空间

CREATE DATABASE

创建一个新数据库

CREATE数据库、模式与表空间引入 10（基线）现存至 20 devel2 次语法变更

动词
CREATE
对象
DATABASE
引入版本
10（基线）
状态
现存
语法变更次数
2
手册小节数
6

本站手册 · 18官方文档 ↗

版本轨迹

相对 PostgreSQL 17 语法未变，正文有更新。

语法铁道图 PostgreSQL 18

沿轨道从左向右阅读，分岔表示选择，绕行表示可选，回环表示重复。方框为参数，点击带下划线的参数可展开子规则。

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 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 ]

PostgreSQL 18 手册 · 查看完整参考页

描述

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 不能在事务块内执行。

形如 “could not initialize database directory” 的错误， 多半与数据目录权限不足、磁盘已满或其他文件系统问题有关。

使用 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;

要创建一个由用户 salesapp 拥有、默认表空间为 salesspace 的数据库 sales：

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 语句。数据库相当于目录，而目录的创建由实现定义。

参见

ALTER DATABASE, DROP DATABASE

语法演化

相邻大版本之间的差异，新的在前。版本号链接到对应快照。

  1. PostgreSQL 20← 19正文更新

    正文更新

  2. PostgreSQL 19← 18正文更新

    正文更新

  3. PostgreSQL 18← 17正文更新

    正文更新

  4. PostgreSQL 16← 15正文更新

    正文更新

  5. PostgreSQL 14← 13语法变化

    + [ STRATEGY [=] strategy ]+ [ BUILTIN_LOCALE [=] builtin_locale ]+ [ ICU_LOCALE [=] icu_locale ]+ [ ICU_RULES [=] icu_rules ]+ [ LOCALE_PROVIDER [=] locale_provider ]+ [ COLLATION_VERSION = collation_version ]+ [ OID [=] oid ]正文更新

  6. PostgreSQL 13← 12语法变化

    + [ LOCALE [=] locale ]正文更新

  7. PostgreSQL 11← 10正文更新

    正文更新

同组命令

命令动词对象版本变动最近变更
DATABASES & SCHEMAS数据库、模式与表空间9 条↑
CREATE DATABASECREATEDATABASE 142 次
创建一个新数据库现存
ALTER DATABASEALTERDATABASE 141 次
更改一个数据库现存
DROP DATABASEDROPDATABASE 131 次
移除一个数据库现存
CREATE SCHEMACREATESCHEMA 141 次
定义一个新模式现存
ALTER SCHEMAALTERSCHEMA 141 次
更改一个模式的定义现存
DROP SCHEMADROPSCHEMA —
移除一个模式现存
CREATE TABLESPACECREATETABLESPACE 141 次
定义一个新表空间现存
ALTER TABLESPACEALTERTABLESPACE 141 次
更改一个表空间的定义现存
DROP TABLESPACEDROPTABLESPACE —
移除一个表空间现存