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, который будет использоваться в этой базе данных.
-O владелец
--owner=владелец
Указывает пользователя базы данных, которому будет принадлежать новая база данных.
(Это имя обрабатывается как идентификатор, заключенный в кавычки.)
-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
Особенности использования
Записи
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, отправленные на сервер для исполнения.