Version: 7.0.0

gs_initdb ​

Overview ​

Background ​

When a database is initialized using gs_initdb, a database directory is created, a system catalog is generated, and a default database and a template database are created.

System Catalogs ​

A large number of system catalogs and views are generated when a database is initialized, many of which allow access from any database user.

NOTE

Permissions on pg_user_status and pg_auth_history system catalogs are granted only to initialization users and sysadmin users.

Generated Databases ​

  • template1: A template database. When you create a database, all content in the template1 database is copied. The settings of template1 are determined by the parameters of gs_initdb.
  • template0: The most initial backup database provided by openGauss. template0 can be used to generate an empty database if necessary.
  • postgres: A default database provided for users, tools, and third-party applications.

Usage Guidelines ​

Background ​

During installation, you are advised to use the -D parameter to invoke gs_initdb to initialize a database. If a database needs to be initialized to rectify a fault, run gs_initdb.

  • Although gs_initdb attempts to create the corresponding data directory, it may not have the permission to do so. Because in most cases, the parent directory is owned by user root. To create a data directory, create an empty data directory as user root first and transfer the ownership of this directory to the database user using chown.
  • gs_initdb is used to set the template1 database and the settings become the default settings of other databases.
  • gs_initdb initializes the default locale and character set encoding of a database. The character set encoding, character encoding order (LC_COLLATE), and character set classes (LC_CTYPE, for example, uppercase letter, lowercase letter, or digit) can be set separately for a database when it is created.

Procedure ​

  1. Log in to any host of the openGauss database as the OS user omm.

  2. Plan the database directory.

    1. Switch to the root user.

      su - root

    2. Enter your username and password as prompted.

  3. Go to the /opt/gaussdb directory and create the data1 directory where the DN resides.

    cd /opt/gaussdb
mkdir data1

    1. Allocate the ownership of the data1 directory to user omm, and dbgrp is the user group to whom user omm belongs to.

      chown omm:dbgrp data1

    2. Log out as user root.

      exit

  4. Run the gs_initdb command to initialize the database and set password as prompted.

    gs_initdb /opt/gaussdb/data1 --nodename dn1
Enter new system admin password:[PASSWORD]
Enter it again:[PASSWORD]

    gs_initdb syntax:

    gs_initdb [OPTION]... [DATADIR]

    For parameters about OPTION, see Command Reference.

Command Reference ​

Command Reference ​

Table 1 and Table 2 list commonly used and uncommonly used parameters required for gs_initdb.

Table 1 Common parameters

Parameter

Description

Value Range

-A, --auth=METHOD

Specifies the authentication method for local users used in pg_hba.conf (host and local rows).

Do not use trust, which is the default value, unless you trust all local users on your system.

Values of METHOD:

  • trust
  • reject
  • md5 (an insecure algorithm, used for compatibility with earlier versions)
  • sha256
  • sm3

Default value: trust

--auth-host=METHOD

Specifies the authentication method for local users via TCP/IP connections used in pg_hba.conf (host rows).

The value specified in the -A parameter is overwritten when this parameter is specified.

Values of METHOD:

  • trust
  • reject
  • md5 (an insecure algorithm, used for compatibility with earlier versions)
  • sha256
  • sm3

Default value: trust

--auth-local=METHOD

Specifies the authentication method for local users via Unix-domain socket connections used in pg_hba.conf (local rows).

The value specified in the -A parameter is overwritten when this parameter is specified.

Values of METHOD:

  • trust
  • reject
  • md5 (an insecure algorithm, used for compatibility with earlier versions)
  • sha256
  • sm3
  • peer (only for the local mode)

Default value: trust

-c, --enable-dcf

Sets the node to be installed to the DCF mode.

NOTE:

In the Lite scenario, this parameter is provided by openGauss, but the DCF function is unavailable. openGauss provides master node selection when DCF is available. You can configure DCF-related parameters.

-

[-D, --pgdata=]DATADIR

Specifies the data directory.

Set DATADIR as needed. The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

--nodename=NODENAME

Specifies the name of the node to be initialized.

The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

-E, --encoding=ENCODING

Sets the encoding format for the new database.

  • If this parameter is specified, you also need to add the --locale option to specify the locale that supports this encoding format. If the --locale option is not added, the system default locale is used. If the encoding format in the system default locale is inconsistent with the encoding format specified in this parameter, the database initialization fails.
  • If this parameter is not specified, the encoding format of the default locale is used. You can run the locale command to view the default locale and its encoding format:
    omm@linux:~> locale|grep LC_CTYPE
LC_CTYPE="en_US.UTF-8"

    In the command output, UTF-8 indicates the encoding format of the default locale.

    The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

--locale=LOCALE

Sets the default locale for the new database.

NOTICE:

If you have set the database encoding format, ensure that the locale you select has the same encoding format as the preset one. Otherwise, the database initialization fails.

For example, to set the database encoding format to GBK, perform the following steps:

  1. Run the locale -a |grep gbk command to query the locales that support GBK:
    omm@linux:~>  locale -a|grep gbk
zh_CN.gbk
zh_SG.gbk
  2. Add the --locale=zh_CN.gbk option when initializing the database.
  3. The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

--dbcompatibility=DBCOMPATIBILITY

Sets the default compatibility for the new database.

The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

--lc-collate=LOCALE

--lc-ctype=LOCALE

--lc-messages=LOCALE

--lc-monetary=LOCALE

--lc-numeric=LOCALE

--lc-time=LOCALE

Sets the locale in the specified category for the new database.

The parameter values must be supported by the OS. The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

NOTE:

If the --lc-collate parameter is not specified when the database is installed, the default value of --lc-collate is C.

--no-locale

Equivalent to --locale=C.

-

--pwfile=FILE

Reads the password of the database sysadmin from FILE during the running of gs_initdb. The first line of the file is taken as the password.

The format of FILE can be "a relative path+file" or "an absolute path+file". The relative path is relative to the current path. The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

-T, --text-search-config=CFG

Sets the default text search mode.

Values of text-search-config:

  • pg_catalog.english: full-context search
  • pg_catalog.simple: common text search

Default value: pg_catalog.simple

-U, --username=NAME

Selects the username of the database sysadmin.

Value range: normal database users The value cannot contain "|", ";", "&", "<", ">", "`", "\\", or "!".

Default value: OS user who runs gs_initdb

-W, --pwprompt

Prompts users to enter the password of the database administrator during the running of gs_initdb.

-

-w, --pwpasswd=PASSWD

Specifies the password of the database administrator by running commands during the running of gs_initdb instead of interactive input.

The password must meet the following complexity requirement:

  • The password must contain at least eight characters.
  • Cannot be the same as the username, the current password (ALTER), or the current password in an inverted sequence.
  • Contains at least three types of the following characters:
    • Uppercase letters (A-Z)
    • Lowercase letters (a-z)
    • Digits: 0–9
    • Special characters: ~!@#$%^&*()-_=+\|[{}];:,<.>/?

-C, --enpwdfiledir=DIR

Specifies the directory where the password encrypted is located, using the AES128 encryption algorithm during the running of gs_initdb. gs_initdb decrypts the password file in this directory and performs the password complexity check on the decrypted password. The password is used as the user's password if the verification result is passed.

NOTE:
  • Run the gs_guc encrypt -K password -D Dir command to generate the encrypted password file.
  • If multiple -w and -C parameters are specified, gs_initdb regards the last -w or -C parameter as the user's requirement (entering a plaintext password or a password encrypted using AES128).

The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

-X, --xlogdir=XLOGDIR

Specifies the directory where the transaction logs are stored.

The directory must be a directory for which openGauss users have the read and write permissions.

The value can be an absolute path or a relative path. The relative path is relative to the data directory. The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

-S, --security

This database is initialized in the security mode.

After the database is initialized using -S, the created database user permissions are restricted, and the public schema permission cannot be used any more by default.

Table 2 Uncommon parameters

Parameter

Description

Value Range

-d, --debug

Prints debugging output from the bootstrap backend. The bootstrap backend is the program for gs_initdb to create the system catalogs.

-

-L DIRECTORY

Specifies the input file path where the database is initialized using gs_initdb. Usually, it is unnecessary. You will be prompted if you need to specify their location explicitly.

Path of input files required by the initialized database The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

-n, --noclean

If this parameter is not specified and gs_initdb determines that an error prevents it from creating a database, it removes any files it might have created before discovering that it cannot finish the job. This option inhibits tidying-up and is therefore useful for debugging.

-

-s, --show

Displays internal settings.

-

-H, --host-ip

Initializes the openGauss node node_host.

The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

-V, --version

Prints the gs_initdb version information and exits.

-

-?, --help

Displays help information about gs_initdb command parameters and exits.

-

-g

Specifies the path of the shared Xlog file for initializing the cross-AZ DR database instance that uses the shared storage.

Specified shared log file path. The value cannot contain "|", ";", "&", "$", "<", ">", "`", "\\", or "!".

Copyright © openGauss 2026. All rights reserved.
TrademarkPrivacy StatementLegal NoticeAbout Cookies
TrademarkPrivacy StatementLegal NoticeAbout Cookies
Copyright © openGauss 2026. All rights reserved.