CREATE DATABASE
CREATE DATABASE — создать базу данных
Синтаксис
CREATE DATABASEимя[ WITH ] [ OWNER [=]имя_пользователя] [ TEMPLATE [=]шаблон] [ ENCODING [=]кодировка] [ STRATEGY [=]стратегия] [ LOCALE [=]локаль] [ LC_COLLATE [=]категория_сортировки] [ LC_CTYPE [=]категория_типов_символов] [ BUILTIN_LOCALE [=]локаль_builtin] [ ICU_LOCALE [=]локаль_icu] [ ICU_RULES [=]правила_icu] [ LOCALE_PROVIDER [=]провайдер_локали] [ COLLATION_VERSION =версия_правил_сортировки] [ TABLESPACE [=]табл_пространство] [ ALLOW_CONNECTIONS [=]разр_подключения] [ CONNECTION LIMIT [=]предел_подключений] [ IS_TEMPLATE [=]это_шаблон] [ OID [=]oid]
Описание
Команда CREATE DATABASE создаёт базу данных PostgreSQL.
Чтобы создать базу данных, необходимо быть суперпользователем или иметь специальное право CREATEDB. См. CREATE ROLE.
По умолчанию новая база данных создаётся копированием стандартной системной базы данных template1. Задать другой шаблон можно, добавив указание TEMPLATE . В частности, написав имяTEMPLATE template0, можно создать чистую базу данных (в которой никаких пользовательских объектов нет, есть только системные объекты в первозданном виде), содержащую только стандартные объекты, предопределённые установленной версией PostgreSQL. Это бывает полезно, когда копировать в новую базу любые дополнительные объекты, добавленные локально в template1, нежелательно.
Параметры
имя#Имя создаваемой базы данных.
имя_пользователя#Имя пользователя (роли), назначаемого владельцем новой базы данных, либо
DEFAULT, чтобы владельцем стал пользователь по умолчанию (а именно, пользователь, выполняющий команду). Чтобы создать базу данных и сделать её владельцем другую роль, необходимо иметь правоSET ROLEдля этой роли.шаблон#Имя шаблона, из которого будет создаваться новая база данных, либо
DEFAULT, чтобы выбрать шаблон по умолчанию (template1).кодировка#Кодировка символов в новой базе данных. Укажите строковую константу (например,
'SQL_ASCII') или целочисленный номер кодировки, либоDEFAULT, чтобы выбрать кодировку по умолчанию (а именно, кодировку шаблона). Наборы символов, которые поддерживает PostgreSQL, перечислены в Подразделе 23.3.1. Дополнительные ограничения описаны ниже.стратегия#Стратегия, которая будет использоваться при создании новой базы данных. Если используется стратегия
WAL_LOG, база данных будет копироваться блок за блоком и каждый блок будет отдельно записан в журнал предзаписи. Эта стратегия наиболее эффективна в случаях, когда шаблонная база данных небольшого размера, поэтому такая стратегия используется по умолчанию. Также доступна старая стратегияFILE_COPY. Если выбрана эта стратегия, делается небольшая запись в журнал предзаписи для каждого табличного пространства, используемого целевой базой данных. Каждая такая запись является копией всего каталога в другом месте на уровне файловой системы. Хотя такая стратегия существенно уменьшает объём журнала упреждающей записи, особенно если шаблонная база данных большого размера, она требует выполнения процедуры контрольной точки как до, так и после создания новой базы данных. В некоторых ситуациях это может оказать заметное негативное влияние на общую производительность системы.локаль#Задаёт порядок сортировки по умолчанию и особенности классификации символов для новой базы данных. Правила сортировки определяют порядок сортировки строк, например в запросах с
ORDER BY, а также порядок индексов по текстовым столбцам. Классификация символов определяет принадлежность символов категориям, например строчные, заглавные и цифры. Этот параметр также устанавливает соответствующие переменные окружения ОС,LC_COLLATEиLC_CTYPE. По умолчанию используется значение из шаблона. Подробное описание представлено в Подразделе 23.2.2.3.1 и Подразделе 23.2.2.3.2.Параметр можно переопределить, задав один из следующих параметров:
категория_сортировки,категория_типов_символов,локаль_builtinилилокаль_icu.При значении
builtinупровайдер_локалинеобходимо указатьлокальилилокаль_builtinи задать для них значениеCилиC.UTF-8.Подсказка
Другие параметры локали lc_messages, lc_monetary, lc_numeric и lc_time задаются не на уровне базы данных и этой командой не устанавливаются. Чтобы изменить их значения по умолчанию для конкретной базы, воспользуйтесь командой
ALTER DATABASE ... SET.категория_сортировки#Устанавливает значение
LC_COLLATEв окружении ОС сервера баз данных. По умолчанию используется значениелокаль(если оно указано), в противном случае — значение из шаблона. Дополнительные ограничения описаны ниже.Если для
провайдер_локализадано значениеlibc, этот параметр также задаёт порядок сортировки по умолчанию для новой базы данных, переопределяя значениелокаль.категория_типов_символов#Устанавливает значение
LC_CTYPEв окружении ОС сервера баз данных. По умолчанию используется значениелокаль(если оно указано), в противном случае — значение из шаблона. Дополнительные ограничения описаны ниже.Если для
провайдер_локализадано значениеlibc, этот параметр также задаёт классификацию символов по умолчанию для новой базы данных, переопределяя значениелокаль.локаль_builtin#Задаёт локаль провайдера
builtinдля установки порядка сортировки по умолчанию и особенностей классификации символов, переопределяя значениелокаль. При этом должно быть задано значениеbuiltinдля провайдера локалей. По умолчанию используется значение излокаль(если оно указано), в противном случае — значение из базы-шаблона.Локали, доступные для провайдера
builtin:CиC.UTF-8.локаль_icu#Задаёт локаль ICU (см. Подраздел 23.2.2.3.2) для установки порядка сортировки по умолчанию и особенностей классификации символов, переопределяя значение
локаль. При этом должен быть задан провайдер локалей ICU. По умолчанию используется значение излокаль(если оно указано), в противном случае — значение из базы-шаблона.правила_icu#Указывает дополнительные правила для настройки поведения сортировки по умолчанию. Параметр поддерживается только для ICU. За дополнительной информацией обратитесь к https://unicode-org.github.io/icu/userguide/collation/customization/.
провайдер_локали#Задаёт провайдера, который будет использоваться для основного правила сортировки в этой базе данных. Возможные значения:
builtin,icu(если сервер собран с поддержкой ICU) илиlibc. По умолчанию выбирается провайдер, указанный вшаблон. За подробностями обратитесь к Подразделу 23.1.4.версия_правил_сортировки#Задаёт строку версии правила сортировки, которая будет записана с объектом базы данных. Обычно её не следует задавать — тогда эта строка будет получена из фактической версии правила сортировки БД, предоставляемого операционной системой. Это указание предназначено для того, чтобы утилита
pg_upgradeмогла скопировать версию из существующей инсталляции.Что делать в случае несовпадения версий правил сортировки, описано в ALTER DATABASE.
табл_пространство#Имя табличного пространства, связываемого с новой базой данных, или
DEFAULTдля использования табличного пространства шаблона. Это табличное пространство будет использоваться по умолчанию для объектов, создаваемых в этой базе. За подробностями обратитесь к CREATE TABLESPACE.разр_подключения#Если false, никто не сможет подключаться к этой базе данных. По умолчанию имеет значение true, то есть подключения принимаются (если не ограничиваются другими механизмами, например,
GRANT/REVOKE CONNECT).предел_подключений#Максимальное количество одновременных подключений к этой базе данных. Значение -1 (по умолчанию) снимает ограничение.
это_шаблон#Если true, базу данных сможет клонировать любой пользователь с правами
CREATEDB; в противном случае (по умолчанию), клонировать эту базу смогут только суперпользователи и её владелец.oid#Идентификатор объекта, который будет назначен новой базе данных. Если этот параметр не указан, PostgreSQL автоматически выберет подходящий OID. Этот параметр в первую очередь предназначен для внутреннего использования в pg_upgrade, и только pg_upgrade может указывать значение меньше 16384.
Дополнительные параметры могут записываться в любом порядке, не обязательно так, как показано выше.
Примечания
CREATE DATABASE нельзя выполнять внутри блока транзакции.
Ошибки, содержащие сообщение «не удалось инициализировать каталог базы данных», чаще всего связаны с нехваткой прав в каталоге данных, заполнением диска или другими проблемами в файловой системе.
Для удаления базы данных применяется DROP DATABASE.
Программа createdb представляет собой оболочку этой команды, созданную ради удобства.
Конфигурационные параметры уровня базы данных (устанавливаемые командой ALTER DATABASE) и разрешения уровня базы (устанавливаемые командой GRANT) из шаблона не копируются.
Хотя с помощью этой команды можно скопировать любую базу данных, а не только template1, указав её имя в качестве имени шаблона, она не предназначена (пока) для использования в качестве универсального средства вроде «COPY DATABASE». Принципиальным ограничением является невозможность копирования базы данных шаблона, если установлены другие подключения к ней. CREATE DATABASE выдаёт ошибку, если при запуске команды есть другие подключения к этой базе; в противном случае новые подключения к базе блокируются до завершения команды CREATE DATABASE. За дополнительными сведениями обратитесь к Разделу 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; В этом примере предложение TEMPLATE template0 необходимо, только если указанная локаль отличается от локали в template1. (В противном случае явное указание локали является избыточным.)
Создание базы данных music2 с другой локалью и другой кодировкой символов:
CREATE DATABASE music2
LOCALE 'sv_SE.iso885915'
ENCODING LATIN9
TEMPLATE template0;Свойства кодировки должны соответствовать локали, иначе возникнет ошибка.
Заметьте, что имена локалей зависят от операционной системы, так что показанные выше команды могут не везде работать одинаково.
Совместимость
Оператор CREATE DATABASE отсутствует в стандарте SQL. Базы данных равнозначны каталогам, а их создание в стандарте определяется реализацией.
См. также
ALTER DATABASE, DROP DATABASECREATE DATABASE
CREATE DATABASE — create a new database
Synopsis
CREATE DATABASEname[ 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]
Description
CREATE DATABASE creates a new PostgreSQL database.
To create a database, you must be a superuser or have the special CREATEDB privilege. See CREATE ROLE.
By default, the new database will be created by cloning the standard system database template1. A different template can be specified by writing TEMPLATE . In particular, by writing nameTEMPLATE template0, you can create a pristine database (one where no user-defined objects exist and where the system objects have not been altered) containing only the standard objects predefined by your version of PostgreSQL. This is useful if you wish to avoid copying any installation-local objects that might have been added to template1.
Parameters
name#The name of a database to create.
user_name#The role name of the user who will own the new database, or
DEFAULTto use the default (namely, the user executing the command). To create a database owned by another role, you must be able toSET ROLEto that role.template#The name of the template from which to create the new database, or
DEFAULTto use the default template (template1).encoding#Character set encoding to use in the new database. Specify a string constant (e.g.,
'SQL_ASCII'), or an integer encoding number, orDEFAULTto use the default encoding (namely, the encoding of the template database). The character sets supported by the PostgreSQL server are described in Section 23.3.1. See below for additional restrictions.strategy#Strategy to be used in creating the new database. If the
WAL_LOGstrategy is used, the database will be copied block by block and each block will be separately written to the write-ahead log. This is the most efficient strategy in cases where the template database is small, and therefore it is the default. The olderFILE_COPYstrategy is also available. This strategy writes a small record to the write-ahead log for each tablespace used by the target database. Each such record represents copying an entire directory to a new location at the filesystem level. While this does reduce the write-ahead log volume substantially, especially if the template database is large, it also forces the system to perform a checkpoint both before and after the creation of the new database. In some situations, this may have a noticeable negative impact on overall system performance.locale#Sets the default collation order and character classification in the new database. Collation affects the sort order applied to strings, e.g., in queries with
ORDER BY, as well as the order used in indexes on text columns. Character classification affects the categorization of characters, e.g., lower, upper, and digit. Also sets the associated aspects of the operating system environment,LC_COLLATEandLC_CTYPE. The default is the same setting as the template database. See Section 23.2.2.3.1 and Section 23.2.2.3.2 for details.Can be overridden by setting
lc_collate,lc_ctype,builtin_locale, oricu_localeindividually.If
locale_providerisbuiltin, thenlocaleorbuiltin_localemust be specified and set to eitherCorC.UTF-8.Tip
The other locale settings lc_messages, lc_monetary, lc_numeric, and lc_time are not fixed per database and are not set by this command. If you want to make them the default for a specific database, you can use
ALTER DATABASE ... SET.lc_collate#Sets
LC_COLLATEin the database server's operating system environment. The default is the setting oflocaleif specified, otherwise the same setting as the template database. See below for additional restrictions.If
locale_providerislibc, also sets the default collation order to use in the new database, overriding the settinglocale.lc_ctype#Sets
LC_CTYPEin the database server's operating system environment. The default is the setting oflocaleif specified, otherwise the same setting as the template database. See below for additional restrictions.If
locale_providerislibc, also sets the default character classification to use in the new database, overriding the settinglocale.builtin_locale#Specifies the builtin provider locale for the database default collation order and character classification, overriding the setting
locale. The locale provider must bebuiltin. The default is the setting oflocaleif specified; otherwise the same setting as the template database.The locales available for the
builtinprovider areCandC.UTF-8.icu_locale#Specifies the ICU locale (see Section 23.2.2.3.2) for the database default collation order and character classification, overriding the setting
locale. The locale provider must be ICU. The default is the setting oflocaleif specified; otherwise the same setting as the template database.icu_rules#Specifies additional collation rules to customize the behavior of the default collation of this database. This is supported for ICU only. See Section 23.2.3.4 for details.
locale_provider#Specifies the provider to use for the default collation in this database. Possible values are
builtin,icu(if the server was built with ICU support) orlibc. By default, the provider is the same as that of thetemplate. See Section 23.1.4 for details.collation_version#Specifies the collation version string to store with the database. Normally, this should be omitted, which will cause the version to be computed from the actual version of the database collation as provided by the operating system. This option is intended to be used by
pg_upgradefor copying the version from an existing installation.See also ALTER DATABASE for how to handle database collation version mismatches.
tablespace_name#The name of the tablespace that will be associated with the new database, or
DEFAULTto use the template database's tablespace. This tablespace will be the default tablespace used for objects created in this database. See CREATE TABLESPACE for more information.allowconn#If false then no one can connect to this database. The default is true, allowing connections (except as restricted by other mechanisms, such as
GRANT/REVOKE CONNECT).connlimit#How many concurrent connections can be made to this database. -1 (the default) means no limit.
istemplate#If true, then this database can be cloned by any user with
CREATEDBprivileges; if false (the default), then only superusers or the owner of the database can clone it.oid#The object identifier to be used for the new database. If this parameter is not specified, PostgreSQL will choose a suitable OID automatically. This parameter is primarily intended for internal use by pg_upgrade, and only pg_upgrade can specify a value less than 16384.
Optional parameters can be written in any order, not only the order illustrated above.
Notes
CREATE DATABASE cannot be executed inside a transaction block.
Errors along the line of “could not initialize database directory” are most likely related to insufficient permissions on the data directory, a full disk, or other file system problems.
Use DROP DATABASE to remove a database.
The program createdb is a wrapper program around this command, provided for convenience.
Database-level configuration parameters (set via ALTER DATABASE) and database-level permissions (set via GRANT) are not copied from the template database.
Although it is possible to copy a database other than template1 by specifying its name as the template, this is not (yet) intended as a general-purpose “COPY DATABASE” facility. The principal limitation is that no other sessions can be connected to the template database while it is being copied. CREATE DATABASE will fail if any other connection exists when it starts; otherwise, new connections to the template database are locked out until CREATE DATABASE completes. See Section 22.3 for more information.
The character set encoding specified for the new database must be compatible with the chosen locale settings (LC_COLLATE and LC_CTYPE). If the locale is C (or equivalently POSIX), then all encodings are allowed, but for other locale settings there is only one encoding that will work properly. (On Windows, however, UTF-8 encoding can be used with any locale.) CREATE DATABASE will allow superusers to specify SQL_ASCII encoding regardless of the locale settings, but this choice is deprecated and may result in misbehavior of character-string functions if data that is not encoding-compatible with the locale is stored in the database.
The encoding and locale settings must match those of the template database, except when template0 is used as template. This is because other databases might contain data that does not match the specified encoding, or might contain indexes whose sort ordering is affected by LC_COLLATE and LC_CTYPE. Copying such data would result in a database that is corrupt according to the new settings. template0, however, is known to not contain any data or indexes that would be affected.
There is currently no option to use a database locale with nondeterministic comparisons (see CREATE COLLATION for an explanation). If this is needed, then per-column collations would need to be used.
The CONNECTION LIMIT option is only enforced approximately; if two new sessions start at about the same time when just one connection “slot” remains for the database, it is possible that both will fail. Also, the limit is not enforced against superusers or background worker processes.
Examples
To create a new database:
CREATE DATABASE lusiadas;
To create a database sales owned by user salesapp with a default tablespace of salesspace:
CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
To create a database music with a different locale:
CREATE DATABASE music
LOCALE 'sv_SE.utf8'
TEMPLATE template0;
In this example, the TEMPLATE template0 clause is required if the specified locale is different from the one in template1. (If it is not, then specifying the locale explicitly is redundant.)
To create a database music2 with a different locale and a different character set encoding:
CREATE DATABASE music2
LOCALE 'sv_SE.iso885915'
ENCODING LATIN9
TEMPLATE template0;
The specified locale and encoding settings must match, or an error will be reported.
Note that locale names are specific to the operating system, so that the above commands might not work in the same way everywhere.
Compatibility
There is no CREATE DATABASE statement in the SQL standard. Databases are equivalent to catalogs, whose creation is implementation-defined.
