diff --git a/docs/basic-query-syntax.md b/docs/basic-query-syntax.md new file mode 100644 index 000000000..f2e51ff73 --- /dev/null +++ b/docs/basic-query-syntax.md @@ -0,0 +1,66 @@ +--- +title: Basic Query Syntax +--- + +# Basic Queries of Cloudberry Database + +This document introduce the basic queries of Cloudberry Database. + +Cloudberry Database is a high-performance, highly parallel data warehouse developed based on PostgreSQL and Greenplum. Here are some examples of the basic query syntax. + +- `SELECT`: Used to retrieve data from databases & tables. + + ```sql + SELECT * FROM employees; -- Queries all data in the employees table. + ``` + +- Conditional query (`WHERE`): Used to filter result sets based on certain conditions. + + ```sql + SELECT * FROM employees WHERE salary > 50000; -- Queries employee information with salary exceeding 50,000. + ``` + +- `ORDER BY`: Used to sort query results by one or more columns. + + ```sql + SELECT * FROM employees ORDER BY salary DESC; -- Sorts employee information in descending order by salary. + ``` + +- Aggregation functions: such as `COUNT`, `SUM`, `AVG`, `MAX`, `MIN`, used for calculating statistics from datasets. + + ```sql + SELECT AVG(salary) FROM employees; -- Calculates the average salary of employees. + ``` + +- `GROUP BY`: Used in conjunction with aggregation functions to group result sets. + + ```sql + SELECT department, COUNT(*) FROM employees GROUP BY department; -- Counts the number of employees by department. + ``` + +- Limit the number of results (`LIMIT`): used to limit the number of rows returned by the query result. + + ```sql + SELECT * FROM employees LIMIT 10; -- Only queries the information of the first 10 employees. + ``` + +- Join query (`JOIN`): used to combine data from two or more tables based on related columns. + + ```sql + SELECT employees.name, departments.name + FROM employees + JOIN departments ON employees.department_id = departments.id; -- Queries employees and their corresponding department names. + ``` + +- Subquery: Nested queries in another SQL query. + + ```sql + SELECT name FROM employees + WHERE department_id IN (SELECT id FROM departments WHERE location = 'New York'); -- Queries all employees working in New York. + ``` + +The above is just a brief overview of the basic query syntax in Cloudberry Database. Cloudberry Database also provides more advanced queries and functions to help developers perform complex data operations and analyses. + +## See also + +- [Insert, Update, and Delete Rows](/docs/insert-update-delete-rows.md) diff --git a/docs/cbdb-linux-compile.md b/docs/cbdb-linux-compile.md new file mode 100644 index 000000000..2f8c3513b --- /dev/null +++ b/docs/cbdb-linux-compile.md @@ -0,0 +1,265 @@ +--- +title: On Linux +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Compile and Install Cloudberry Database on Linux + +:::info +The source of this document is from the GitHub repository [`cloudberrydb/cloudberrydb`](https://github.com/cloudberrydb/cloudberrydb/blob/main/readmes/README.Linux.md). +::: + +This document shares how to compile and install Cloudberry Database on Linux systems (CentOS 7, RHEL, and Ubuntu). Note that this document is for developers to try out Cloudberry Database in a single-node environments. DO NOT use this document for production environments. + +Take the following steps to compile and install Cloudberry Database: + +1. [Clone GitHub repo](#step-1-clone-github-repo). +2. [Install dependencies](#step-2-install-dependencies). +3. [Perform prerequisite platform tasks](#step-3-perform-prerequisite-platform-tasks). +4. [Build Cloudberry Database](#step-4-build-cloudberry-database). +5. [Verify the cluster](#step-5-verify-the-cluster). + +## Step 1. Clone GitHub repo + +Clone the GitHub repository `cloudberrydb/cloudberrydb` to the target machine: + +```shell +git clone https://github.com/cloudberrydb/cloudberrydb.git +``` + +## Step 2. Install dependencies + +Enter the repository and install dependencies according to your operating systems: + + + + +The following steps work on CentOS 7. For other CentOS versions, these steps might work but are not guaranteed to work. + +1. Run the Bash script `README.CentOS.bash` in the `readmes` directory of the `cloudberrydb/cloudberrydb` repository. To run this script, password is required. Then, some required dependencies will be automatically downloaded. + + ```bash + cd cloudberrydb/readmes + ./README.CentOS.bash + ``` + +2. Install additional packages required for configurations. + + ```bash + yum -y install R apr apr-devel apr-util automake autoconf bash bison bison-devel bzip2 bzip2-devel centos-release-scl curl flex flex-devel gcc gcc-c++ git gdb iproute krb5-devel less libcurl libcurl-devel libevent libevent-devel libxml2 libxml2-devel libyaml libzstd-devel libzstd make openldap openssh openssh-clients openssh-server openssl openssl-devel openssl-libs perl python3-devel readline readline-devel rsync sed sudo tar vim wget which xerces-c-devel zip zlib && \ + yum -y install epel-release + ``` + +3. Update the GNU Compiler Collection (GCC) to version `devtoolset-10` to support C++ 14. + + ```bash + yum install centos-release-scl + yum -y install devtoolset-10-gcc devtoolset-10-gcc-c++ devtoolset-10-binutils + scl enable devtoolset-10 bash + source /opt/rh/devtoolset-10/enable + echo "source /opt/rh/devtoolset-10/enable" >> /etc/bashrc + source /etc/bashrc + gcc -v + ``` + +4. Link cmake3 to cmake: + + ```bash + sudo ln -sf /usr/bin/cmake3 /usr/local/bin/cmake + ``` + + + + +1. Install Development Tools. + + ```bash + sudo yum group install -y "Development Tools" + ``` + +2. Install dependencies: + + ```bash + sudo yum install -y epel-release + + sudo yum install -y apr-devel bison bzip2-devel cmake3 flex gcc gcc-c++ krb5-devel libcurl-devel libevent-devel libkadm5 libxml2-devel libzstd-devel openssl-devel perl-ExtUtils-Embed python3-devel python3-pip readline-devel xerces-c-devel zlib-devel + ``` + +3. Install more dependencies by running the `README.Rhel-Rocky.bash` script. + + ```bash + ~/cloudberrydb/readmes/README.Rhel-Rocky.bash + ``` + + + + +1. Install dependencies by running the `README.Ubuntu.bash` script in the `readmes` directory. + + ```shell + ## You need to enter your password to run. + sudo ~/cloudberrydb/readmes/README.Ubuntu.bash + ``` + + :::info + - When you run the `README.Ubuntu.bash` script for dependencies, you will be asked to configure `realm` for Kerberos. You can enter any realm, because this is just for testing, and during testing, it will reconfigure a local server/client. If you want to skip this manual configuration, run `export DEBIAN_FRONTEND=noninteractive`. + - If the script fails to download packages, we recommend that you can try another one software source for Ubuntu. + ::: + +2. Install GCC 10. Ubuntu 18.04 and later versions should use GCC 10 or newer: + + ```bash + ## Install gcc-10 + sudo apt install software-properties-common + sudo add-apt-repository ppa:ubuntu-toolchain-r/test + sudo apt install gcc-10 g++-10 + sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 + ``` + + + + +## Step 3. Perform prerequisite platform tasks + +After you have installed all the dependencies for your operating system, it is time to do some prerequisite platform tasks before you go on building Cloudberry Database. These operation include manually running `ldconfig` on all platforms, creating the `gpadmin` user, and setting up a password to start the Cloudberry Database and test. + +1. Make sure that you add `/usr/local/lib` and `/usr/local/lib64` to the `/etc/ld.so.conf` file. + + ```bash + echo -e "/usr/local/lib \n/usr/local/lib64" >> /etc/ld.so.conf + ldconfig + ``` + +2. Create the `gpadmin` user and set up the SSH key. Manually create SSH keys based on different operating systems, so that you can run `ssh localhost` without a password. + + + + + ```bash + useradd gpadmin # Creates gpadmin user + su - gpadmin # Uses the gpadmin user + ssh-keygen # Creates SSH key + cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys + chmod 600 ~/.ssh/authorized_keys + exit + ``` + + + + + ```bash + useradd -r -m -s /bin/bash gpadmin # Creates gpadmin user + su - gpadmin # Uses the gpadmin user + ssh-keygen # Creates SSH key + cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys + chmod 600 ~/.ssh/authorized_keys + exit + ``` + + + + +## Step 4. Build Cloudberry Database + +After you have installed all the dependencies and performed the prerequisite platform tasks, you can start to build Cloudberry Database. Run the following commands in sequence. + +1. Configure the build environment. Enter the `cloudberrydb` directory and run the `configure` script. + + ```bash + cd cloudberrydb + ./configure --with-perl --with-python --with-libxml --with-gssapi --prefix=/usr/local/cloudberrydb + ``` + + :::info + Cloudberry Database is built with GPORCA by default. If you want to build CBDB without GPORCA, add the `--disable-orca` flag in the `./configure` command. + + ```bash + ./configure --disable-orca --with-perl --with-python --with-libxml --prefix=/usr/local/cloudberrydb + ``` + + ::: + +2. Compile the code and install the database. + + ```bash + make -j8 + make -j8 install + ``` + +3. Bring in the Greenplum environment for your running shell. + + ```bash + cd .. + cp -r cloudberrydb/ /home/gpadmin/ + cd /home/gpadmin/ + chown -R gpadmin:gpadmin cloudberrydb/ + su - gpadmin + cd cloudberrydb/ + source /usr/local/cloudberrydb/greenplum_path.sh + ``` + +4. Start the demo cluster. + + + + + ```bash + scl enable devtoolset-10 bash + source /opt/rh/devtoolset-10/enable + make create-demo-cluster + ``` + + + + + ```bash + make create-demo-cluster + ``` + + + + +5. Prepare the test by running the following command. This command will configure the port and environment variables for the test. + + Environment variables such as `PGPORT` and `COORDINATOR_DATA_DIRECTORY` will be configured, which are the default port and the data directory of the coordinator node. + + ```bash + source gpAux/gpdemo/gpdemo-env.sh + ``` + +## Step 5. Verify the cluster + +1. You can verify whether the cluster has started successfully by running the following command. If successful, you might see multiple active `postgres` processes with ports ranging from `7000` to `7007`. + + ```bash + ps -ef | grep postgres + ``` + +2. Connect to the Cloudberry Database and see the active segment information by querying the system table `gp_segement_configuration`. For detailed description of this table, see the Greenplum document [here](https://docs.vmware.com/en/VMware-Greenplum/6/greenplum-database/ref_guide-system_catalogs-gp_segment_configuration.html). + + ```sql + $ psql -p 7000 postgres + psql (14.4, server 14.4) + Type "help" for help. + + postgres=# select version(); + version + ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + PostgreSQL 14.4 (Cloudberry Database 1.0.0+1c0d6e2224 build dev) on x86_64( GCC 13.2.0) 13.2.0, 64-bit compiled on Sep 22 2023 10:56:01 + (1 row) + + postgres=# select * from gp_segment_configuration; + dbid | content | role | preferred_role | mode | status | port | hostname | address | datadir | warehouseid + ------+---------+------+----------------+------+--------+------+------------+------------+------------------------------------------------------------------------------+------------- + 1 | -1 | p | p | n | u | 7000 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/qddir/demoDataDir-1 | 0 + 8 | -1 | m | m | s | u | 7001 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/standby | 0 + 3 | 1 | p | p | s | u | 7003 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1 | 0 + 6 | 1 | m | m | s | u | 7006 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1 | 0 + 2 | 0 | p | p | s | u | 7002 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0 | 0 + 5 | 0 | m | m | s | u | 7005 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0 | 0 + 4 | 2 | p | p | s | u | 7004 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2 | 0 + 7 | 2 | m | m | s | u | 7007 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2 | 0 + (8 rows) + ``` \ No newline at end of file diff --git a/docs/cbdb-macos-compile.md b/docs/cbdb-macos-compile.md index 1a91e18cd..55c1e04fa 100644 --- a/docs/cbdb-macos-compile.md +++ b/docs/cbdb-macos-compile.md @@ -5,7 +5,7 @@ title: On macOS # Compile and Install Cloudberry Database on macOS :::info -The source of this document is from [the document](https://github.com/cloudberrydb/cloudberrydb/blob/main/readmes/README.macOS.md) in the GitHub repository `cloudberrydb/cloudberrydb`. +The source of this document is from the GitHub repository [`cloudberrydb/cloudberrydb`](https://github.com/cloudberrydb/cloudberrydb/blob/main/readmes/README.macOS.md). ::: This document shares how to build, compile, and install Cloudberry Database on macOS (single node) for development and trial purposes. Follow the steps below. diff --git a/docs/connect-to-cbdb.md b/docs/connect-to-cbdb.md new file mode 100644 index 000000000..576881f97 --- /dev/null +++ b/docs/connect-to-cbdb.md @@ -0,0 +1,115 @@ +--- +title: Connect to Database +--- + +# Connect to Cloudberry Database + +This document introduces how to connect to Cloudberry Database. + +## Connection parameters + +Users can connect to Cloudberry Database using a PostgreSQL-compatible client program, such as `psql`. Users and administrators always connect to Cloudberry Database through the *coordinator*. The segments cannot accept client connections. + +To establish a connection to the Cloudberry Database coordinator, you will need to know the following connection information and configure your client program accordingly. + +|Connection parameter|Description|Environment variable| +|--------------------|-----------|--------------------| +|Application name|The application name that is connecting to the database. The default value, held in the `application_name` connection parameter is *psql*.|`$PGAPPNAME`| +|Database name|The name of the database to which you want to connect. For a newly initialized system, use the `postgres` database to connect for the first time.|`$PGDATABASE`| +|Host name|The host name of the Cloudberry Database coordinator. The default host is the local host.|`$PGHOST`| +|Port|The port number that the Cloudberry Database coordinator instance is running on. The default is 5432.|`$PGPORT`| +|User name|The database user (role) name to connect as. This is not necessarily the same as your OS user name. Check with your Cloudberry administrator if you are not sure what you database user name is. Note that every Cloudberry Database system has one superuser account that is created automatically at initialization time. This account has the same name as the OS name of the user who initialized the Cloudberry system (typically `gpadmin`).|`$PGUSER`| + +[Connecting with psql](#connect-with-psql) provides example commands for connecting to Cloudberry Database. + +## Supported client applications + +Users can connect to Cloudberry Database using various client applications: + +- A number of [Cloudberry Database Client Applications](#client-utility-applications) are provided with your Cloudberry installation. The `psql` client application provides an interactive command-line interface to Cloudberry Database. +- Using standard [Database Application Interfaces](#connect-with-application-interfaces), such as ODBC and JDBC, users can create their own client applications that interface to Cloudberry Database. +- Most client tools that use standard database interfaces, such as ODBC and JDBC, can be configured to connect to Cloudberry Database. + +### Client utility applications + +Cloudberry Database comes installed with a number of client utility applications located in the `$GPHOME/bin` directory of your Cloudberry Database coordinator host installation. The following are the most commonly used client utility applications: + +|Name|Usage| +|----|-----| +|`createdb`|Creates a new database| +|`createuser`|Defines a new database role| +|`dropdb`|Removes a database| +|`dropuser`|Removes a role| +|`psql`|PostgreSQL interactive terminal| +|`reindexdb`|Reindexes a database| +|`vacuumdb`|Garbage-collects and analyzes a database| + +When using these client applications, you must connect to a database through the Cloudberry coordinator instance. You will need to know the name of your target database, the host name and port number of the coordinator, and what database user name to connect as. This information can be provided on the command-line using the options `-d`, `-h`, `-p`, and `-U` respectively. If an argument is found that does not belong to any option, it will be interpreted as the database name first. + +All of these options have default values which will be used if the option is not specified. The default host is the local host. The default port number is 5432. The default user name is your OS system user name, as is the default database name. Note that OS user names and Cloudberry Database user names are not necessarily the same. + +If the default values are not correct, you can set the environment variables `PGDATABASE`, `PGHOST`, `PGPORT`, and `PGUSER` to the appropriate values, or use a `psql` `~/.pgpass` file to contain frequently-used passwords. + +### Connect with psql + +Depending on the default values used or the environment variables you have set, the following examples show how to access a database via `psql`: + +```shell +$ psql -d gpdatabase -h coordinator_host -p 5432 -U `gpadmin` +``` + +```shell +$ psql gpdatabase +``` + +```shell +$ psql +``` + +If a user-defined database has not yet been created, you can access the system by connecting to the `postgres` database. For example: + +```shell +$ psql postgres +``` + +After connecting to a database, `psql` provides a prompt with the name of the database to which `psql` is currently connected, followed by the string `=>` (or `=#` if you are the database superuser). For example: + +```shell +gpdatabase=> +``` + +At the prompt, you might type in SQL commands. A SQL command must end with a `;` (semicolon) in order to be sent to the server and run. For example: + +```sql +=> SELECT * FROM mytable; +``` + +## Connect with application interfaces + +You might want to develop your own client applications that interface to Cloudberry Database. PostgreSQL provides a number of database drivers for the most commonly used database application programming interfaces (APIs), which can also be used with Cloudberry Database. These drivers are available as a separate download. Each driver (except libpq, which comes with PostgreSQL) is an independent PostgreSQL development project and must be downloaded, installed and configured to connect to Cloudberry Database. The following drivers are available: + +|API|PostgreSQL Driver|Download Link| +|---|-----------------|-------------| +|ODBC|psqlODBC|[https://odbc.postgresql.org/](https://odbc.postgresql.org/)| +|JDBC|pgjdbc|[https://jdbc.postgresql.org/](https://jdbc.postgresql.org/)| +|Perl DBI|pgperl|[https://metacpan.org/release/DBD-Pg](https://metacpan.org/release/DBD-Pg)| +|Python DBI|pygresql|[http://www.pygresql.org/](http://www.pygresql.org/)| +|Python DBI|psycopg2|[https://www.psycopg.org/](https://www.psycopg.org/)| +|libpq C Library|libpq|[https://www.postgresql.org/docs/12/libpq.html](https://www.postgresql.org/docs/12/libpq.html)| + +General instructions for accessing a Cloudberry Database with an API are: + +1. Download your programming language platform and respective API from the appropriate source. For example, you can get the Java Development Kit (JDK) and JDBC API from Oracle. +2. Write your client application according to the API specifications. When programming your application, be aware of the SQL support in Cloudberry Database so you do not include any unsupported SQL syntax. + +Download the appropriate driver and configure connectivity to your Cloudberry Database coordinator instance. + +## Troubleshoot connection problems + +A number of things can prevent a client application from successfully connecting to Cloudberry Database. This topic explains some of the common causes of connection problems and how to correct them. + +| Problem | Solution | +| ------- | -------- | +| No `pg_hba.conf` entry for host or user | To enable Cloudberry Database to accept remote client connections, you must configure your Cloudberry Database coordinator instance so that connections are allowed from the client hosts and database users that will be connecting to Cloudberry Database. This is done by adding the appropriate entries to the `pg_hba.conf` configuration file (located in the coordinator instance's data directory). | +| Cloudberry Database is not running | If the Cloudberry Database coordinator instance is down, users will not be able to connect. You can verify that the Cloudberry Database system is up by running the `gpstate` utility on the Cloudberry coordinator host. | +| Network problems: Interconnect timeouts | If users connect to the Cloudberry coordinator host from a remote client, network problems can prevent a connection (for example, DNS host name resolution problems, the host system is down, and so on.). To ensure that network problems are not the cause, connect to the Cloudberry coordinator host from the remote client host. For example: `ping hostname`

If the system cannot resolve the host names and IP addresses of the hosts involved in Cloudberry Database, queries and connections will fail. For some operations, connections to the Cloudberry Database coordinator use `localhost` and others use the actual host name, so you must be able to resolve both. If you encounter this error, first make sure you can connect to each host in your Cloudberry Database array from the coordinator host over the network. In the `/etc/hosts` file of the coordinator and all segments, make sure you have the correct host names and IP addresses for all hosts involved in the Cloudberry Database array. The `127.0.0.1` IP must resolve to `localhost`. | diff --git a/docs/create-and-manage-database.md b/docs/create-and-manage-database.md new file mode 100644 index 000000000..2109ba7de --- /dev/null +++ b/docs/create-and-manage-database.md @@ -0,0 +1,98 @@ +--- +title: Create and Manage Database +--- + +# Create and Manage Cloudberry Database + +A Cloudberry Database system is a single instance of Cloudberry Database. There can be multiple running Cloudberry Database systems co-existing with each other, but usually a client can only connect to one of them. + +There can be multiple databases in a Cloudberry Database system. This is different from some database management systems (such as Oracle) where the database instance *is* the database. Although you can create many databases in a Cloudberry system, client programs can connect to and access only one database at a time — you cannot cross-query between databases. + +## About template and default databases + +Cloudberry Database provides some template databases and a default database, *template1*, *template0*, and *postgres*. + +By default, each new database you create is based on a *template1* database. Cloudberry Database uses *template1* to create databases unless you specify another template. Creating objects in *template1* is not recommended. The objects will be in every database you create using the default template database. + +Cloudberry Database uses another database template, *template0*, internally. Do not drop or modify *template0*. You can use *template0* to create a completely clean database containing only the standard objects predefined by Cloudberry Database at initialization. + +You can use the *postgres* database to connect to Cloudberry Database for the first time. Cloudberry Database uses *postgres* as the default database for administrative connections. + +## Create a database + +The `CREATE DATABASE` command creates a new database. For example: + +```sql +=> CREATE DATABASE ; +``` + +To create a database, you must have privileges to create a database or be a Cloudberry Database superuser. If you do not have the correct privileges, you cannot create a database. Contact your Cloudberry Database administrator to either give you the necessary privilege or to create a database for you. + +You can also use the client program `createdb` to create a database. For example, running the following command in a command line terminal connects to Cloudberry Database using the provided host name and port and creates a database named *mydatabase*: + +```shell +$ createdb -h coordinator_host -p 5432 mydatabase +``` + +The host name and port must match the host name and port of the installed Cloudberry Database system. + +Some objects, such as roles, are shared by all the databases in a Cloudberry Database system. Other objects, such as tables that you create, are known only in the database in which you create them. + +:::caution +The `CREATE DATABASE` command is not transactional. +::: + +### Clone a database + +By default, a new database is created by cloning the standard system database template, *template1*. Any database can be used as a template when creating a new database, thereby providing the capability to 'clone' or copy an existing database and all objects and data within that database. For example: + +```sql +=> CREATE DATABASE TEMPLATE ; +``` + +### Create a database with a different owner + +Another database owner can be assigned when a database is created: + +```sql +=> CREATE DATABASE WITH ; +``` + +## View the list of databases + +If you are working in the `psql` client program, you can use the `\l` meta-command to show the list of databases and templates in your Cloudberry Database system. If using another client program and you are a superuser, you can query the list of databases from the `pg_database` system catalog table. For example: + +```sql +=> SELECT datname from pg_database; +``` + +## Alter a database + +The `ALTER DATABASE` command changes database attributes such as owner, name, or default configuration attributes. For example, the following command alters a database by setting its default schema search path (the `search_path` configuration parameter): + +```sql +=> ALTER DATABASE mydatabase SET search_path TO myschema, public, pg_catalog; +``` + +To alter a database, you must be the owner of the database or a superuser. + +## Drop a database + +The `DROP DATABASE` command drops (or deletes) a database. It removes the system catalog entries for the database and deletes the database directory on disk that contains the data. You must be the database owner or a superuser to drop a database, and you cannot drop a database while you or anyone else is connected to it. Connect to `postgres` (or another database) before dropping a database. For example: + +```sql +=> \c postgres +=> DROP DATABASE mydatabase; +``` + +You can also use the client program `dropdb` to drop a database. For example, the following command connects to Cloudberry Database using the provided host name and port and drops the database *mydatabase*: + +```shell +$ dropdb -h coordinator_host -p 5432 mydatabase +``` + +:::caution +Dropping a database cannot be undone. +::: + +The `DROP DATABASE` command is not transactional. diff --git a/docs/insert-update-delete-rows.md b/docs/insert-update-delete-rows.md new file mode 100644 index 000000000..8271a4e02 --- /dev/null +++ b/docs/insert-update-delete-rows.md @@ -0,0 +1,125 @@ +--- +title: Insert, Update, and Delete Rows +--- + +# Insert, Update, and Delete Row Data in Cloudberry Database + +This document introduces how to manipulate row data in Cloudberry Database, including: + +- [Inserting rows](#insert-rows) +- [Updating existing rows](#update-existing-rows) +- [Deleting rows](#delete-rows) +- [Truncating a table](#truncate-a-table) +- [Vacuuming the database](#vacuum-the-database) + +## Insert rows + +Use the `INSERT` command to create rows in a table. This command requires the table name and a value for each column in the table; you might optionally specify the column names in any order. If you do not specify column names, list the data values in the order of the columns in the table, separated by commas. + +For example, to specify the column names and the values to insert: +insert +```sql +INSERT INTO products (name, price, product_no) VALUES ('Cheese', 9.99, 1); +``` + +To specify only the values to insert: + +```sql +INSERT INTO products VALUES (1, 'Cheese', 9.99); +``` + +Usually, the data values are literals (constants), but you can also use scalar expressions. For example: + +```sql +INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < +'2016-05-07'; +``` + +You can insert multiple rows in a single command. For example: + +```sql +INSERT INTO products (product_no, name, price) VALUES + (1, 'Cheese', 9.99), + (2, 'Bread', 1.99), + (3, 'Milk', 2.99); +``` + +### Insert rows into partitioned tables + +To insert data into a partitioned table, you are expected to specify the root partitioned table that was created with the `CREATE TABLE` command. Directly specifying a leaf partition in an `INSERT` command is not supported, and attempting to do so will cause an error, because leaf partitions are invisible to users and data insertion is managed automatically by the database system. + +An error will be returned if the data being inserted does not fit the range of any existing partitions (for example, the specified key value does not match any partition rules). + +To ensure data is correctly inserted into a partitioned table, you only need to specify the root partitioned table in your `INSERT` statement. The database system will automatically insert the data row into the appropriate leaf partition based on the partition key. If a data row does not conform to the range of any leaf partition, the database will return an error. + +Example: + +```sql +-- Inserting data into the root partitioned table +INSERT INTO sales (sale_id, product_no, year, amount) VALUES (1, 'Cheese', 2021, 9.99); +``` + +The above statement will automatically insert the data row into the correct partition based on the value of the year column. You should not, and need not, attempt to directly specify any leaf partition for data insertion. + +### Insert rows into append-optimized tables + +To insert large amounts of data, use external tables or the `COPY` command. These load mechanisms are more efficient than `INSERT` for inserting many rows. + +The storage model of append-optimized tables in Cloudberry Database is designed for efficient bulk data loading rather than single row `INSERT` statements. For high-volume data insertions, it is recommended to use batch loading methods such as the `COPY` command. Cloudberry Database can support multiple concurrent `INSERT` transactions on append-optimized tables; however, this capability is typically intended for batch insertions rather than single-row operations. + +## Update existing rows + +The `UPDATE` command updates rows in a table. You can update all rows, a subset of all rows, or individual rows in a table. You can update each column separately without affecting other columns. + +To perform an update, you need: + +- The name of the table and columns to update. +- The new values of the columns. +- One or more conditions specifying the row or rows to be updated. + +For example, the following command updates all products that have a price of *5* to have a price of *10*: + +```sql +UPDATE products SET price = 10 WHERE price = 5; +``` + +## Delete rows + +The `DELETE` command deletes rows from a table. Specify a `WHERE` clause to delete rows that match certain criteria. If you do not specify a `WHERE` clause, all rows in the table are deleted. The result is a valid, but empty, table. For example, to remove all rows from the products table that have a price of *10*: + +```sql +DELETE FROM products WHERE price = 10; +``` + +To delete all rows from a table: + +```sql +DELETE FROM products; +``` + +### Truncate a table + +Use the `TRUNCATE` command to quickly remove all rows in a table. For example: + +```sql +TRUNCATE mytable; +``` + +This command empties a table of all rows in one operation. Note that in Cloudberry Database, the `TRUNCATE` command will affect inherited child tables by default, even without using the `CASCADE` option. In addition, because Cloudberry Database does not support foreign key constraints, the `TRUNCATE` command will not trigger any `ON DELETE` actions or rewrite rules. The command truncates only rows in the named table. + +## Vacuum the database + +Deleted or updated data rows occupy physical space on disk even though new transactions cannot see them. Periodically running the `VACUUM` command removes these expired rows. For example: + +```sql +VACUUM mytable; +``` + +The `VACUUM` command collects table-level statistics such as the number of rows and pages. Vacuum all tables after loading data, including append-optimized tables. + +You need to use the `VACUUM`, `VACUUM FULL`, and `VACUUM ANALYZE` commands to maintain the data in a Cloudberry Database especially if updates and deletes are frequently performed on your database data. + +## See also + +- [Work with Transactions](/docs/work-with-transactions.md) +- [Transactional Concurrency Control](/docs/transactional-concurrency-control.md) diff --git a/docs/start-and-stop-cbdb-database.md b/docs/start-and-stop-cbdb-database.md new file mode 100644 index 000000000..2fa316537 --- /dev/null +++ b/docs/start-and-stop-cbdb-database.md @@ -0,0 +1,144 @@ +--- +title: Start and Stop Database +--- + +# Start and Stop Cloudberry Database + +In a Cloudberry Database DBMS, the database server instances (the coordinator and all segments) are started or stopped across all of the hosts in the system in such a way that they can work together as a unified DBMS. + +Because a Cloudberry Database system is distributed across many machines, the process for starting and stopping a Cloudberry Database system is different than the process for starting and stopping a regular PostgreSQL DBMS. + +Use the `gpstart` and `gpstop` utilities to start and stop Cloudberry Database, respectively. These utilities are located in the `$GPHOME/bin` directory on your Cloudberry Database coordinator host. + +> **Important** Do not issue a `kill` command to end any Postgres process. Instead, use the database command `pg_cancel_backend()`. + +Issuing a `kill -9` or `kill -11` can introduce database corruption and prevent root cause analysis from being performed. + +## Start Cloudberry Database + +Start an initialized Cloudberry Database system by running the `gpstart` utility on the coordinator instance. + +Use the `gpstart` utility to start a Cloudberry Database system that has already been initialized by the `gpinitsystem` utility, but has been stopped by the `gpstop` utility. The `gpstart` utility starts Cloudberry Database by starting all the `postgres` instances on the Cloudberry Database cluster. `gpstart` orchestrates this process and performs the process in parallel. + +Run `gpstart` on the coordinator host to start Cloudberry Database: + +```shell +$ gpstart +``` + +## Restart Cloudberry Database + +Stop the Cloudberry Database system and then restart it. + +The `gpstop` utility with the `-r` option can stop and then restart Cloudberry Database after the shutdown completes. + +To restart Cloudberry Database, enter the following command on the coordinator host: + +```shell +$ gpstop -r +``` + +## Reload configuration file changes only + +Reload changes to Cloudberry Database configuration files without interrupting the system. + +The `gpstop` utility can reload changes to the `pg_hba.conf` configuration file and to *runtime* parameters in the coordinator `postgresql.conf` file without service interruption. Active sessions pick up changes when they reconnect to the database. Many server configuration parameters require a full system restart (`gpstop -r`) to activate. + +Reload configuration file changes without shutting down the Cloudberry Database system using the `gpstop` utility: + +```shell +$ gpstop -u +``` + +## Start the Coordinator in maintenance mode + +Start only the coordinator to perform maintenance or administrative tasks without affecting data on the segments. For example, you can connect to a database only on the coordinator instance in maintenance mode and edit system catalog settings. + +1. Run `gpstart` using the `-m` option: + + ```shell + $ gpstart -m + ``` + +2. Connect to the coordinator in maintenance mode to do catalog maintenance. For example: + + ```shell + $ PGOPTIONS='-c gp_role=utility' psql postgres + ``` + +3. After completing your administrative tasks, stop the coordinator in maintenance mode. Then, restart it in production mode. + + ```shell + $ gpstop -m + $ gpstart + ``` + + :::caution + Incorrect use of maintenance mode connections can result in an inconsistent system state. It is recommended that Technical Support perform this operation. + ::: + +## Stop Cloudberry Database + +The `gpstop` utility stops or restarts your Cloudberry Database system and always runs on the coordinator host. When activated, `gpstop` stops all `postgres` processes in the system, including the coordinator and all segment instances. The `gpstop` utility uses a default of up to multiple parallel worker threads to bring down the Postgres instances that make up the Cloudberry Database cluster. To stop Cloudberry Database immediately, use the fast mode. + +> **Important** Immediate shut down mode is not recommended. This mode stops all database processes without allowing the database server to complete transaction processing or clean up any temporary or in-process work files. + +- To stop Cloudberry Database: + + ```shell + $ gpstop + ``` + +- To stop Cloudberry Database in fast mode: + + ```shell + $ gpstop -M fast + ``` + + By default, you are not allowed to shut down Cloudberry Database if there are any client connections to the database. Use the `-M fast` option to roll back all in progress transactions and terminate any connections before shutting down. + +## Stop client processes + +Cloudberry Database launches a new backend process for each client connection. A Cloudberry Database user with `SUPERUSER` privileges can cancel and terminate these client backend processes. + +Canceling a backend process with the `pg_cancel_backend()` function ends a specific queued or active client query. Terminating a backend process with the `pg_terminate_backend()` function terminates a client connection to a database. + +The `pg_cancel_backend()` function has two signatures: + +- `pg_cancel_backend( pid int4 )` +- `pg_cancel_backend( pid int4, msg text )` + +The `pg_terminate_backend()` function has two similar signatures: + +- `pg_terminate_backend( pid int4 )` +- `pg_terminate_backend( pid int4, msg text )` + +If you provide a `msg`, Cloudberry Database includes the text in the cancel message returned to the client. `msg` is limited to 128 bytes; Cloudberry Database truncates anything longer. + +The `pg_cancel_backend()` and `pg_terminate_backend()` functions return `true` if successful, and `false` otherwise. + +To cancel or terminate a backend process, you must first identify the process ID of the backend. You can obtain the process ID from the `pid` column of the `pg_stat_activity` view. For example, to view the process information associated with all running and queued queries: + +```sql +SELECT usename, pid, state, query, datname + FROM pg_stat_activity; +``` + +Sample partial query output: + +```sql +usename | pid | state | query | datname +---------+-------------------+--------+------------------------+--------- +  sammy | 31861 | idle | SELECT * FROM testtbl; | testdb +  billy | 31905 | active | SELECT * FROM topten; | testdb +``` + +Use the output to identify the process id (`pid`) of the query or client connection. + +For example, to cancel the waiting query identified in the sample output above and include `'Admin canceled long-running query.'` as the message returned to the client: + +```sql +=# SELECT pg_cancel_backend(31905 ,'Admin canceled long-running query.'); + +ERROR: canceling statement due to user request: "Admin canceled long-running query." +``` diff --git a/docs/transactional-concurrency-control.md b/docs/transactional-concurrency-control.md new file mode 100644 index 000000000..189096c1a --- /dev/null +++ b/docs/transactional-concurrency-control.md @@ -0,0 +1,158 @@ +--- +title: Concurrency Control for Transactions +--- + +# Transactional Concurrency Control in Cloudberry Database + +This document introduces the transactional concurrency control in Cloudberry Database, including: + +- [MVCC mechanism](#mvcc-mechanism) +- [Lock modes](#lock-modes) +- [Global Deadlock Detector](#global-deadlock-detector) + +## MVCC mechanism + +Cloudberry Database and PostgreSQL do not use locks for concurrency control. Instead, they maintain data consistency through a multi-version model known as Multi-version Concurrency Control (MVCC). MVCC ensures transaction isolation for each database session, allowing each query transaction to see a consistent snapshot of data. This ensures that the data observed by a transaction remains consistent and unaffected by other concurrent transactions. + +However, the specific data changes visible to a transaction are influenced by its isolation level. The default isolation level is "READ COMMITTED," which means that a transaction can observe data changes made by other transactions that have already been committed. If the isolation level is set to "REPEATABLE READ," then queries within that transaction will observe the data because it was at the beginning of the transaction and will not see changes made by other transactions in the interim. To specify the isolation level of a transaction, you can use the statement `BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ` to start a transaction with the "REPEATABLE READ" isolation level. + +Because MVCC does not use explicit locks for concurrency control, lock contention is minimized and Cloudberry Database maintains reasonable performance in multi-user environments. Locks acquired for querying (reading) data do not conflict with locks acquired for writing data. + +## Lock modes + +Cloudberry Database provides multiple lock modes to control concurrent access to data in tables. Most Cloudberry Database SQL commands automatically acquire the appropriate locks to ensure that referenced tables are not dropped or modified in incompatible ways while a command runs. For applications that cannot adapt easily to MVCC behavior, you can use the `LOCK` command to acquire explicit locks. However, proper use of MVCC generally provides better performance. + +|Lock Mode|Associated SQL Commands|Conflicts With| +|---------|-----------------------|--------------| +|ACCESS SHARE|`SELECT`|ACCESS EXCLUSIVE| +|ROW SHARE|`SELECT...FOR lock_strength`|EXCLUSIVE, ACCESS EXCLUSIVE| +|ROW EXCLUSIVE|`INSERT`, `COPY`|SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE, ACCESS EXCLUSIVE| +|SHARE UPDATE EXCLUSIVE|`ANALYZE`|SHARE UPDATE EXCLUSIVE, SHARE, EXCLUSIVE, ACCESS EXCLUSIVE| +|SHARE|`CREATE INDEX`|ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE ROW EXCLUSIVE, EXCLUSIVE, ACCESS EXCLUSIVE| +|SHARE ROW EXCLUSIVE| |ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE, ACCESS EXCLUSIVE| +|EXCLUSIVE|`DELETE`, `UPDATE`, `SELECT...FOR lock_strength`, `REFRESH MATERIALIZED VIEW CONCURRENTLY`|ROW SHARE, ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE, ACCESS EXCLUSIVE| +|ACCESS EXCLUSIVE|`ALTER TABLE`, `DROP TABLE`, `TRUNCATE`, `REINDEX`, `CLUSTER`, `REFRESH MATERIALIZED VIEW` (without `CONCURRENTLY`), `VACUUM FULL`|ACCESS SHARE, ROW SHARE, ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE, ACCESS EXCLUSIVE| + +:::info +By default, the Global Deadlock Detector is deactivated, and Cloudberry Database acquires the more restrictive `EXCLUSIVE` lock (rather than `ROW EXCLUSIVE` in PostgreSQL) for `UPDATE` and `DELETE`. + +When the Global Deadlock Detector is enabled: + +- The lock mode for some `DELETE` and `UPDATE` operations on heap tables is `ROW EXCLUSIVE`. See [Global Deadlock Detector]](#global-deadlock-detector). +::: + +## Global Deadlock Detector + +The Cloudberry Database Global Deadlock Detector background worker process collects lock information on all segments and uses a directed algorithm to detect the existence of local and global deadlocks. This algorithm allows Cloudberry Database to relax concurrent update and delete restrictions on heap tables. (Cloudberry Database still employs table-level locking on AO/CO tables, restricting concurrent `UPDATE`, `DELETE`, and `SELECT...FOR lock_strength` operations.) + +By default, the Global Deadlock Detector is deactivated and Cloudberry Database runs the concurrent `UPDATE` and `DELETE` operations on a heap table serially. You can activate these concurrent updates and have the Global Deadlock Detector determine when a deadlock exists by setting the parameter `gp_enable_global_deadlock_detector` in the `postgresql.conf` configuration file to `on` and then restarting the database. + +When the Global Deadlock Detector is enabled, the background worker process is automatically started on the coordinator host when you start Cloudberry Database. You configure the interval at which the Global Deadlock Detector collects and analyzes lock waiting data via the `gp_global_deadlock_detector_period` server configuration parameter in the `postgresql.conf` configuration file. + +If the Global Deadlock Detector determines that deadlock exists, it breaks the deadlock by cancelling one or more backend processes associated with the youngest transaction(s) involved. + +When the Global Deadlock Detector determines a deadlock exists for the following types of transactions, only one of the transactions will succeed. The other transactions will fail with an error indicating that concurrent updates to the same row is not allowed. + +- Concurrent transactions on the same row of a heap table where the first transaction is an update operation and a later transaction runs an update or delete and the query plan contains a motion operator. +- Concurrent update transactions on the same distribution key of a heap table that are run by the Postgres-based planner. +- Concurrent update transactions on the same row of a hash table that are run by the GPORCA optimizer. + +> **Note** Cloudberry Database uses the interval specified in the `deadlock_timeout` server configuration parameter for local deadlock detection. Because the local and global deadlock detection algorithms differ, the cancelled process(es) may differ depending upon which detector (local or global) Cloudberry Database triggers first. + +> **Note** If the `lock_timeout` server configuration parameter is turned on and set to a value smaller than `deadlock_timeout` and `gp_global_deadlock_detector_period`, Cloudberry Database will cancel a statement before it would ever trigger a deadlock check in that session. + +To view lock waiting information for all segments, run the `gp_dist_wait_status()` user-defined function. You can use the output of this function to determine which transactions are waiting on locks, which transactions are holding locks, the lock types and mode, the waiter and holder session identifiers, and which segments are running the transactions. Sample output of the `gp_dist_wait_status()` function follows: + +```sql +SELECT * FROM pg_catalog.gp_dist_wait_status(); + +-[ RECORD 1 ]----+-------------- +segid | 0 +waiter_dxid | 11 +holder_dxid | 12 +holdTillEndXact | t +waiter_lpid | 31249 +holder_lpid | 31458 +waiter_lockmode | ShareLock +waiter_locktype | transactionid +waiter_sessionid | 8 +holder_sessionid | 9 +-[ RECORD 2 ]----+-------------- +segid | 1 +waiter_dxid | 12 +holder_dxid | 11 +holdTillEndXact | t +waiter_lpid | 31467 +holder_lpid | 31250 +waiter_lockmode | ShareLock +waiter_locktype | transactionid +waiter_sessionid | 9 +holder_sessionid | 8 +``` + +When it cancels a transaction to break a deadlock, the Global Deadlock Detector reports the following error message: + +``` +ERROR: canceling statement due to user request: "cancelled by global deadlock detector" +``` + +### Global Deadlock Detector UPDATE and DELETE compatibility + +The Global Deadlock Detector can manage concurrent updates for these types of `UPDATE` and `DELETE` commands on heap tables: + +- Simple `UPDATE` of a single table. Update a non-distribution key with the Postgres-based planner. The command does not contain a `FROM` clause, or a sub-query in the `WHERE` clause. + + ```sql + UPDATE t SET c2 = c2 + 1 WHERE c1 > 10; + ``` + +- Simple `DELETE` of a single table. The command does not contain a sub-query in the `FROM` or `WHERE` clauses. + + ```sql + DELETE FROM t WHERE c1 > 10; + ``` + +- Split `UPDATE`. For the Postgres-based planner, the `UPDATE` command updates a distribution key. + + ```sql + UPDATE t SET c = c + 1; -- c is a distribution key + ``` + + For GPORCA, the `UPDATE` command updates a distribution key or references a distribution key. + + ```sql + UPDATE t SET b = b + 1 WHERE c = 10; -- c is a distribution key + ``` + +- Complex `UPDATE`. The `UPDATE` command includes multiple table joins. + + ```sql + UPDATE t1 SET c = t1.c+1 FROM t2 WHERE t1.c = t2.c; + ``` + + Or the command contains a sub-query in the `WHERE` clause. + + ```sql + UPDATE t SET c = c + 1 WHERE c > ALL(SELECT * FROM t1); + ``` + +- Complex `DELETE`. A complex `DELETE` command is similar to a complex `UPDATE`, and involves multiple table joins or a sub-query. + + ```sql + DELETE FROM t USING t1 WHERE t.c > t1.c; + ``` + +The following table shows the concurrent `UPDATE` or `DELETE` commands that are managed by the Global Deadlock Detector. For example, concurrent simple `UPDATE` commands on the same table row are managed by the Global Deadlock Detector. For a concurrent complex `UPDATE` and a simple `UPDATE`, only one `UPDATE` is performed, and an error is returned for the other `UPDATE`. + +|Command|Simple `UPDATE`|Simple `DELETE`|Split `UPDATE`|Complex `UPDATE`|Complex `DELETE`| +|-------|---------------|---------------|--------------|----------------|----------------| +|Simple `UPDATE`|YES|YES|NO|NO|NO| +|Simple `DELETE`|YES|YES|NO|YES|YES| +|Split `UPDATE`|NO|NO|NO|NO|NO| +|Complex `UPDATE`|NO|YES|NO|NO|NO| +|Complex `DELETE`|NO|YES|NO|NO|YES| + +## See also + +- [Work with Transactions](/docs/work-with-transactions.md) +- [Insert, Update, and Delete Rows](/docs/insert-update-delete-rows.md) \ No newline at end of file diff --git a/docs/work-with-transactions.md b/docs/work-with-transactions.md new file mode 100644 index 000000000..246cb805a --- /dev/null +++ b/docs/work-with-transactions.md @@ -0,0 +1,61 @@ +--- +title: Work with Transactions +--- + +# Work with Transactions in Cloudberry Database + +Transactions allow you to bundle multiple SQL statements in one all-or-nothing operation. + +The following are the Cloudberry Database SQL transaction commands: + +- `BEGIN` or `START TRANSACTION` starts a transaction block. +- `END` or `COMMIT` commits the results of a transaction. +- `ROLLBACK` abandons a transaction without making any changes. +- `SAVEPOINT` marks a place in a transaction and enables partial rollback. You can roll back commands run after a savepoint while maintaining commands run before the savepoint. +- `ROLLBACK TO SAVEPOINT` rolls back a transaction to a savepoint. +- `RELEASE SAVEPOINT` destroys a savepoint within a transaction. + +## Transaction isolation levels + +Cloudberry Database accepts the standard SQL transaction levels as follows: + +- `READ UNCOMMITTED` and `READ COMMITTED` behave like the standard `READ COMMITTED`. +- `REPEATABLE READ` and `SERIALIZABLE` behave like `REPEATABLE READ`. + +The following information describes the behavior of the Cloudberry Database transaction levels. + +### Read uncommitted and read committed + +Cloudberry Database does not allow any command to see an uncommitted update in another concurrent transaction, so `READ UNCOMMITTED` behaves the same as `READ COMMITTED`. `READ COMMITTED` provides fast, simple, partial transaction isolation. `SELECT`, `UPDATE`, and `DELETE` commands operate on a snapshot of the database taken when the query started. + +A `SELECT` query: + +- Sees data committed before the query starts. +- Sees updates run within the transaction. +- Does not see uncommitted data outside the transaction. +- Can possibly see changes that concurrent transactions made if the concurrent transaction is committed after the initial read in its own transaction. + +Successive `SELECT` queries in the same transaction can see different data if other concurrent transactions commit changes between the successive queries. `UPDATE` and `DELETE` commands find only rows committed before the commands started. + +`READ COMMITTED` transaction isolation allows concurrent transactions to modify or lock a row before `UPDATE` or `DELETE` find the row. `READ COMMITTED` transaction isolation might be inadequate for applications that perform complex queries and updates and require a consistent view of the database. + +### Repeatable read and serializable + +`SERIALIZABLE` transaction isolation, as defined by the SQL standard, ensures that transactions that run concurrently produce the same results as if they were run one after another. If you specify `SERIALIZABLE` Cloudberry Database falls back to `REPEATABLE READ`. `REPEATABLE READ` transactions prevent dirty reads, non-repeatable reads, and phantom reads without expensive locking, but Cloudberry Database does not detect all serializability interactions that can occur during concurrent transaction execution. Concurrent transactions should be examined to identify interactions that are not prevented by disallowing concurrent updates of the same data. You can prevent these interactions by using explicit table locks or by requiring the conflicting transactions to update a dummy row introduced to represent the conflict. + +With `REPEATABLE READ` transactions, a `SELECT` query: + +- Sees a snapshot of the data as of the start of the transaction (not as of the start of the current query within the transaction). +- Sees only data committed before the query starts. +- Sees updates run within the transaction. +- Does not see uncommitted data outside the transaction. +- Does not see changes that concurrent transactions make. +- Successive `SELECT` commands within a single transaction always see the same data. +- `UPDATE`, `DELETE`, `SELECT FOR UPDATE`, and `SELECT FOR SHARE` commands find only rows committed before the command started. If a concurrent transaction has updated, deleted, or locked a target row, the `REPEATABLE READ` transaction waits for the concurrent transaction to commit or roll back the change. If the concurrent transaction commits the change, the `REPEATABLE READ` transaction rolls back. If the concurrent transaction rolls back its change, the `REPEATABLE READ` transaction can commit its changes. + +The default transaction isolation level in Cloudberry Database is `READ COMMITTED`. To change the isolation level for a transaction, declare the isolation level when you `BEGIN` the transaction or use the `SET TRANSACTION` command after the transaction starts. + +## See also + +- [Transactional Concurrency Control](/docs/transactional-concurrency-control.md) +- [Insert, Update, and Delete Rows](/docs/insert-update-delete-rows.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current.json b/i18n/zh/docusaurus-plugin-content-docs/current.json index ea3d8c0c9..557b65406 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current.json +++ b/i18n/zh/docusaurus-plugin-content-docs/current.json @@ -7,7 +7,7 @@ "message": "产品介绍", "description": "The label for category product introduction in sidebar docs" }, - "sidebar.docsbars.category.Deployment Guides": { + "sidebar.docsbars.category.Deploy and Build": { "message": "部署指南", "description": "The label for category deployment guides in sidebar docs" }, @@ -19,12 +19,20 @@ "message": "从源码编译安装", "description": "The label for category building CloudberryDB from source code in sidebar docs" }, - "sidebar.docsbars.category.Reference": { + "sidebar.docsbars.category.References": { "message": "参考指南", "description": "The label for category reference in sidebar docs" }, "sidebar.docsbars.category.SQL Statements": { "message": "SQL 语句", "description": "The label for category SQL statements in sidebar docs" + }, + "sidebar.docsbars.category.Create and Prepare": { + "message": "创建和准备数据库", + "description": "The label for category creating and preparing database in sidebar docs" + }, + "sidebar.docsbars.category.Operate with Data": { + "message": "数据操作", + "description": "The label for category data operations in sidebar docs" } } diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/basic-query-syntax.md b/i18n/zh/docusaurus-plugin-content-docs/current/basic-query-syntax.md new file mode 100644 index 000000000..5f927bbff --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/basic-query-syntax.md @@ -0,0 +1,62 @@ +--- +title: 基本查询语法 +--- + +# 基本查询语法 + +本文档介绍了 Cloudberry Database 的基本查询。 + +Cloudberry Database 是基于 PostgreSQL 和 Greenplum 开发的高性能、高并行的数据仓库。以下是一些基本查询语法的示例。 + +- `SELECT`：用于从数据库和表中检索数据。 + + ```sql + SELECT * FROM employees; -- 查询 employees 表中的所有数据。 + ``` + +- 条件查询 (`WHERE`)：基于特定条件过滤结果集。 + + ```sql + SELECT * FROM employees WHERE salary > 50000; -- 查询薪水超过 50,000 的员工信息。 + ``` + +- `ORDER BY`：用于按一个或多个列对查询结果进行排序。 + + ```sql + SELECT * FROM employees ORDER BY salary DESC; -- 按薪水降序排列员工信息。 + ``` + +- 聚合函数：用于从数据集中计算统计信息，例如 `COUNT`、`SUM`、`AVG`、`MAX`、`MIN`。 + + ```sql + SELECT AVG(salary) FROM employees; -- 计算员工的平均薪水。 + ``` + +- `GROUP BY`：与聚合函数一起使用，用于对结果集进行分组。 + + ```sql + SELECT department, COUNT(*) FROM employees GROUP BY department; -- 按部门统计员工数量。 + ``` + +- 限制结果数量 (`LIMIT`)：用于限制查询结果返回的行数。 + + ```sql + SELECT * FROM employees LIMIT 10; -- 仅查询前 10 个员工的信息。 + ``` + +- 连接查询 (`JOIN`)：用于基于相关列将两个或多个表的数据组合在一起。 + + ```sql + SELECT employees.name, departments.name + FROM employees + JOIN departments ON employees.department_id = departments.id; -- 查询员工及其对应的部门名称。 + ``` + +- 子查询：在另一个 SQL 查询中的嵌套查询。 + + ```sql + SELECT name FROM employees + WHERE department_id IN (SELECT id FROM departments WHERE location = 'New York'); -- 查询所有在纽约工作的员工。 + ``` + +以上只是 Cloudberry Database 基本查询语法的简要概述。Cloudberry Database 还提供更高级的查询和功能，帮助开发者执行复杂的数据操作和分析。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-linux-compile.md b/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-linux-compile.md new file mode 100644 index 000000000..f13a0fd4c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-linux-compile.md @@ -0,0 +1,265 @@ +--- +title: 在 Linux 上 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 在 Linux 系统上编译和安装 Cloudberry Database + +:::info +本文档来自 GitHub 仓库 [`cloudberrydb/cloudberrydb`](https://github.com/cloudberrydb/cloudberrydb/blob/main/readmes/README.Linux.md). +::: + +本文档分享如何在 Linux 系统（CentOS 7、RHEL 和 Ubuntu）上编译和安装 Cloudberry Database。请注意，本文档仅供开发人员在单节点环境中尝试 Cloudberry Database。**请勿将本文档用于生产环境**。 + +按照以下步骤设置开发环境： + +1. [克隆 GitHub 仓库](#第-1-步克隆-github-仓库)。 +2. [安装依赖项](#第-2-步安装依赖项)。 +3. [执行平台准备工作](#第-3-步执行平台准备工作)。 +4. [构建 Cloudberry Database](#第-4-步构建-cloudberry-database)。 +5. [验证集群](#第-5-步验证集群)。 + +## 第 1 步：克隆 GitHub 仓库 + +将 GitHub 仓库 `cloudberrydb/cloudberrydb` 克隆到目标机器： + +```shell +git clone https://github.com/cloudberrydb/cloudberrydb.git +``` + +## 第 2 步：安装依赖项 + +进入仓库目录，根据你的操作系统安装依赖项： + + + + +以下步骤在 CentOS 7 上测试通过。对于其他版本的 CentOS，这些步骤可能有效，但不能保证有效。 + +1. 执行 `cloudberrydb/cloudberrydb` 仓库下 `readmes` 目录中的 `README.CentOS.bash` 脚本。执行此脚本需要输入密码。然后，系统会自动下载一些必要的依赖项。 + + ```bash + cd cloudberrydb/readmes + ./README.CentOS.bash + ``` + +2. 安装配置所需的其他包。 + + ```bash + yum -y install R apr apr-devel apr-util automake autoconf bash bison bison-devel bzip2 bzip2-devel centos-release-scl curl flex flex-devel gcc gcc-c++ git gdb iproute krb5-devel less libcurl libcurl-devel libevent libevent-devel libxml2 libxml2-devel libyaml libzstd-devel libzstd make openldap openssh openssh-clients openssh-server openssl openssl-devel openssl-libs perl python3-devel readline readline-devel rsync sed sudo tar vim wget which xerces-c-devel zip zlib && \ + yum -y install epel-release + ``` + +3. 将 GNU Compiler Collection (GCC) 更新到 `devtoolset-10` 版本，以支持 C++ 14。 + + ```bash + yum install centos-release-scl + yum -y install devtoolset-10-gcc devtoolset-10-gcc-c++ devtoolset-10-binutils + scl enable devtoolset-10 bash + source /opt/rh/devtoolset-10/enable + echo "source /opt/rh/devtoolset-10/enable" >> /etc/bashrc + source /etc/bashrc + gcc -v + ``` + +4. 将 cmake3 链接到 cmake： + + ```bash + sudo ln -sf /usr/bin/cmake3 /usr/local/bin/cmake + ``` + + + + +1. 安装开发工具 Development Tools。 + + ```bash + sudo yum group install -y "Development Tools" + ``` + +2. 安装依赖项。 + + ```bash + sudo yum install -y epel-release + + sudo yum install -y apr-devel bison bzip2-devel cmake3 flex gcc gcc-c++ krb5-devel libcurl-devel libevent-devel libkadm5 libxml2-devel libzstd-devel openssl-devel perl-ExtUtils-Embed python3-devel python3-pip readline-devel xerces-c-devel zlib-devel + ``` + +3. 执行 `README.Rhel-Rocky.bash` 脚本安装更多依赖项。 + + ```bash + ~/cloudberrydb/readmes/README.Rhel-Rocky.bash + ``` + + + + +1. 执行 `readmes` 目录下的 `README.Ubuntu.bash` 脚本，以安装依赖项。 + + ```shell + # 执行该脚本需要输入密码。 + sudo ~/cloudberrydb/readmes/README.Ubuntu.bash + ``` + + :::info 提示 + - 当执行 `README.Ubutnu.bash` 脚本安装依赖项时，会提示你配置 Kerberos 的 `realm`。你可以输入任意 `realm`，因为这只是用于测试，而且在测试期间，系统会重新配置本地服务器/客户端。如果你想跳过此手动配置，请执行 `export DEBIAN_FRONTEND=noninteractive`。 + - 如果脚本下载安装包失败，请尝试使用另一个 Ubuntu 软件源。 + ::: + +2. 安装 GCC 10。Ubuntu 18.04 及以上版本应当使用 GCC 10 或以上版本： + + ```bash + # 安装 gcc-10 + sudo apt install software-properties-common + sudo add-apt-repository ppa:ubuntu-toolchain-r/test + sudo apt install gcc-10 g++-10 + sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 + ``` + + + + +## 第 3 步：执行平台准备工作 + +在操作系统上安装所有依赖项后，在构建 Cloudberry Database 之前你还需要执行一些平台准备工作。这些操作包括在平台上手动运行 `ldconfig`、创建 `gpadmin` 用户以及设置密码以启动 Cloudberry Database 并进行测试。 + +1. 确保将 `/usr/local/lib` 和 `/usr/local/lib64` 添加到 `/etc/ld.so.conf` 文件中。 + + ```bash + echo -e "/usr/local/lib \n/usr/local/lib64" >> /etc/ld.so.conf + ldconfig + ``` + +2. 创建 `gpadmin` 用户并设置 SSH 密钥。根据不同的操作系统手动创建 SSH 密钥，这样你就可以在不输入密码的情况下运行 `ssh localhost`。 + + + + + ```bash + useradd gpadmin # 创建 gpadmin 用户 + su - gpadmin # 切换到 gpadmin 用户 + ssh-keygen # 创建 SSH 密钥 + cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys + chmod 600 ~/.ssh/authorized_keys + exit + ``` + + + + + ```bash + useradd -r -m -s /bin/bash gpadmin # 创建 gpadmin 用户 + su - gpadmin # 切换到 gpadmin 用户 + ssh-keygen # 创建 SSH 密钥 + cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys + chmod 600 ~/.ssh/authorized_keys + exit + ``` + + + + +## 第 4 步：构建 Cloudberry Database + +安装完所有依赖项并执行了平台准备工作后，你就可以开始构建 Cloudberry Database 了。按顺序执行以下命令。 + +1. 进入 `cloudberrydb` 目录，执行 `configure` 脚本。 + + ```bash + cd cloudberrydb + ./configure --with-perl --with-python --with-libxml --with-gssapi --prefix=/usr/local/cloudberrydb + ``` + + :::info 提示 + Cloudberry Database 默认使用 GPORCA 构建。如果你希望构建出不使用 GPORCA 的 Cloudberry Database，请在 `./configure` 命令中添加 `--disable-orca` 参数。 + + ```bash + ./configure --disable-orca --with-perl --with-python --with-libxml --prefix=/usr/local/cloudberrydb + ``` + + ::: + +2. 编译源码并安装数据库。 + + ```bash + make -j8 + make -j8 install + ``` + +3. 将 Greenplum 环境引入运行中的 shell。 + + ```bash + cd .. + cp -r cloudberrydb/ /home/gpadmin/ + cd /home/gpadmin/ + chown -R gpadmin:gpadmin cloudberrydb/ + su - gpadmin + cd cloudberrydb/ + source /usr/local/cloudberrydb/greenplum_path.sh + ``` + +4. 启动示例集群。 + + + + + ```bash + scl enable devtoolset-10 bash + source /opt/rh/devtoolset-10/enable + make create-demo-cluster + ``` + + + + + ```bash + make create-demo-cluster + ``` + + + + +5. 执行以下命令，以准备测试。此命令将为测试配置端口和环境变量。 + + 该命令会配置端口和环境变量，例如 `PGPORT`（主节点的默认端口）和 `COORDINATOR_DATA_DIRECTORY`（主节点的数据目录）。 + + ```bash + source gpAux/gpdemo/gpdemo-env.sh + ``` + +## 第 5 步：验证集群 + +1. 你可以通过以下命令来验证集群是否已成功启动。如果成功启动，你会看到端口在 `7000` 到 `7007` 之间的多个 `postgres` 进程。 + + ```bash + ps -ef | grep postgres + ``` + +2. 连接至 Cloudberry Database，通过查询系统表 `gp_segement_configuration` 查看活跃 segment 的信息。有关此系统表的详细描述，参见 [Greenplum 文档](https://docs.vmware.com/en/VMware-Greenplum/7/greenplum-database/ref_guide-system_catalogs-gp_segment_configuration.html)。 + + ```sql + $ psql -p 7000 postgres + psql (14.4, server 14.4) + Type "help" for help. + + postgres=# select version(); + version + ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + PostgreSQL 14.4 (Cloudberry Database 1.0.0+1c0d6e2224 build dev) on x86_64( GCC 13.2.0) 13.2.0, 64-bit compiled on Sep 22 2023 10:56:01 + (1 row) + + postgres=# select * from gp_segment_configuration; + dbid | content | role | preferred_role | mode | status | port | hostname | address | datadir | warehouseid + ------+---------+------+----------------+------+--------+------+------------+------------+------------------------------------------------------------------------------+------------- + 1 | -1 | p | p | n | u | 7000 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/qddir/demoDataDir-1 | 0 + 8 | -1 | m | m | s | u | 7001 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/standby | 0 + 3 | 1 | p | p | s | u | 7003 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1 | 0 + 6 | 1 | m | m | s | u | 7006 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1 | 0 + 2 | 0 | p | p | s | u | 7002 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0 | 0 + 5 | 0 | m | m | s | u | 7005 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0 | 0 + 4 | 2 | p | p | s | u | 7004 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2 | 0 + 7 | 2 | m | m | s | u | 7007 | i-6wvpa9wt | i-6wvpa9wt | /home/gpadmin/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2 | 0 + (8 rows) + ``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-macos-compile.md b/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-macos-compile.md index 03bf764ed..fe11e0e83 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-macos-compile.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cbdb-macos-compile.md @@ -5,7 +5,7 @@ title: 在 macOS 上 # 在 macOS 上编译和安装 Cloudberry Database :::info 提示 -本文档来自 GitHub 仓库 [cloudberrydb/cloudberrydb](https://github.com/cloudberrydb/cloudberrydb/blob/main/readmes/README.macOS.md)。 +本文档来自 GitHub 仓库 [`cloudberrydb/cloudberrydb`](https://github.com/cloudberrydb/cloudberrydb/blob/main/readmes/README.macOS.md)。 ::: 本文档分享了如何在 macOS 上（单节点）构建、编译和安装 Cloudberry Database 以供开发测试使用。请按照以下步骤操作。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/connect-to-cbdb.md b/i18n/zh/docusaurus-plugin-content-docs/current/connect-to-cbdb.md new file mode 100644 index 000000000..d87d81cb8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/connect-to-cbdb.md @@ -0,0 +1,117 @@ +--- +title: 连接到数据库 +--- + +# 连接到 Cloudberry Database + +本文档介绍如何连接到 Cloudberry Database。 + +## 连接参数 + +你可以使用与 PostgreSQL 兼容的客户端程序（例如 `psql`）连接到 Cloudberry Database。用户和管理员总是通过 *coordinator* 连接到 Cloudberry Database。Segment 不接受客户端连接。 + +为了建立与 Cloudberry Database coordinator 的连接，你需要了解以下连接信息，并相应地配置你的客户端程序。 + +|连接参数|描述|环境变量| +|--------|----|-------| +|应用程序名|连接到数据库的应用程序名称。在 `application_name` 连接参数中的默认值是 *psql*。|`$PGAPPNAME`| +|数据库名|待连接数据库的名称。对于新初始化的系统，首次连接请使用 `postgres` 数据库。|`$PGDATABASE`| +|主机名|Cloudberry Database coordinator 的主机名。默认主机是本地主机。|`$PGHOST`| +|端口|Cloudberry Database coordinator 实例运行的端口号。默认值为 `5432`。|`$PGPORT`| +|用户名|连接的数据库用户（角色）名称。这不一定与你的操作系统用户名相同。如果你不确定你的数据库用户名是什么，请与你的 Cloudberry 管理员联系。请注意，每个 Cloudberry Database 系统在初始化时都会自动创建一个超级用户帐户。此帐户的名称与初始化 Cloudberry 系统的用户的操作系统名称相同（通常为 `gpadmin`）。|`$PGUSER`| + +[使用 psql 连接](#使用-psql-连接) 介绍了连接到 Cloudberry Database 的示例命令。 + +## 支持的客户端应用程序 + +你可以使用多种客户端应用程序连接到 Cloudberry Database： + +- Cloudberry 安装中包含了一些[客户端应用程序](#客户端应用程序)。在这些应用程序中，`psql` 是一个交互式命令行界面。 +- 使用标准的[数据库应用程序接口](#使用应用程序接口连接)，例如 ODBC 和 JDBC，你可以创建自己的客户端应用程序，与 Cloudberry Database 进行连接。 +- 大多数使用标准数据库接口（例如 ODBC 和 JDBC）的客户端工具，都可以配置为连接到 Cloudberry Database。 + +### 客户端应用程序 + +Cloudberry Database 的安装中，随附包含了一些客户端工具应用程序，位于 coordinator 主机安装的 `$GPHOME/bin` 目录下。以下是最常用的客户端应用程序： + +|名称|用途| +|----|---| +|`createdb`|创建新的数据库| +|`createuser`|定义新的数据库角色| +|`dropdb`|删除数据库| +|`dropuser`|删除角色| +|`psql`|PostgreSQL 交互终端| +|`reindexdb`|对数据库进行重新索引| +|`vacuumdb`|收集并分析数据库的垃圾| + +使用这些客户端应用程序时，您必须通过 coordinator 实例连接到数据库。您需要知道目标数据库的名称、coordinator 的主机名和端口号，以及要连接的数据库用户名。你可以在连接命令上中使用 `-d`、`-h`、`-p` 和 `-U` 选项分别指定这些信息。如果没有为某个参数显示指定选项，数据库将首先使用数据库名称来作为该参数的默认值。 + +所有这些选项都有默认值，如果未指定选项，则使用这些默认值：默认主机是本地主机 localhost。默认端口号是 `5432`。默认用户名是操作系统的用户名称，数据库名称也是如此。请注意，操作系统用户名和 Cloudberry Database 用户名不一定相同。 + +如果默认值不正确，您可以适当设置环境变量 `PGDATABASE`、`PGHOST`、`PGPORT` 和 `PGUSER` 的值，或使用 `psql` 的 `~/.pgpass` 文件来保存经常使用的密码。 + +### 使用 psql 连接 + +根据默认值或你设置的环境变量，使用 `psql` 访问数据库，示例如下： + +```shell +$ psql -d gpdatabase -h coordinator_host -p 5432 -U `gpadmin` +``` + +```shell +$ psql gpdatabase +``` + +```shell +$ psql +``` + +如果尚未创建用户定义的数据库，你可以先连接到 `postgres` 数据库来访问系统。例如： + +```shell +$ psql postgres +``` + +连接到数据库后，`psql` 展示了一个提示符，提示符后面是 `psql` 当前连接的数据库名称，后面跟着字符串 `=>`（如果你是数据库超级用户则为 `=#`）。例如： + +```shell +gpdatabase=> +``` + +在提示符中，你可以输入 SQL 命令。为了将 SQL 命令发送到服务器并运行，SQL 命令必须以 `;`（分号）结尾。例如： + +```sql +=> SELECT * FROM mytable; +``` + +## 使用应用程序接口连接 + +你可能希望开发自己的客户端应用程序与 Cloudberry Database 进行交互。PostgreSQL 为最常用的数据库应用程序编程接口（API）提供了一系列数据库驱动程序，这些驱动程序也可以与 Cloudberry Database 一起使用。这些驱动程序需要单独下载。 + +每个驱动程序（除了随 PostgreSQL 一起提供的 `libpq`）都是独立的 PostgreSQL 开发项目。你需要下载、安装并配置这些应用程序，才能连接到 Cloudberry Database。这些驱动程序如下： + +|API|PostgreSQL 驱动程序|下载链接| +|---|------------------|-------| +|ODBC|psqlODBC|[psqlODBC - PostgreSQL ODBC 驱动程序](https://odbc.postgresql.org/)| +|JDBC|pgjdbc|[PostgreSQL JDBC 驱动程序](https://jdbc.postgresql.org/)| +|Perl DBI|pgperl|[DBD-Pg](https://metacpan.org/release/DBD-Pg)| +|Python DBI|pygresql|[PyGreSQL](http://www.pygresql.org/)| +|Python DBI|psycopg2|[Psycopg](https://www.psycopg.org/)| +|libpq C 库|libpq|[libpq - C 库](https://www.postgresql.org/docs/12/libpq.html)| + +使用 API 访问 Cloudberry Database 的通用说明是： + +1. 从适当来源下载你的编程语言平台和相应的 API。例如，你可以从 Oracle 获取 Java 开发工具包（JDK）和 JDBC API。 +2. 根据 API 规范，编写你的客户端应用程序。在编写应用程序时，请注意 Cloudberry Database 中的 SQL 支持，这样就不会包含不受支持的 SQL 语法。 + +下载适当的驱动程序并配置与你的 Cloudberry Database coordinator 实例的连接。 + +## 常见连接问题 + +有很多原因可能会导致客户端应用程序无法成功连接到 Cloudberry Database。以下表格介绍了连接问题的一些常见原因以及如何解决。 + +| 问题 | 解决方案 | +| ---- | -------- | +| 没有针对主机或用户的 `pg_hba.conf` 条目 | 要允许远程客户端连接到 Cloudberry Database，你需要配置 Cloudberry Database coordinator 实例以接受这些连接。这需要通过在 `pg_hba.conf` 配置文件（该文件位于 coordinator 实例的数据目录中）添加适当的条目来实现。 | +| Cloudberry Database 没有运行 | 如果 Cloudberry Database coordinator 实例停止运行，用户将无法连接。你可以通过在 Cloudberry coordinator 主机上运行 `gpstate` 实用程序来验证 Cloudberry Database 系统是否在运行。 | +| 网络问题：连接超时 | 如果用户从远程客户端连接到 Cloudberry coordinator 主机，网络问题可能会阻止连接（例如，DNS 主机名解析问题、主机系统关闭等）。为排除网络问题，请从远程客户端主机连接到 Cloudberry coordinator 主机。例如：`ping hostname`。

如果系统无法解析参与 Cloudberry Database 的主机的主机名和 IP 地址，查询和连接将会失败。某些操作会使用 `localhost` 连接到 Cloudberry Database coordinator，而其他操作则会使用实际的主机名，因此你必须能够解析这两者。如果你遇到这个错误，请首先确保你能够从 coordinator 主机通过网络连接到 Cloudberry Database 列表中的每个主机。在 coordinator 和所有 segment 的 `/etc/hosts` 文件中，确保你拥有 Cloudberry Database 列表中涉及的所有主机的正确主机名和 IP 地址。`127.0.0.1` 必须解析为 `localhost`。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/create-and-manage-database.md b/i18n/zh/docusaurus-plugin-content-docs/current/create-and-manage-database.md new file mode 100644 index 000000000..50bb7c4c6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/create-and-manage-database.md @@ -0,0 +1,7 @@ +--- +title: 创建和管理数据库 +--- + +# 创建和管理 Cloudberry Database + +当前内容正在准备中，敬请期待。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/insert-update-delete-rows.md b/i18n/zh/docusaurus-plugin-content-docs/current/insert-update-delete-rows.md new file mode 100644 index 000000000..72664dec4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/insert-update-delete-rows.md @@ -0,0 +1,7 @@ +--- +title: 插入、更新和删除行数据 +--- + +# 在 Cloudberry Database 中插入、更新和删除行数据 + +当前内容正在准备中，敬请期待。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/start-and-stop-cbdb-database.md b/i18n/zh/docusaurus-plugin-content-docs/current/start-and-stop-cbdb-database.md new file mode 100644 index 000000000..7eb12209a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/start-and-stop-cbdb-database.md @@ -0,0 +1,7 @@ +--- +title: 启动和停止数据库 +--- + +# 启动和停止 Cloudberry Database + +当前内容正在准备中，敬请期待。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/transactional-concurrency-control.md b/i18n/zh/docusaurus-plugin-content-docs/current/transactional-concurrency-control.md new file mode 100644 index 000000000..c6e1ccf7f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/transactional-concurrency-control.md @@ -0,0 +1,7 @@ +--- +title: 事务中的并发控制 +--- + +# Cloudberry Database 中的事务并发控制 + +当前内容正在准备中，敬请期待。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/work-with-transactions.md b/i18n/zh/docusaurus-plugin-content-docs/current/work-with-transactions.md new file mode 100644 index 000000000..4f59ac62f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/work-with-transactions.md @@ -0,0 +1,7 @@ +--- +title: 使用事务 +--- + +# 在 Cloudberry Database 中使用事务 + +当前内容正在准备中，敬请期待。 diff --git a/sidebars.js b/sidebars.js index 28bf336ee..816ec7c0c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -24,12 +24,12 @@ const sidebars = { { type: 'category', - label: 'Deployment Guides', + label: 'Deploy and Build', items: [ { type: 'category', label: 'Build from Source Code', - items: ['cbdb-macos-compile'] + items: ['cbdb-macos-compile','cbdb-linux-compile'] }, { type: 'category', @@ -41,7 +41,19 @@ const sidebars = { { type: 'category', - label: 'Reference', + label: 'Create and Prepare', + items: ['create-and-manage-database','start-and-stop-cbdb-database','connect-to-cbdb'] + }, + + { + type: 'category', + label: 'Operate with Data', + items: ['basic-query-syntax','insert-update-delete-rows','work-with-transactions','transactional-concurrency-control'] + }, + + { + type: 'category', + label: 'References', items: [ { type: 'category',