createdb

createdb — создать новую базу данных QHB

Синтаксис

createdb [флаг...] [параметр-подключения...] --host=хост [аргумент...]

Описание

Утилита createdb создает новую базу данных QHB.

Обычно пользователь базы данных, который выполняет эту команду, становится владельцем новой базы данных. Однако с помощью параметра -O можно указать и другого владельца, если у текущего пользователя имеются соответствующие права.

createdb — это обертка для команды SQL CREATE DATABASE. Между созданием баз данных с помощью этой утилиты и их созданием иными способами при обращении к серверу по сути нет никакой разницы.

Если имя базы данных не указано, то используется имя пользователя, от которого выполняется программа; аналогичный алгоритм применяется и относительно владельца базы данных.

Если базу данных невозможно создать, то программа выведет сообщение об ошибке, при этом иногда предлагая решение проблемы.

Параметры

createdb принимает следующие аргументы командной строки:

Флаги

-?
--help
Показать справку об аргументах командной строки createdb и завершиться.

-V
--version
Вывести версию createdb и завершиться.

-v
--verbose
Задает уровень ведения журнала в Debug. Значение по умолчанию — Info.

-w
--no-password
Никогда не запрашивать ввод пароля. Если серверу требуется аутентификация по паролю, и пароль недоступен с помощью иных средств, таких как файл .pgpass, попытка подключения завершится неудачно. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, чтобы ввести пароль.

-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.

Это несущественный параметр, так как createdb автоматически запросит пароль, если сервер требует аутентификацию по паролю. Однако чтобы выяснить это, createdb потребуется дополнительная попытка подключения к серверу. В некоторых случаях имеет смысл ввести -W, чтобы исключить эту лишнюю попытку.

Параметры подключения

-D табличное_пространство
--tablespace=табличное_пространство
Задает табличное пространство, которое по умолчанию будет использоваться в базе данных. (Это имя обрабатывается аналогично идентификатору, заключенному в кавычки.)

-e
--echo
Отобразить на экране команды, которые createdb генерирует и отправляет на сервер.

-E кодировка
--encoding=кодировка
Задает схему кодировки символов, которая будет использоваться в этой базе данных. Поддерживаемые сервером QHB кодировки описаны в подразделе Поддерживаемые кодировки.

-h хост
--host=хост
Задает имя хост-компьютера, на котором работает сервер. Если значение начинается со слэша, оно используется в качестве каталога для Unix-сокета. Вместо этого параметра можно воспользоваться переменной среды PGHOST.

-l локаль
--locale=локаль
Задает локаль, которая будет использоваться в этой базе данных. Этот параметр равнозначен одновременной установке флагов --lc-collate и --lc-ctype.

--lc-collate=локаль
Задает параметр LC_COLLATE, который будет использоваться в этой базе данных.

--lc-ctype=локаль
Задает параметр LC_CTYPE, который будет использоваться в этой базе данных.

--maintenance-db=имя_бд
Задает имя базы данных, к которой будет произведено подключение при создании новой базы данных. Если это имя не указано, будет выбрана база данных qhb, а если она не существует (или это имя новой базы данных) — template1.

-O владелец
--owner=владелец
Указывает пользователя базы данных, которому будет принадлежать новая база данных. (Это имя обрабатывается аналогично идентификатору, заключенному в кавычки.)

-p порт
--port=порт
Указывает TCP-порт или расширение файла локального Unix-сокета, через который сервер принимает подключения. Значение по умолчанию — 5432.

-T шаблон
--template=шаблон
Задает шаблон, на основе которого будет создана эта база данных. (Это имя обрабатывается аналогично идентификатору, заключенному в кавычки.)

-U имя_пользователя
--username=имя_пользователя
Имя пользователя, под которым производится подключение.

Аргументы

имя_бд
Задает имя создаваемой базы данных. Имя должно быть уникальным среди всех баз данных QHB в этом кластере. По умолчанию в качестве имени новой базы данных выбирается имя текущего системного пользователя. Вместо этого параметра можно воспользоваться переменной среды PGDATABASE.

комментарий
Добавляет комментарий к создаваемой базе данных.

Параметры -D, -l, -E, -O и -T соответствуют параметрам базовой команды SQL CREATE DATABASE; здесь можно найти дополнительную информацию по ним.

Переменные среды

PGDATABASE
Если установлено и не переопределено в командной строке, задает имя создаваемой базы данных.

PGHOST
PGPORT
PGUSER
Параметры подключения по умолчанию. PGUSER также определяет имя создаваемой базы данных, если оно не указано в командной строке или в переменной среды PGDATABASE.

PG_COLOR
Указывает, использовать ли цвет в диагностических сообщениях. Возможные значения: always (всегда), auto (автоматически) и never (никогда).

Диагностика

В случае возникновения затруднений обратитесь к CREATE DATABASE и psql, где рассматриваются потенциальные проблемы и сообщения об ошибках. Сервер базы данных должен работать на целевом хосте.

Примеры

Сценарии использования

Создать базу данных new на сервере, используемом по умолчанию:

$ createdb new

Создать базу данных new с именем пользователя, от которого запущена программа:

$ createdb

Создать базу данных new с локалью en_US.UTF-8, взяв за основу базу template0 и подключившись к обслуживающей базе qhb:

$ createdb new -l en_US.UTF-8 -T template0 --maintenance-db qhb

Создать базу данных new с локалью en_us и кодировкой LATIN1, взяв за основу базу template0.

$ createdb new "my comment" -l en_US -E LATIN1 -T template0 -v

После создания на базу накладывается комментарий "my comment".
Флаг -v обеспечивает вывод отладочной информации:

```
[DEBUG] Running getpwuid_r for user #1000
[DEBUG] Loading user with uid 1000
[DEBUG] executing statement batch: SELECT pg_catalog.set_config('search_path', '', false);
[DEBUG] executing statement batch: CREATE DATABASE new2 ENCODING 'LATIN1' TEMPLATE template0 LC_COLLATE 'en_US' LC_CTYPE 'en_US';
[DEBUG] executing statement batch: COMMENT ON DATABASE new2 IS 'my comment';
[DEBUG] Database has been successfully created
```

Особенности использования

Записи

createdb new -l en_US.UTF-8 -T template0

и

createdb new -l en_US -E UTF-8 -T template0

не равнозначны. В первом случае база данных будет успешно создана, во втором случае будет выдана ошибка.

[ERROR] db error: ERROR: encoding "UTF8" does not match locale "en_US": SQL: "CREATE DATABASE new3 ENCODING 'UTF-8' TEMPLATE template0 LC_COLLATE 'en_US' LC_CTYPE 'en_US';"
DETAIL: The chosen LC_CTYPE setting requires encoding "LATIN1".

([ОШИБКА] ошибка базы данных: ОШИБКА: кодировка "UTF8" не соответствует локали "en_US": SQL: "CREATE DATABASE new3 ENCODING 'UTF-8' TEMPLATE template0 LC_COLLATE 'en_US' LC_CTYPE 'en_US';"
ДЕТАЛИЗАЦИЯ: Выбранному значению LC_CTYPE требуется кодировка "LATIN1".)
  • Невозможно добавить комментарий к базе данных, не указав ее имя.

  • Флаг -l, --locale объединяет в себе --lc-collate и --lc-ctype, поэтому вместе их указывать нельзя. То есть:

    createdb new -l en_US = CREATE DATABASE new LC_COLLATE 'en_US' LC_CTYPE 'en_US';
    

    А при одновременном указании этих двух параметров

    createdb new --lc-collate en_US --lc-ctype en_US
    

    будет выдана ошибка.

  • По умолчанию clusterdb пытается использовать базу template1 как обслуживающую новую базу данных ( флаг --maintenance-db), а если подключиться к ней не выходит, то используется база данных qhb.

  • Флаг -v, --verbose помимо отладочной информации исполняет роль ECHO, выводя SQL-команды, отправленные на сервер для исполнения.

См. также

dropdb, CREATE DATABASE