createdb

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

Синтаксис

createdb [параметр-подключения...] [параметр...] [имя_бд [описание]]

Описание

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

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

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

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

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

Параметры

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

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

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

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

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

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

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

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

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

-icu-locale=локаль
Задает идентификатор локали ICU, который будет использоваться в этой базе данных, если выбран провайдер локали ICU.

--locale-provider={libc|icu}
Задает провайдера локали для правила сортировки базы данных по умолчанию.

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

-S шаблон
--strategy=стратегия
Задает стратегию создания базы данных. Подробную информацию см. на справочной странице команды CREATE DATABASE.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Кроме того, эта утилита, как и большинство других утилит QHB, использует переменные среды, поддерживаемые libpq (см. раздел Переменные среды).

Диагностика

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

Примеры

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

Создать базу данных 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

-- [DEBUG] Выполняется getpwuid_r для пользователя #1000
-- [DEBUG] Загружается пользователь с uid 1000
-- [DEBUG] выполняется пакет операторов: SELECT pg_catalog.set_config('search_path', '', false);
-- [DEBUG] выполняется пакет операторов: CREATE DATABASE new2 ENCODING 'LATIN1' TEMPLATE template0 LC_COLLATE 'en_US' LC_CTYPE 'en_US';
-- [DEBUG] выполняется пакет операторов: COMMENT ON DATABASE new2 IS 'my comment';
-- [DEBUG] База данных была успешно создана

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

  • Записи

    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

Copyright © KVANTOM LLC, 2019-2024